@orbat-mapper/tactical-draw 0.2.0-alpha.3 → 0.2.0-alpha.31

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ControlMeasure, ControlMeasureKind, ControlMeasureSnapshot, ControlMeasureStyle } from "@orbat-mapper/control-measures";
+import { AmplifierPlacement, AmplifierPlacements, ControlMeasure, ControlMeasureKind, ControlMeasureRender, ControlMeasureStyle, FillPattern, TextAmplifiers } from "@orbat-mapper/control-measures";
 import { Feature, Position } from "geojson";
 
 //#region src/gestures/types.d.ts
@@ -12,6 +12,11 @@ interface PointerEventInfo {
    * mouse paths populate it; touch leaves it `undefined`.
    */
   altKey?: boolean;
+  /**
+   * Whether Shift was held for this pointer event. Rotation gestures use the
+   * live value to constrain transform-box angles to 15-degree increments.
+   */
+  shiftKey?: boolean;
   /** Engine-native event, for drivers that need to call preventDefault etc. */
   native?: unknown;
 }
@@ -35,6 +40,52 @@ interface EditPointerDriver {
   dispose(): void;
 }
 //#endregion
+//#region src/fill-pattern.d.ts
+/**
+ * Shared hatch fill-pattern tiles for area control-measure fills (ADR-0035
+ * `FillPattern`, excluding `"solid"` which every adapter already renders as a
+ * flat color). Both the MapLibre adapter (raster `addImage` pattern) and the
+ * OpenLayers adapter (canvas `Pattern` fill) need the *same* diagonal-hachure
+ * texture, so it is rasterized once here in pure math — no `HTMLCanvasElement`
+ * — so it works in adapter code and in jsdom/node tests alike.
+ */
+type HatchPattern = Exclude<FillPattern, "solid">;
+/**
+ * Every non-solid `FillPattern` as a runtime list — the value-level companion
+ * to {@link HatchPattern}, so adapters can test membership and build filter
+ * expressions without re-spelling the pattern vocabulary.
+ */
+declare const HATCH_PATTERNS: readonly HatchPattern[];
+/**
+ * Stable id for a rasterized tile, keyed by pattern and color. Adapters use
+ * this as the image-registry key (MapLibre `addImage` id, OpenLayers pattern
+ * cache key) so the same color+pattern never gets rasterized twice. Color is
+ * lowercased so `"#FF0000"` and `"#ff0000"` share one texture.
+ */
+declare function fillPatternImageId(color: string, pattern: HatchPattern): string;
+/**
+ * Tile edge length in device pixels for a given `pixelRatio`. Must be a power
+ * of two — MapLibre requires POT dimensions for seamless WebGL texture wrap —
+ * and scales linearly with `pixelRatio` for the ratios that matter in
+ * practice (1x/2x displays: 32 -> 64, both already POT). Non-POT products
+ * (e.g. a 3x ratio, 32*3=96) round up to the next POT rather than losing the
+ * power-of-two guarantee.
+ */
+declare function fillPatternImageDimension(pixelRatio: number): number;
+/**
+ * Rasterize one seamless hatch tile as a straight RGBA pixel buffer — no
+ * canvas involved, so this runs identically in a browser adapter and in
+ * jsdom/node tests. Diagonal lines are snapped to slope ±1 (45°) so the
+ * mod-based coverage math in {@link lineCoverage} tiles exactly. `"hachure"`
+ * draws the "/" diagonal, `"backhachure"` its "\" mirror, and `"cross"` unions
+ * both via `Math.max` coverage.
+ */
+declare function makeFillPatternImage(color: string, pattern: HatchPattern, pixelRatio?: number): {
+  width: number;
+  height: number;
+  data: Uint8ClampedArray;
+};
+//#endregion
 //#region src/map-adapter.d.ts
 type PixelCoordinate = [number, number];
 type MapCursor = "" | "default" | "crosshair" | "grab" | "grabbing" | "pointer";
@@ -54,6 +105,16 @@ interface StyleOptions {
   pointRadius?: number;
   text?: TextStyleOptions;
 }
