@orbat-mapper/tactical-draw 0.2.0-alpha.1 → 0.2.0-alpha.11

package/dist/index.d.mts

@@ -165,6 +165,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;
@@ -437,9 +446,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 +457,56 @@ 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;
+  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. `delete` is an explicit
+ * destructive mode: it renders the vertex handles (so they can be tapped to
+ * remove) but no midpoints or box, and the edit controller deletes the tapped
+ * vertex instead of dragging it.
+ */
+type EditMode = "reshape" | "transform" | "delete";
+//#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.setMembers([])`. `"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,7 +515,8 @@ 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. */
@@ -495,16 +537,20 @@ interface EditSession {
    */
   readonly sizeAnchor: SizeAnchor;
   /**
-   * Resolve the outer `edit` promise with a `ControlMeasureSnapshot` of the
-   * current working state.
+   * Commit: returns the `ControlMeasureSnapshot` 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(): ControlMeasureSnapshot | 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;
   /** Shallow-merge per-measure generator options into the live working copy. */
@@ -530,6 +576,47 @@ interface EditSession {
    * have run.
    */
   onChange(listener: (event: EditChangeEvent) => void): () => void;
+  /**
+   * Subscribe to the committed snapshot — the single delivery channel for the
+   * `ControlMeasureSnapshot` 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: ControlMeasureSnapshot) => 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.
@@ -558,13 +645,205 @@ interface EditChangeEvent {
   abort(): void;
 }
 //#endregion
+//#region src/tactical-draw/transform-session.d.ts
+/**
+ * Surface delivered via `td.editMany(measures, opts).onSession` and
+ * synchronously available from `td.activeTransformSession` while the group
+ * transform is live. The group sibling of `EditSession` (`edit-session.ts`):
+ * no reshape, no per-measure `setOptions`/`setStyle` — only the shared
+ * transform box's corner-scale / rotate / body-translate gestures, applied to
+ * every member at once. See the Phase 3 ("Multi-select") slice of ADR-0017.
+ *
+ * The member set is mutable via [[setMembers]] (#187): members can join or
+ * leave a live session without a session boundary. Because membership changes
+ * over the session's lifetime, snapshot arrays are keyed by **measure id**, not
+ * by index — a snapshot's identity is `snapshot.measure.id`. `measures` is a
+ * live view of the current members' join-time inputs; a `TransformChangeEvent`'s
+ * arrays are index-aligned with `session.measures` *as of that emission*. After
+ * the session settles (`close` / `abort` / an emptying `setMembers`), every
+ * method is a silent no-op (except [[onSettled]] — late registration still
+ * delivers, asynchronously).
+ */
+interface TransformSession {
+  /**
+   * Live view of the current members' join-time input measures — a fresh array
+   * on each read, in current membership order. Grows/shrinks as [[setMembers]]
+   * adds or removes members. Not stable across membership changes: key
+   * snapshots by `snapshot.measure.id` rather than relying on index alignment.
+   */
+  readonly measures: readonly ControlMeasure[];
+  /**
+   * Live working control points for the member whose id is `measureId`, or
+   * `undefined` when no member carries that id. Copy on read.
+   */
+  controlPointsFor(measureId: 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.
+   *
+   * `setMembers([])` on a live session delegates to [[close]]: it commits every
+   * current member, resolves the promise with their snapshots, and returns that
+   * same array. Duplicate ids in `measures` throw `TypeError` synchronously,
+   * without mutating session state.
+   */
+  setMembers(measures: readonly ControlMeasure[]): ControlMeasureSnapshot[] | undefined;
+  /**
+   * Commit: returns the members' `ControlMeasureSnapshot[]` (the members in the
+   * set at close time) and resolves the outer `editMany` promise with the same
+   * value (the same reference — no double-bake of ground-anchored sizes). A
+   * member removed mid-session via [[setMembers]] is not included here; its exit
+   * snapshot was returned from that `setMembers` call (and delivered to
+   * [[onCommit]] at that time). Returns `undefined` after the session has
+   * settled (idempotent no-op).
+   */
+  close(): ControlMeasureSnapshot[] | 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 `ControlMeasureSnapshot[]` this session ever commits (#191). Fires
+   * exactly once per batch:
+   *
+   * - The members [[setMembers]] removes, but only when that call actually
+   *   removed at least one member.
+   * - The close-time members on any commit path: [[close]], `setMembers([])`,
+   *   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
+   * `setMembers`/`close` call that produced the batch, before that call
+   * returns, and the array delivered here is the same reference that call
+   * returns (and, for the close batch, the same reference the `editMany`
+   * promise resolves with). This is the recommended single fold path for exit
+   * state — subscribe once in `onSession` and every committed snapshot, from
+   * either delivery site, arrives here exactly once; the `setMembers` return
+   * 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: ControlMeasureSnapshot[]) => 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 `measures` and `previous` are index-aligned with
+ * `session.measures` *as of this emission*. Key by `measure.id` rather than
+ * relying on index alignment across emissions. A `setMembers` call from within
+ * a listener takes effect immediately and supersedes this emission's
+ * `reject()` (the rollback baseline no longer matches the member set);
+ * `close()` and `abort()` still apply, against the new membership. See
+ * `EditChangeEvent` for the identical emission contract this mirrors.
+ */
+interface TransformChangeEvent {
+  /** Working state after the completed gesture, index-aligned with `session.measures` as of this emission. */
+  readonly measures: ControlMeasureSnapshot[];
+  /** State immediately before this gesture, index-aligned with `session.measures` as of this emission. */
+  readonly previous: ControlMeasureSnapshot[];
+  /** The session the event belongs to. */
+  readonly session: TransformSession;
+  /**
+   * Roll every member's working preview back to `previous` after all
+   * listeners have run. Multiple calls collapse to a single rollback.
+   * Overridden by `close()` or `abort()` if either is also called during this
+   * emission, and dropped if a listener called `session.setMembers` (the
+   * 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,6 +865,45 @@ 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
+   * `ControlMeasureSnapshot` 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: ControlMeasureSnapshot) => 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/tactical-draw.d.ts
@@ -637,11 +955,12 @@ 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). `"delete"` is exclusive: it collapses
+   * the set to vertex-tap removal only. An unknown mode throws `TypeError`.
    */
   modes?: readonly EditMode[];
   /**
@@ -655,8 +974,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 +990,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
@@ -699,8 +1046,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;
   /**
@@ -746,6 +1095,20 @@ declare class TacticalDraw {
    * `EditHandle` so the controller stays the single owner of edit state.
    */
   private activeEdit;
+  /**
+   * Tracked alongside `activeInteraction` whenever the interaction is a group
+   * transform (`editMany`). The `render()` / view-change paths need every
+   * member's id (to exclude all of them from reconcile) — mirrors `activeEdit`
+   * but for `TransformHandle`'s `measureIds` array.
+   */
+  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.onMeasurePick`. The
    * façade subscribes once to `adapter.onPick` per layer and routes events
@@ -764,6 +1127,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
@@ -789,6 +1153,21 @@ declare class TacticalDraw {
    * 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*
@@ -841,12 +1220,25 @@ 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>>;
   /**
@@ -858,8 +1250,69 @@ declare class TacticalDraw {
    * 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>;
+  /**
+   * Start an interactive group transform (multi-select) over `measures`
+   * (ADR-0017 "Multi-select" slice). Every member is lifted onto the shared
+   * preview layer; the box (corner scale, rotate grip, drag-anywhere body
+   * translate) applies rigidly to all of them at once. Returns a Promise that
+   * resolves with `ControlMeasureSnapshot[]` on `session.close()` and rejects
+   * with `TacticalDrawAbortError` on signal / Escape / destroy / preempt /
+   * `session.abort()`. Key the resolved snapshots by `snapshot.measure.id`:
+   * the member set is mutable (`session.setMembers`, #187) so snapshot arrays
+   * are id-keyed, not index-aligned with this input. The promise resolves with
+   * the members in the set at close time; a member removed mid-session had its
+   * exit snapshot returned from the `setMembers` call that removed it.
+   *
+   * `measures.length` must be >= 1; a single-element array behaves like an
+   * `edit` with only `transform` mode. Throws `TypeError` synchronously (before
+   * any preemption) for an empty array or duplicate ids.
+   *
+   * For a selection that changes over time (shift-click toggle, marquee
+   * replace), prefer [[syncTransformMembers]] over hand-rolling the
+   * 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<ControlMeasureSnapshot[]>;
+  /**
+   * One-call selection-sync: mutate the live group transform's member set in
+   * place, or start a fresh `editMany` when no transform is live (#191). This
+   * owns the "live session → `setMembers`, else → `editMany`" branch that every
+   * host otherwise hand-rolls against `activeTransformSession`.
+   *
+   * The facade knows session liveness synchronously — `activeTransformSessionRef`
+   * is cleared inside the settle path, before control returns to host code — so
+   * unlike a host's own `activeTransformSession ? setMembers : editMany` check,
+   * this can never observe a stale ref pointing at an already-settled session.
+   * The settled-race fall-through hosts had to hand-roll for that gap is owned
+   * here instead: a `setMembers` call that (implausibly) still returns
+   * `undefined` falls through to a fresh `editMany` rather than silently
+   * dropping the selection.
+   *
+   * `measures: []` closes any live session (committing every member) and is a
+   * no-op while idle. With a live session, `options` is ignored — session-scoped
+   * state (`sizeAnchor`, box angle, close-on-click-away policy) is sticky per
+   * `setMembers`'s contract; `options` applies only when this call starts a
+   * 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`.
+   */
+  syncTransformMembers(measures: readonly ControlMeasure[], options?: EditManyOptions): void;
   /**
    * Subscribe to picks on committed control measures.
    *
@@ -895,6 +1348,13 @@ declare class TacticalDraw {
    * fixed-length draws. Safe to read after `destroy()`.
    */
   get activeSession(): DrawSession | EditSession | 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 +1386,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
@@ -947,4 +1417,52 @@ declare class TacticalDrawDestroyedError extends Error {
   constructor(message?: string);
 }
 //#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 };
+//#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/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 EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type GuideStyle, type HandleStyle, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type 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, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, ignoreAbort, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, tryControlMeasureIdFromFeature };