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

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, TextAmplifiers } from "@orbat-mapper/control-measures";
 import { Feature, Position } from "geojson";
 
 //#region src/gestures/types.d.ts
@@ -54,6 +54,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 +72,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).
@@ -78,6 +100,14 @@ interface HandleStyle {
   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 +145,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.
@@ -165,6 +197,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;
@@ -207,6 +248,12 @@ 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)
    */
@@ -223,6 +270,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 +308,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 +317,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 +332,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 +358,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 +384,20 @@ 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;
 //#endregion
 //#region src/gestures/hit-test.d.ts
 type ToPixel = (lonLat: Position) => PixelCoordinate | null;
@@ -331,7 +412,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 +454,87 @@ declare class PointerCallbackHub {
   clear(): void;
 }
 //#endregion
+//#region src/point-symbol.d.ts
+type PointSymbolSize = {
+  value: number;
+  unit: "pixels";
+} | {
+  value: number;
+  unit: "meters";
+};
+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;
+//#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 +585,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 +607,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 +618,59 @@ 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. `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.
+ * 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
+/**
+ * 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/edit-session.d.ts
 /**
@@ -474,17 +679,29 @@ 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 {
   /** 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 +712,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 +741,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 +769,47 @@ 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;
 }
 /**
  * Delivered to `EditSession.onChange` listeners once per completed gesture.
@@ -541,9 +821,9 @@ interface EditSession {
  */
 interface EditChangeEvent {
   /** 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 +838,252 @@ interface EditChangeEvent {
   abort(): void;
 }
 //#endregion
+//#region src/tactical-draw/graphic-edit-session.d.ts
+interface GraphicEditChangeEvent<G extends Graphic = Graphic> {
+  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> {
+  /** 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.
+ *
+ * The member set is mutable via [[setGraphics]] (#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.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 {
+  /**
+   * 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 ControlMeasure[];
+  /**
+   * Live working control points for the member whose id is `graphicId`, or
+   * `undefined` when no member carries that id. Copy on read.
+   */
+  controlPointsFor(graphicId: string): readonly Position[] | undefined;
+  /** `true` when any member's working points differ 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.
+   * 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()`. */
+  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:
+   *
+   * - **Retained** members (id in both the current and next sets) carry their
+   *   current working state forward; the passed measure 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.
+   *
+   * **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.
+   *
+   * `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.
+   */
+  setGraphics(graphics: readonly ControlMeasure[]): GraphicSnapshot<ControlMeasure>[] | undefined;
+  /**
+   * Commit: returns the members' `GraphicSnapshot<ControlMeasure>[]` (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 [[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<ControlMeasure>[] | 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<ControlMeasure>[]` 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<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 (#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 {
+  /** Working state after the completed gesture, index-aligned with `session.graphics` as of this emission. */
+  readonly graphics: GraphicSnapshot<ControlMeasure>[];
+  /** State immediately before this gesture, index-aligned with `session.graphics` as of this emission. */
+  readonly previous: GraphicSnapshot<ControlMeasure>[];
+  /** 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/graphic-transform-session.d.ts
+interface GraphicTransformChangeEvent {
+  readonly graphics: GraphicSnapshot[];
+  readonly previous: GraphicSnapshot[];
+  readonly session: GraphicTransformSession;
+  reject(): void;
+  close(): void;
+  abort(): void;
+}
+interface GraphicTransformSession {
+  readonly graphics: readonly Graphic[];
+  readonly workingGraphics: readonly Graphic[];
+  readonly dirty: boolean;
+  close(): GraphicSnapshot[] | undefined;
+  abort(): void;
+  onChange(listener: (event: GraphicTransformChangeEvent) => void): () => void;
+  onCommit(listener: (snapshots: GraphicSnapshot[]) => void): () => void;
+  onSettled(listener: (reason: SettleReason) => void): () => 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 +1105,50 @@ 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;
 }
 //#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 +1160,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
@@ -628,7 +1203,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 +1212,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 +1232,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 +1248,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 | GraphicTransformSession) => 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
@@ -699,8 +1304,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 +1343,7 @@ declare class TacticalDraw {
   private readonly graphicsStyle;
   private readonly defaultInteractionStyle;
   private readonly generateId;
+  private readonly pointSymbols;
   private destroyed;
   private hasRendered;
   private readonly activeInteraction;
@@ -747,7 +1355,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 +1386,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
@@ -782,13 +1405,29 @@ declare class TacticalDraw {
   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 +1453,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
@@ -841,25 +1480,104 @@ declare class TacticalDraw {
    * (exposing it via `activeSession`) before the host's own handler runs.
    */
   private trackSession;
+  /**
+   * 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`.
+   */
+  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()`.
+   *
+   * For a variable-length draw, `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.
+   * Fixed-length kinds have no session and settle only through the promise.
    */
-  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(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 control-measure-only transform's
+   * member set in place, or start a fresh `editMany` when no compatible
+   * transform is live (#191). A selection containing a point symbol uses the
+   * unified graphic transform session, which does not yet support mutable
+   * membership; changing that selection preempts the current session and starts
+   * a new one, resetting its box angle and other session-local state.
+   *
+   * 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`.
    */
-  edit(measure: ControlMeasure, options?: EditOptions): Promise<ControlMeasureSnapshot>;
+  syncTransformGraphics(graphics: readonly Graphic[], options?: EditManyOptions): void;
   /**
    * Subscribe to picks on committed control measures.
    *
@@ -871,7 +1589,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 +1601,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 +1653,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 | GraphicTransformSession | 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 +1692,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 +1722,64 @@ 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[];
+}
+/** 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 GraphicRender, type GraphicSnapshot, type GraphicTransformChangeEvent, type GraphicTransformSession, type GuideStyle, type HandleStyle, type IconResource, type InteractionHit, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SettleReason, type SizeAnchor, type StyleOptions, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pointSymbolFootprint, resolveGroundTextSizePixels, tryControlMeasureIdFromFeature };