+/**
+ * Text (label) style for a layer. When `labelProperty` is set, adapters also
+ * read per-feature label properties: `rotation` (radians, rendered as
+ * `π − rotation`), the size anchor's `textSizeMeters` (ground) or
+ * `textSizePixels` (screen) (ADR-0028), and `textAnchor` (`"start"` = text
+ * begins at the label point, `"end"` = text ends there; absent = centered).
+ * A ground-anchored label renders at
+ * `clamp(textSizeMeters / resolution, textSizeMinPixels, textSizeMaxPixels)`;
+ * a screen-anchored one at a constant `textSizePixels`, unclamped.
+ */
 interface TextStyleOptions {
   text?: string;
   labelProperty?: string;
@@ -62,6 +123,18 @@ interface TextStyleOptions {
   strokeColor?: string;
   strokeWidth?: number;
   rotation?: number;
+  /**
+   * Lower edge of the ground-anchored label clamp band (ADR-0028): text never
+   * renders below this pixel size, however far the view zooms out.
+   * @default 8
+   */
+  textSizeMinPixels?: number;
+  /**
+   * Upper edge of the ground-anchored label clamp band (ADR-0028): text never
+   * renders above this pixel size, however far the view zooms in.
+   * @default 24
+   */
+  textSizeMaxPixels?: number;
 }
 /**
  * Per-feature style for edit handles (vertex / midpoint / translate / rotate).
@@ -75,9 +148,25 @@ interface HandleStyle {
   strokeWidth?: number;
   strokeDash?: readonly number[];
   fillColor?: string;
+  /**
+   * How `fillColor` paints a filled part's interior. Absent or `"solid"` is
+   * today's flat fill; `"hachure"`/`"backhachure"`/`"cross"` request the shared hatch texture
+   * ({@link makeFillPatternImage}). Alpha rides in `fillColor` — there is no
+   * separate opacity field. Adapters that cannot rasterize a pattern degrade
+   * to solid. Per-feature only: layer-level `StyleOptions` has no equivalent.
+   */
+  fillPattern?: "solid" | HatchPattern;
   pointRadius?: number;
 }
 type LayerId = string;
+/** Canonical SVG resource shared by point features through `iconId`. */
+interface IconResource {
+  id: string;
+  svg: string;
+  width: number;
+  height: number;
+  anchor: [number, number];
+}
 /**
  * Click-style hit event delivered by {@link MapAdapter.onPick}.
  *
@@ -115,6 +204,8 @@ interface MapAdapter {
    * Set the style for a specific layer.
    */
   setLayerStyle(layerId: LayerId, style: StyleOptions): void;
+  /** Reconcile the layer's desired shared icon resources. */
+  reconcileLayerIconResources(layerId: LayerId, resources: readonly IconResource[]): void;
   /**
    * Set features on a vector layer.
    * Features should be standard GeoJSON Features.
@@ -143,6 +234,12 @@ interface MapAdapter {
    * silently ignored.
    */
   removeFeatures(layerId: LayerId, ids: readonly string[]): void;
+  /**
+   * Defer an upcoming removal from `layerId` until the most recent update to
+   * `updatedLayerId` has completed in the engine. Optional because synchronous
+   * adapters already make cross-layer write order visible atomically.
+   */
+  deferLayerRemovalUntilLayerUpdate?(layerId: LayerId, updatedLayerId: LayerId): void;
   /**
    * Subscribe to click-style "pick" events for a specific layer. Basemap and
    * other-layer clicks never fire the handler.
@@ -165,6 +262,15 @@ interface MapAdapter {
   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;
@@ -174,6 +280,11 @@ interface MapAdapter {
   toLonLat(coordinate: number[]): Position;
   fromLonLat(position: Position): number[];
   getPixelFromCoordinate(position: Position): PixelCoordinate | null;
+  /**
+   * Convert a viewport pixel to longitude/latitude. Optional so third-party
+   * adapters compiled against an older ABI remain valid.
+   */
+  getCoordinateFromPixel?(pixel: PixelCoordinate): Position | null;
   /**
    * Get current viewport size in CSS pixels.
    */
@@ -207,11 +318,23 @@ interface MapAdapter {
    * Get current map zoom level
    */
   getZoom(): number | undefined;
+  /**
+   * Get current view bearing, radians — the clockwise-from-north compass
+   * direction that screen-up points to (MapLibre-bearing semantics). `0` for
+   * engines/views that don't rotate.
+   */
+  getBearing(): number;
   /**
    * Listen for view changes (zoom/resolution)
    */
   onViewChange(handler: () => void): void;
   offViewChange(handler: () => void): void;
+  /**
+   * The engine evaluates the meters→pixels clamp for ground-sized point
+   * symbols inside its own style layer, so meters-sized point symbols don't
+   * need view-change re-renders for size.
+   */
+  readonly scalesGroundPointSymbolsNatively?: boolean;
   /**
    * Construct an {@link EditPointerDriver} for `TacticalDraw`'s edit
    * controller. The controller subscribes to pointer events on the returned
@@ -223,6 +346,13 @@ interface MapAdapter {
    * destruction.
    */
   destroy(): void;
+  /**
+   * Returns the features currently set on the layer — the adapter-side cache
+   * of the last `setLayerFeatures`/`updateLayerFeatures`/`removeFeatures`/
+   * `clearLayer` state. Empty array for an unknown layer. Callers must not
+   * mutate the returned array or features.
+   */
+  getLayerFeatures(layerId: LayerId): readonly Feature[];
 }
 //#endregion
 //#region src/base-map-adapter.d.ts
@@ -254,6 +384,8 @@ 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 layerIconResourceIds;
   private layerCounter;
   private destroyed;
   protected nextLayerId(): LayerId;
@@ -261,6 +393,7 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
     style?: StyleOptions;
   }): LayerId;
   removeLayer(layerId: LayerId): void;
+  reconcileLayerIconResources(layerId: LayerId, resources: readonly IconResource[]): void;
   setLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
   updateLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
   removeFeatures(layerId: LayerId, ids: readonly string[]): void;
@@ -275,6 +408,10 @@ 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 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;
@@ -297,6 +434,12 @@ 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
@@ -317,6 +460,52 @@ 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;
 //#endregion
 //#region src/gestures/hit-test.d.ts
 type ToPixel = (lonLat: Position) => PixelCoordinate | null;
@@ -331,7 +520,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;
@@ -366,6 +562,95 @@ 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;
+}
+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.
@@ -416,6 +701,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
@@ -437,9 +723,10 @@ declare function getSizeAnchor(measure: Pick<ControlMeasure, "kind" | "options">
 //#endregion
 //#region src/tactical-draw/handles.d.ts
 /**
- * Line-only style surface for the rubber-band guide (ADR-0004). Slot inside
- * `InteractionStyle.guide`. Applied as the guide layer's layer style by the
- * façade; not per-feature.
+ * Line-only style surface for the rubber-band guide (ADR-0004) and the
+ * transform-box outline. Slot inside `InteractionStyle.guide` /
+ * `InteractionStyle.boxOutline`. Applied as a layer style for the guide, and
+ * per-feature (`properties.style`) for the box outline — see ADR-0017.
  */
 interface GuideStyle {
   strokeColor?: string;
@@ -447,25 +734,96 @@ interface GuideStyle {
   strokeDash?: readonly number[];
 }
 /**
- * Unified interaction-affordance style surface (ADR-0006). One option object
- * for both the guide line and every handle slot. `guide` is delivered as a
- * layer style; handle slots ride per-feature on `properties.style`.
+ * Unified interaction-affordance style surface (ADR-0006, extended by
+ * ADR-0017 for the transform box). One option object for the guide line,
+ * the box outline, and every handle slot. `guide` and `boxOutline` are line
+ * styles; handle slots ride per-feature on `properties.style`.
  */
 interface InteractionStyle {
   guide?: GuideStyle;
   vertexHandle?: HandleStyle;
   midpointHandle?: HandleStyle;
-  translateHandle?: HandleStyle;
+  /** Visible grab target for a draggable rendered text label. */
+  labelHandle?: HandleStyle;
+  scaleHandle?: HandleStyle;
   rotateHandle?: HandleStyle;
+  boxOutline?: GuideStyle;
+  /**
+   * Pixel padding added on every side of the fitted transform box
+   * (`fitTransformBox`, ADR-0017) so the box doesn't tightly hug the rendered
+   * geometry. Default `0`. A scalar, not a style object, but it participates
+   * in the same built-in → façade → per-call resolution slot system as every
+   * other `InteractionStyle` field (see `TacticalDraw.resolveInteractionStyle`).
+   */
+  boxPadding?: number;
+}
+/**
+ * Reserved enum from PRD #40, replaced under ADR-0017 by the transform-box UI.
+ * `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. `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" | "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;
 }
 /**
- * Reserved enum from PRD #40. `reshape`, `translate`, and `rotate` produce
- * handles. `delete` is an explicit destructive mode: it renders the vertex
- * handles (so they can be tapped to remove) but no midpoint/translate/rotate
- * grips, and the edit controller deletes the tapped vertex instead of dragging
- * it. `scale` is reserved and throws elsewhere.
+ * 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 EditMode = "reshape" | "translate" | "rotate" | "scale" | "delete";
+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
 /**
@@ -474,17 +832,31 @@ type EditMode = "reshape" | "translate" | "rotate" | "scale" | "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. */
+  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[];
@@ -495,18 +867,24 @@ interface EditSession {
    */
   readonly sizeAnchor: SizeAnchor;
   /**
-   * Resolve the outer `edit` promise with a `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(): void;
+  close(): GraphicSnapshot<ControlMeasure> | undefined;
   /** Reject the outer `edit` promise with reason `"session"`. */
   abort(): void;
   /**
-   * Switch the active edit-mode set. `"reshape"`, `"translate"`, and `"rotate"`
-   * produce handles; `"delete"` is exclusive (vertex-tap removal) and collapses
-   * the set to delete-only. `"scale"` is rejected with `TypeError` per PRD #40.
+   * Switch the active edit-mode set. `"reshape"` produces vertex/midpoint
+   * handles; `"transform"` renders the oriented selection box (corner scale
+   * handles, rotate grip, body translate — ADR-0017); `"delete"` is exclusive
+   * (vertex-tap removal) and collapses the set to delete-only. An unknown mode
+   * 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;
   /**
@@ -518,6 +896,22 @@ interface EditSession {
   setSizeAnchor(anchor: SizeAnchor): 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
@@ -530,6 +924,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.
@@ -540,10 +997,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;
   /**
@@ -558,13 +1017,268 @@ 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(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.
+ *
+ * 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 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.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 workingGraphics: readonly Graphic[];
+  /**
+   * 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(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 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) 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 (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 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.
+   *
+   * 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 (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
+   * 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.
+   *
+   * `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 `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(): GraphicSnapshot[] | undefined;
+  /** Reject the outer `editMany` promise with reason `"session"`. */
+  abort(): void;
+  /**
+   * Subscribe to working-copy changes. The listener receives a
+   * [[TransformChangeEvent]] for each completed group gesture (corner scale,
+   * rotate, or body-translate drag end) — never on rubber-band ticks. All
+   * currently-registered listeners receive the same event instance, in
+   * registration order.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, aggregated otherwise). `event.reject()` /
+   * `event.close()` / `event.abort()` take effect only after all listeners
+   * have run — mirrors `EditSession.onChange` (issue #49).
+   */
+  onChange(listener: (event: TransformChangeEvent) => void): () => void;
+  /**
+   * Subscribe to committed exit-snapshot batches — the single delivery channel
+   * for every `GraphicSnapshot[]` this session ever commits (#191). Fires
+   * exactly once per batch:
+   *
+   * - The members [[setGraphics]] removes, but only when that call actually
+   *   removed at least one member.
+   * - The close-time members on any commit path: [[close]], `setGraphics([])`,
+   *   a click-away close, or `TransformChangeEvent.close()`.
+   *
+   * 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 `setGraphics` return
+   * value and the promise resolution are unchanged and remain valid for
+   * backward compatibility.
+   *
+   * 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: (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` and the members are no
+   *   longer excluded from `td.render()` reconciliation, 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 `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 {
+  /** 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.setGraphics` (the
+   * rollback baseline no longer matches the member set).
+   */
+  reject(): void;
+  /** Shortcut for `event.session.close()`, deferred until the emission ends. */
+  close(): void;
+  /** Shortcut for `event.session.abort()`, deferred until the emission ends. */
+  abort(): void;
+}
+//#endregion
 //#region src/tactical-draw/session.d.ts
 /**
  * Scoped surface delivered via `td.draw({ onSession })` for variable-length
  * 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. */
@@ -586,8 +1300,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
@@ -599,8 +1422,22 @@ interface TacticalDrawLayerOptions {
   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
@@ -621,6 +1458,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;
@@ -628,7 +1467,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
@@ -637,11 +1476,13 @@ interface EditOptions {
    */
   closeOnClickAway?: boolean;
   /**
-   * Active edit modes. Defaults to `["reshape"]`. `reshape` renders vertex /
-   * midpoint handles; `translate` renders a grip on the centroid pivot; and
-   * `rotate` renders a grip offset just outside the shape (so it has a lever
-   * arm and orbits with the geometry). The three can be combined freely.
-   * `"scale"` is reserved and throws.
+   * Active edit modes. Defaults to `["reshape", "transform"]`. `reshape`
+   * 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). `"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[];
   /**
@@ -655,8 +1496,10 @@ interface EditOptions {
    * polyline sourced from the working control points alongside the working
    * geometry preview. For `geometry === "area"` kinds, a separate
    * closing-segment `LineString` is also emitted once `workingPoints.length >= 3`.
-   * The guide is suppressed mechanically when `geometry === "point"` or
-   * `minCoordinates === maxCoordinates`, regardless of this flag. See ADR-0004.
+   * The guide is suppressed mechanically when `geometry === "point"`, and for
+   * fixed-length kinds (`minCoordinates === maxCoordinates` or `canonicalPointCount`
+   * set) unless the kind's draw rule opts back in via `showGuide`, regardless of
+   * this flag. See ADR-0004.
    */
   guide?: boolean;
   /**
@@ -669,6 +1512,32 @@ interface EditOptions {
    */
   sizeAnchor?: SizeAnchor;
 }
+/**
+ * Options for `TacticalDraw.editMany` — the multi-select group transform
+ * (ADR-0017 "Multi-select" slice). Leaner than `EditOptions`: there is no
+ * `modes` (a group transform is always the oriented box — no reshape), no
+ * `guide` (no rubber-band content for a group), and no per-measure `setOptions`
+ * / `setStyle` surface on the resulting session.
+ */
+interface EditManyOptions {
+  signal?: AbortSignal;
+  /**
+   * Called synchronously once when the group transform starts, before any
+   * pointer event is processed. Lets a host wire Done/Cancel/Delete buttons to
+   * the active session.
+   */
+  onSession?: (session: TransformSession) => void;
+  /**
+   * Default `true`. When `true`, a click on empty map (or on a graphics-layer
+   * measure outside the group) closes the active transform. Clicks on preview
+   * / handle features are consumed and keep it open.
+   */
+  closeOnClickAway?: boolean;
+  /** Per-call interaction style override scoped to this transform. See ADR-0006. */
+  interactionStyle?: InteractionStyle;
+  /** Size anchor for the committed measures (ADR-0020), applied group-wide. Default `"ground"`. */
+  sizeAnchor?: SizeAnchor;
+}
 /**
  * Draft control measure handed to `TacticalDraw.draw`. `kind` is required up
  * front so the façade can resolve metadata, draw rule, and controller choice
@@ -689,9 +1558,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;
   /**
@@ -699,8 +1572,10 @@ interface DrawOptions {
    * polyline alongside the kind's generator preview. For `geometry === "area"`
    * kinds, a separate closing-segment `LineString` is also emitted once the
    * total point count (cursor included) is ≥ 3. The guide is suppressed
-   * mechanically when `geometry === "point"` or `minCoordinates === maxCoordinates`,
-   * regardless of this flag. See ADR-0004.
+   * mechanically when `geometry === "point"`, and for fixed-length kinds
+   * (`minCoordinates === maxCoordinates` or `canonicalPointCount` set) unless
+   * the kind's draw rule opts back in via `showGuide`, regardless of this
+   * flag. See ADR-0004.
    */
   guide?: boolean;
   /**
@@ -736,6 +1611,9 @@ declare class TacticalDraw {
   private readonly graphicsStyle;
   private readonly defaultInteractionStyle;
   private readonly generateId;
+  private readonly pointSymbols;
+  private snappingOptions;
+  private readonly resolveSnap;
   private destroyed;
   private hasRendered;
   private readonly activeInteraction;
@@ -747,7 +1625,21 @@ declare class TacticalDraw {
    */
   private activeEdit;
   /**
-   * Host pick handlers registered via `td.onPick` / `td.onMeasurePick`. The
+   * 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 `graphicIds` array.
+   */
+  private activeTransform;
+  /**
+   * The live `TransformSession`, exposed via `activeTransformSession`. Set
+   * directly by `editMany`'s `onSession` wrapper (not routed through
+   * `ActiveInteractionTracker.session`, whose type is `DrawSession | EditSession`)
+   * and cleared on settle.
+   */
+  private activeTransformSessionRef;
+  /**
+   * 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).
@@ -764,6 +1656,7 @@ declare class TacticalDraw {
   private deferredGraphicsPick;
   private idCounter;
   private editCounter;
+  private transformCounter;
   /**
    * Snapshot of the host's last `render()` argument. The edit slice uses it
    * to recompute the graphics-layer state during a lift / restore — the
@@ -771,24 +1664,45 @@ declare class TacticalDraw {
    * surrounding collection state.
    */
   private lastRenderedMeasures;
+  private snapGeometryFeatures;
   constructor(adapter: MapAdapter, options?: TacticalDrawOptions);
+  /** Replace snapping configuration without recreating the map adapter or façade. */
+  setSnappingOptions(options?: SnappingOptions): void;
+  /** Clear transient host affordances when snapping or its interaction ends. */
+  private clearSnapResult;
   /**
    * Render `measures` into features and write them to the graphics layer.
    * Routes every measure through [[renderMeasureForAdapter]] so pixel sizing is
    * 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).
+   * `settleToGraphics` (no exclusion, the edit is ending).
    */
   private renderMeasuresToGraphics;
   /**
    * 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. 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.
    */
   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.
+   */
+  private excludedInteractionIds;
+  /**
+   * Live member ids of the active group transform, or `undefined` when none.
+   * Falls back to the session ref because `onSession` fires from inside the
+   * controller's attach, before `runWithSlot` has assigned `activeTransform` —
+   * the session ref is registered first (`trackTransformSession`), so a
+   * `render()` from inside `onSession` still sees live membership.
+   */
+  private transformMemberIds;
   /**
    * Reconcile the graphics layer against the authoritative list of measures.
    * Idempotent. Throws synchronously on duplicate measure ids *before*
@@ -814,7 +1728,7 @@ declare class TacticalDraw {
    * layers (the only edit-facing side effect, `notifyExternalMeasure`, is a
    * pure style replay).
    */
-  render(measures: readonly ControlMeasure[]): void;
+  render(measures: readonly Graphic[]): void;
   /**
    * Nested-call guard + preempt, shared by `draw` and `edit`. Returns a
    * pre-rejected promise when called re-entrantly from inside another
@@ -842,24 +1756,108 @@ declare class TacticalDraw {
    */
   private trackSession;
   /**
-   * 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()`.
+   * Wrap a host `onSession` callback for `editMany`, recording the session on
+   * `activeTransformSessionRef` (exposed via `activeTransformSession`) before
+   * the host's own handler runs. Separate from `trackSession` because
+   * `ActiveInteractionTracker.session` is typed `DrawSession | EditSession`.
    */
-  draw<K extends ControlMeasureKind>(draft: DrawMeasureDraft<K>, options?: DrawOptions): Promise<ControlMeasureSnapshot<K>>;
+  private trackTransformSession;
+  /**
+   * 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(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 `GraphicSnapshot<ControlMeasure>[]` on `session.close()` and rejects
+   * with `TacticalDrawAbortError` on signal / Escape / destroy / preempt /
+   * `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 `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 [[syncTransformGraphics]] over hand-rolling the
+   * live-session-vs-fresh-`editMany` branch, and subscribe to
+   * `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 ? 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 `setGraphics` call that (implausibly) still returns
+   * `undefined` falls through to a fresh `editMany` rather than silently
+   * dropping the selection.
+   *
+   * `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
+   * `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`. 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.
    *
@@ -871,7 +1869,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
@@ -883,6 +1881,47 @@ 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.
+   *
+   * `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 `mapEventHitTolerance(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()`.
@@ -894,7 +1933,14 @@ 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
+   * `TransformSession` isn't part of its `DrawSession | EditSession` union —
+   * see `activeTransformSessionRef`. Safe to read after `destroy()`.
+   */
+  get activeTransformSession(): TransformSession | null;
   /**
    * Tear down the façade. Releases only layer slots the façade created; host
    * supplied layer ids are left untouched. Safe to call multiple times. After
@@ -926,9 +1972,19 @@ declare class TacticalDraw {
   private applyGuideStyle;
   private baseGuideStyle;
   /**
-   * Resolve handle slots across built-in → façade → per-call with per-slot,
-   * per-property shallow merge. Explicit `undefined` at a higher-priority
-   * layer unsets the corresponding lower-priority field (ADR-0006).
+   * Resolve handle slots (plus `boxOutline`) across built-in → façade →
+   * per-call with per-slot, per-property shallow merge. Explicit `undefined`
+   * at a higher-priority layer unsets the corresponding lower-priority field
+   * (ADR-0006). `boxOutline` rides this same per-feature merge path (not the
+   * `guide` layer-style path) — the edit controller reads it off
+   * `properties.style` on the box outline `LineString` (ADR-0017).
+   *
+   * `boxPadding` is a scalar, not a mergeable style object, so it resolves
+   * separately with the same façade → per-call precedence and the same
+   * explicit-undefined-wins rule: a `boxPadding` key present at a
+   * higher-priority layer (even set to `undefined`) wins over a lower layer's
+   * value. There is no built-in `boxPadding` — an absent value at every layer
+   * falls through to the controllers' own `?? 0` default.
    *
    * Returns `undefined` only when no slot would carry any value — keeps the
    * downstream "no style on the feature" path intact for tests that assert
@@ -946,5 +2002,65 @@ 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
+/**
+ * The Excalidraw/Felt-style transform box: the oriented bounding box drawn
+ * around a selection, with 4 corner scale handles, a rotate grip above the
+ * top edge, and drag-anywhere-inside-the-box translate. This module is the
+ * single source of truth for box *placement* (`fitTransformBox`,
+ * `boxCorners`, `rotateGripPixel`) AND box *picking* (`pointInBox`,
+ * `pickBoxHandle`) — mirroring the ADR-0016 discipline that keeps
+ * `handles.ts` owning vertex/midpoint placement/pick. Everything here is pure
+ * pixel-space math: no projection, no rendering, no session state.
+ *
+ * **Angle convention**: `angle` is in radians, measured in screen pixel space
+ * (y grows downward). A positive angle rotates the box clockwise as drawn on
+ * screen — the same convention `rotatePointsAround` (`handle-drag.ts`) uses,
+ * so box rotation and control-point rotation stay in lockstep.
+ *
+ * **Corner ordering**: `boxCorners` always returns
+ * `[topLeft, topRight, bottomRight, bottomLeft]` in the box's own (unrotated)
+ * local frame, then rotated into place. "Top" means the smaller-y edge before
+ * rotation — i.e. the edge the rotate grip floats above. The order is stable
+ * across calls so a scale handle's `index` (0–3) always means the same
+ * corner, and its opposite corner is always `(index + 2) % 4`.
+ */
+interface TransformBox {
+  /** Box center, pixel space. */
+  center: PixelCoordinate;
+  /** Half-width along the box's local x-axis (pre-rotation), in pixels. */
+  halfWidth: number;
+  /** Half-height along the box's local y-axis (pre-rotation), in pixels. */
+  halfHeight: number;
+  /** Radians, screen space, positive = clockwise on screen. */
+  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`.
+ *
+ * Map engines that wrap pointer longitudes into [-180, 180] (OpenLayers'
+ * `toLonLat`, MapLibre's globe unproject) make positions jump ~360° when a
+ * gesture crosses the antimeridian. Adapters use this to keep delivered
+ * longitudes continuous with the view center, and to project coordinates on
+ * the world copy the view is actually looking at.
+ */
+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 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, bindAbortable, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, ignoreAbort, isTacticalDrawAbortError, 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 FeatureOps, 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 LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type SnapCandidate, type SnapCandidateProvider, type SnapCandidateRequest, type SnapInteraction, type SnapResult, type SnappingOptions, type StyleOptions, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextSizeProps, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, type TransientChangeEvent, type TransientPhase, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, effectivePointSymbolPixelSize, fillPatternImageDimension, fillPatternImageId, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, makeFillPatternImage, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pointSymbolFootprint, resizePointSymbolSize, resolveGroundTextSizePixels, resolveTextSizePixels, tryControlMeasureIdFromFeature };