@orbat-mapper/tactical-draw 0.2.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,950 @@
+import { ControlMeasure, ControlMeasureKind, ControlMeasureSnapshot, ControlMeasureStyle } from "@orbat-mapper/control-measures";
+import { Feature, Position } from "geojson";
+
+//#region src/gestures/types.d.ts
+interface PointerEventInfo {
+  /** Per-event hit-tolerance override (e.g. larger for touch). */
+  hitTolerance?: number;
+  /**
+   * Whether the Alt/Option modifier was held for this pointer event. The edit
+   * controller reads this on pointer-down to turn a vertex hit into a delete
+   * (the GIS-standard Alt+click-to-delete gesture) instead of a drag. Only the
+   * mouse paths populate it; touch leaves it `undefined`.
+   */
+  altKey?: boolean;
+  /** Engine-native event, for drivers that need to call preventDefault etc. */
+  native?: unknown;
+}
+interface PointerCallback {
+  (pixel: PixelCoordinate, info?: PointerEventInfo): void;
+}
+/**
+ * Engine-agnostic pointer driver consumed by `TacticalDraw`'s edit controller.
+ * The controller owns handle rendering and hit-tests handles in lonLat space;
+ * the driver only carries raw pointer events, drag-pan toggle, and pixel
+ * projection.
+ */
+interface EditPointerDriver {
+  onPointerDown(cb: PointerCallback): () => void;
+  onPointerMove(cb: PointerCallback): () => void;
+  onPointerUp(cb: PointerCallback): () => void;
+  setDragPanEnabled(enabled: boolean): void;
+  toPixel(lonLat: Position): PixelCoordinate | null;
+  fromPixel(pixel: PixelCoordinate): Position;
+  /** Idempotent. */
+  dispose(): void;
+}
+//#endregion
+//#region src/map-adapter.d.ts
+type PixelCoordinate = [number, number];
+type MapCursor = "" | "default" | "crosshair" | "grab" | "grabbing" | "pointer";
+interface MapEvent {
+  type: string;
+  coordinate: Position;
+  pixel: PixelCoordinate;
+  originalEvent: unknown;
+}
+type MapEventHandler = (event: MapEvent) => void;
+interface StyleOptions {
+  strokeColor?: string;
+  strokeWidth?: number;
+  strokeDash?: number[];
+  fillColor?: string;
+  pointFillColor?: string;
+  pointRadius?: number;
+  text?: TextStyleOptions;
+}
+interface TextStyleOptions {
+  text?: string;
+  labelProperty?: string;
+  font?: string;
+  fillColor?: string;
+  strokeColor?: string;
+  strokeWidth?: number;
+  rotation?: number;
+}
+/**
+ * Per-feature style for edit handles (vertex / midpoint / translate / rotate).
+ * The producer (`TacticalDraw`) rides this on `properties.style`; the adapter
+ * reads it back when rendering the handle, so it is part of the adapter
+ * contract rather than the tactical-draw authoring surface. `pointRadius` is a
+ * UI affordance not present on `ControlMeasureStyle`. See ADR-0006.
+ */
+interface HandleStyle {
+  strokeColor?: string;
+  strokeWidth?: number;
+  strokeDash?: readonly number[];
+  fillColor?: string;
+  pointRadius?: number;
+}
+type LayerId = string;
+/**
+ * Click-style hit event delivered by {@link MapAdapter.onPick}.
+ *
+ * `id` is the control measure id, already split off the feature id by the
+ * adapter (see `controlMeasureIdFromFeature`).
+ *
+ * `originalEvent` is whatever the engine surfaces — OpenLayers normalises to
+ * `PointerEvent`, MapLibre delivers `MouseEvent`, Leaflet delivers
+ * `MouseEvent | TouchEvent`. Do not narrow to `PointerEvent` at the consumer.
+ */
+interface PickEvent {
+  id: string;
+  feature: Feature;
+  pixel: PixelCoordinate;
+  coordinate: Position;
+  originalEvent: MouseEvent | PointerEvent | TouchEvent;
+}
+type PickHandler = (event: PickEvent) => void;
+interface PickOptions {
+  signal?: AbortSignal;
+}
+interface MapAdapter {
+  /**
+   * Add a vector layer to the map.
+   * @returns unique layer ID
+   */
+  addVectorLayer(options?: {
+    style?: StyleOptions;
+  }): LayerId;
+  /**
+   * Remove a layer from the map.
+   */
+  removeLayer(layerId: LayerId): void;
+  /**
+   * Set the style for a specific layer.
+   */
+  setLayerStyle(layerId: LayerId, style: StyleOptions): void;
+  /**
+   * Set features on a vector layer.
+   * Features should be standard GeoJSON Features.
+   */
+  setLayerFeatures(layerId: LayerId, features: Feature[]): void;
+  /**
+   * Clear all features from a layer.
+   */
+  clearLayer(layerId: LayerId): void;
+  /**
+   * Reconcile features on a layer against the incoming set, keyed by `id`.
+   *
+   * Semantics:
+   *  - features with an `id` that already exists are updated in place;
+   *  - features with a fresh `id` are added;
+   *  - features in the layer whose `id` is missing from the incoming set are
+   *    removed.
+   *
+   * Features must carry a stable `id`. Use this when you can compute the
+   * complete desired state of a layer in one go; for partial removals use
+   * {@link removeFeatures}.
+   */
+  updateLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
+  /**
+   * Remove features by `id` from a layer. Ids that are not present are
+   * silently ignored.
+   */
+  removeFeatures(layerId: LayerId, ids: readonly string[]): void;
+  /**
+   * Subscribe to click-style "pick" events for a specific layer. Basemap and
+   * other-layer clicks never fire the handler.
+   *
+   * For control-measure features, adapters must set `PickEvent.id` to the
+   * originating control-measure id (not the rendered part's feature id).
+   * Features that do not satisfy the control-measure feature-id contract must
+   * be ignored rather than dispatched.
+   *
+   * Bound to the engine's tap-suppressing click event (OL `singleclick`,
+   * MapLibre `click`, Leaflet `click`) so the handler does not fire at the
+   * end of a pan or pinch-zoom gesture.
+   *
+   * Hit tolerance is pointer-type aware: 4 px for mouse/pen, 12 px for touch.
+   *
+   * Returns an unsubscribe function. The returned function and the optional
+   * `signal` are both honoured; either teardown path stops further events,
+   * and both are idempotent.
+   */
+  onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
+  /**
+   * Map Event Listeners
+   */
+  on(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
+  off(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
+  /**
+   * Projection / Coordinate Utilities
+   */
+  toLonLat(coordinate: number[]): Position;
+  fromLonLat(position: Position): number[];
+  getPixelFromCoordinate(position: Position): PixelCoordinate | null;
+  /**
+   * Get current viewport size in CSS pixels.
+   */
+  getViewportSize(): {
+    width: number;
+    height: number;
+  };
+  /**
+   * Pan the map by pixel delta.
+   * Positive delta means desired on-screen feature shift (right/down).
+   */
+  panByPixels(delta: PixelCoordinate, options?: {
+    durationMs?: number;
+  }): void;
+  /**
+   * Set the map viewport cursor. Pass an empty string to restore engine default styling.
+   */
+  setCursor(cursor: MapCursor): void;
+  /**
+   * Toggle the engine's native double-click-to-zoom gesture. `TacticalDraw`
+   * disables this for the lifetime of a variable-length draw so the commit
+   * `dblclick` doesn't also zoom the map.
+   */
+  setDoubleClickZoomEnabled(enabled: boolean): void;
+  /**
+   * Get current view resolution (meters per pixel at center or generally).
+   * returns undefined if not supported or not ready.
+   */
+  getResolution(): number | undefined;
+  /**
+   * Get current map zoom level
+   */
+  getZoom(): number | undefined;
+  /**
+   * Listen for view changes (zoom/resolution)
+   */
+  onViewChange(handler: () => void): void;
+  offViewChange(handler: () => void): void;
+  /**
+   * Construct an {@link EditPointerDriver} for `TacticalDraw`'s edit
+   * controller. The controller subscribes to pointer events on the returned
+   * driver to wire handle drags (vertex / midpoint / translate / rotate).
+   */
+  createEditPointerDriver(): EditPointerDriver;
+  /**
+   * Release all adapter-owned map resources. Adapters must not be used after
+   * destruction.
+   */
+  destroy(): void;
+}
+//#endregion
+//#region src/base-map-adapter.d.ts
+interface FeatureOps {
+  adds: Feature[];
+  updates: Feature[];
+  /** Features whose id was absent from the incoming set. */
+  removes?: Feature[];
+  full: Feature[];
+  replace?: boolean;
+}
+type NormalizedEventHandler = (lonLat: Position, pixel: PixelCoordinate, originalEvent: unknown) => void;
+interface NativeEventEntry<TEventToken> {
+  type: string;
+  token: TEventToken;
+}
+/**
+ * Abstract base class shared by all `MapAdapter` implementations.
+ *
+ * Owns shared bookkeeping (layer registry, feature cache, event-token
+ * tracking) and orchestrates the public methods over a small
+ * protected primitive surface that subclasses implement. See
+ * `docs/adr/0001-map-adapter-base-class.md` for the rationale, in particular
+ * around the `applyFeatureOps` primitive shape.
+ */
+declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> implements MapAdapter {
+  protected layers: Map<string, TLayerHandle>;
+  protected eventTokens: Map<MapEventHandler, NativeEventEntry<TEventToken>>;
+  protected viewChangeTokens: Map<() => void, TViewToken>;
+  protected featureCache: Map<string, Feature<import("geojson").Geometry, import("geojson").GeoJsonProperties>[]>;
+  protected featuresChangedListeners: Map<string, Set<(features: Feature[]) => void>>;
+  private layerCounter;
+  private destroyed;
+  protected nextLayerId(): LayerId;
+  addVectorLayer(options?: {
+    style?: StyleOptions;
+  }): LayerId;
+  removeLayer(layerId: LayerId): void;
+  setLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
+  updateLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
+  removeFeatures(layerId: LayerId, ids: readonly string[]): void;
+  abstract onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
+  abstract createEditPointerDriver(): EditPointerDriver;
+  clearLayer(layerId: LayerId): void;
+  on(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
+  off(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
+  onViewChange(handler: () => void): void;
+  offViewChange(handler: () => void): void;
+  destroy(): void;
+  protected emitLayerFeaturesChanged(layerId: LayerId, features: Feature[]): void;
+  protected onLayerFeaturesChanged(layerId: LayerId, listener: (features: Feature[]) => void): () => void;
+  protected destroyEngineResources(): void;
+  protected abstract createLayer(layerId: LayerId, style?: StyleOptions): TLayerHandle;
+  protected abstract destroyLayer(handle: TLayerHandle): void;
+  protected abstract applyFeatureOps(layerId: LayerId, ops: FeatureOps): void;
+  protected abstract attachNativeEvent(type: "click" | "pointermove" | "dblclick", onEvent: NormalizedEventHandler): NativeEventEntry<TEventToken>;
+  protected abstract detachNativeEvent(entry: NativeEventEntry<TEventToken>): void;
+  protected abstract attachViewChange(handler: () => void): TViewToken;
+  protected abstract detachViewChange(token: TViewToken): void;
+  abstract setLayerStyle(layerId: LayerId, style: StyleOptions): void;
+  abstract toLonLat(coordinate: number[]): Position;
+  abstract fromLonLat(position: Position): number[];
+  abstract getPixelFromCoordinate(position: Position): PixelCoordinate | null;
+  abstract getViewportSize(): {
+    width: number;
+    height: number;
+  };
+  abstract panByPixels(delta: PixelCoordinate, options?: {
+    durationMs?: number;
+  }): void;
+  abstract setCursor(cursor: MapCursor): void;
+  abstract setDoubleClickZoomEnabled(enabled: boolean): void;
+  abstract getResolution(): number | undefined;
+  abstract getZoom(): number | undefined;
+}
+//#endregion
+//#region src/pick-utils.d.ts
+declare function pickHitTolerance(originalEvent: unknown): number;
+declare function tryControlMeasureIdFromFeature(feature: Feature): string | null;
+/**
+ * Wire a subscription to honour both an optional AbortSignal and a returned
+ * dispose function. `attach` runs immediately (unless the signal is already
+ * aborted) and must return its own teardown function. The returned dispose is
+ * idempotent.
+ */
+declare function bindAbortable(signal: AbortSignal | undefined, attach: () => () => void): () => void;
+//#endregion
+//#region src/feature-style.d.ts
+/**
+ * Coerce a raw `properties.style` value into a `HandleStyle` for the
+ * per-feature interaction-affordance overlay (ADR-0006). Returns `undefined`
+ * when missing or shaped wrong so callers fall through to the layer style.
+ */
+declare function coerceHandleStyle(raw: unknown): HandleStyle | undefined;
+//#endregion
+//#region src/gestures/hit-test.d.ts
+type ToPixel = (lonLat: Position) => PixelCoordinate | null;
+/**
+ * Test whether `pixel` hits any feature in `features`, in pixel space.
+ *
+ * Hit semantics:
+ * - Point: within `hitTolerance` of the projected vertex
+ * - LineString / MultiLineString: within `hitTolerance` of any segment
+ * - Polygon / MultiPolygon: inside the projected ring, OR within
+ *   `hitTolerance` of a ring segment (so border hits work outside fill)
+ *
+ * Returns the first matching feature in iteration order, or null.
+ */
+declare function hitTestFeature(pixel: PixelCoordinate, features: Feature[], hitTolerance: number, toPixel: ToPixel): Feature | null;
+//#endregion
+//#region src/gestures/hit-tolerance.d.ts
+declare const TOUCH_HIT_TOLERANCE_PX = 22;
+//#endregion
+//#region src/gestures/pointer-callback-hub.d.ts
+/**
+ * The subscriber registry behind every {@link EditPointerDriver}.
+ *
+ * Each engine adapter sources pointer events differently — OpenLayers from
+ * unified DOM `PointerEvent`s, MapLibre and Leaflet from split mouse/touch
+ * streams — and each owns its own multi-touch capture FSM. What does *not*
+ * vary is the registry: three callback sets, the subscribe-returns-disposer
+ * contract, the snapshot-before-dispatch semantics, and teardown. That lived
+ * in four hand-rolled copies (the three adapters plus the test fake); it now
+ * lives here once.
+ *
+ * Adapters fan their normalized events in through {@link fireDown} /
+ * {@link fireMove} / {@link fireUp} and expose the `onPointer*` methods on
+ * their driver; teardown calls {@link clear}.
+ */
+declare class PointerCallbackHub {
+  private readonly downCbs;
+  private readonly moveCbs;
+  private readonly upCbs;
+  onPointerDown(cb: PointerCallback): () => void;
+  onPointerMove(cb: PointerCallback): () => void;
+  onPointerUp(cb: PointerCallback): () => void;
+  fireDown(pixel: PixelCoordinate, info?: PointerEventInfo): void;
+  fireMove(pixel: PixelCoordinate, info?: PointerEventInfo): void;
+  fireUp(pixel: PixelCoordinate, info?: PointerEventInfo): void;
+  /** Drop every subscriber. Idempotent; call from the driver's `dispose`. */
+  clear(): void;
+}
+//#endregion
+//#region src/tactical-draw/abort.d.ts
+/**
+ * AbortPlumbing for the TacticalDraw façade.
+ *
+ * Owns the abort contract for `TacticalDraw` so the rest of the façade
+ * (controllers, sessions) does not invent ad-hoc reason strings or error
+ * subclasses. See issue #43 / PRD #40.
+ */
+type TacticalDrawAbortReason = "escape" | "signal" | "preempted" | "destroyed" | "session" | "removed";
+interface TacticalDrawAbortErrorOptions {
+  cause?: unknown;
+  message?: string;
+}
+/**
+ * Façade abort error. Extends `DOMException` with `name: "AbortError"` so it
+ * still matches platform `AbortSignal` semantics and `instanceof DOMException`.
+ */
+declare class TacticalDrawAbortError extends DOMException {
+  readonly name: "AbortError";
+  readonly reason: TacticalDrawAbortReason;
+  constructor(reason: TacticalDrawAbortReason, options?: TacticalDrawAbortErrorOptions);
+}
+declare function isTacticalDrawAbortError(error: unknown): error is TacticalDrawAbortError;
+/**
+ * Swallow façade `TacticalDrawAbortError` *and* plain DOM `AbortError`s;
+ * rethrow every other value unchanged. Designed for use as
+ * `promise.catch(ignoreAbort)`.
+ */
+declare function ignoreAbort(error: unknown): void;
+/**
+ * Combined-signal handle returned by `combineWithHostSignal`. The façade uses
+ * `signal` for the live interaction and `abort` for programmatic cancellation
+ * with a closed-enum reason. `dispose` detaches the host-signal listener;
+ * controllers should call it when the interaction settles.
+ */
+interface CombinedAbort {
+  readonly signal: AbortSignal;
+  abort(reason: TacticalDrawAbortReason, cause?: unknown): void;
+  dispose(): void;
+}
+/**
+ * Compose the façade's internal abort controller with an optional host
+ * `AbortSignal`. Host aborts surface as `reason: "signal"` with the host's
+ * `signal.reason` on `error.cause`. An already-aborted host signal triggers
+ * a next-microtask abort (never synchronous), so callers can register await
+ * handlers before the rejection fires.
+ */
+declare function combineWithHostSignal(hostSignal?: AbortSignal): CombinedAbort;
+//#endregion
+//#region src/tactical-draw/measure-options.d.ts
+/**
+ * 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
+ * on zoom. `screen` means a pixel size held constant on screen — re-rendered
+ * against the live `metersPerPixel` on every view change. A draw/edit drawn in
+ * pixels resolves (`bakes`) to a `ground` anchor on commit unless the caller
+ * asks to stay `screen`.
+ */
+type SizeAnchor = "ground" | "screen";
+/**
+ * The [[SizeAnchor]] a measure currently encodes (ADR-0020): `screen` when it
+ * carries its kind's pixel-denominated size option, `ground` otherwise. Keys off
+ * the same `PIXEL_SIZE_OPTIONS` table as the bake, so a consumer deciding how to
+ * re-edit a graphic never has to re-derive the per-kind pixel-option knowledge
+ * (e.g. via a fragile key-name heuristic). Accepts the minimal `{ kind, options }`
+ * shape, mirroring [[measureUsesAdapterResolution]].
+ */
+declare function getSizeAnchor(measure: Pick<ControlMeasure, "kind" | "options">): SizeAnchor;
+//#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.
+ */
+interface GuideStyle {
+  strokeColor?: string;
+  strokeWidth?: number;
+  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`.
+ */
+interface InteractionStyle {
+  guide?: GuideStyle;
+  vertexHandle?: HandleStyle;
+  midpointHandle?: HandleStyle;
+  translateHandle?: HandleStyle;
+  rotateHandle?: HandleStyle;
+}
+/**
+ * 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.
+ */
+type EditMode = "reshape" | "translate" | "rotate" | "scale" | "delete";
+//#endregion
+//#region src/tactical-draw/edit-session.d.ts
+/**
+ * Surface delivered via `td.edit(measure, opts).onSession` and synchronously
+ * available from `td.activeSession` while the edit is live.
+ *
+ * `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.
+ */
+interface EditSession {
+  /** Immutable edit-start input. */
+  readonly measure: 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;
+  /** `true` after the first working-copy mutation; back to `false` within tolerance. */
+  readonly dirty: boolean;
+  readonly modes: readonly EditMode[];
+  /**
+   * Live size anchor for the measure under edit (ADR-0020). `"ground"` bakes a
+   * pixel size to meters on commit; `"screen"` keeps it zoom-aware. Initialised
+   * from `EditOptions.sizeAnchor` and mutated by [[setSizeAnchor]].
+   */
+  readonly sizeAnchor: SizeAnchor;
+  /**
+   * Resolve the outer `edit` promise with a `ControlMeasureSnapshot` of the
+   * current working state.
+   */
+  close(): void;
+  /** 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.
+   */
+  setModes(modes: readonly EditMode[]): void;
+  /** Shallow-merge per-measure generator options into the live working copy. */
+  setOptions(partial: ControlMeasure["options"]): void;
+  /**
+   * Flip the size anchor (ADR-0020). Takes effect on the next emitted snapshot
+   * and on `close()`. A no-op for measures with no pixel-denominated size. The
+   * in-flight preview is unaffected (it renders from the working options), so a
+   * screen-locked symbol stays screen-locked until commit.
+   */
+  setSizeAnchor(anchor: SizeAnchor): void;
+  /** Shallow-merge per-measure style into the live working copy. */
+  setStyle(partial: ControlMeasureStyle): void;
+  /**
+   * Subscribe to working-copy changes. The listener receives an
+   * [[EditChangeEvent]] for each completed gesture (drag end, insert/delete
+   * via handle) — 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.
+   */
+  onChange(listener: (event: EditChangeEvent) => void): () => void;
+}
+/**
+ * Delivered to `EditSession.onChange` listeners once per completed gesture.
+ *
+ * Listeners see the *same* event instance in registration order. Per-gesture
+ * effects (`reject`, `close`, `abort`) are recorded during emission and
+ * applied after every listener has run, so a downstream listener cannot
+ * observe partial state. See PRD #40 user-stories 23–24.
+ */
+interface EditChangeEvent {
+  /** Working state after the completed gesture. */
+  readonly measure: ControlMeasureSnapshot;
+  /** State immediately before this gesture. */
+  readonly previous: ControlMeasureSnapshot;
+  /** The session the event belongs to. */
+  readonly session: EditSession;
+  /**
+   * Roll the 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.
+   */
+  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.
+ */
+interface DrawSession {
+  /** Live snapshot of the committed control points. Copy on read. */
+  readonly controlPoints: readonly Position[];
+  /** `true` when the current point count is in `[min, max]`. */
+  readonly canCommit: boolean;
+  readonly minControlPoints: number;
+  readonly maxControlPoints?: number;
+  /**
+   * Commit if `canCommit` is true. Returns `false` (no-op) if not committable.
+   * On success resolves the outer `draw` promise on the next microtask.
+   */
+  commit(): boolean;
+  /** Reject the outer `draw` promise with reason `"session"`. */
+  abort(): void;
+  /**
+   * Subscribe to control-point add/remove changes. Rubber-band pointer ticks
+   * do not fire listeners. Returns an unsubscribe function. Listener errors
+   * are collected and rethrown after all listeners run.
+   */
+  onChange(listener: (session: DrawSession) => void): () => void;
+}
+//#endregion
+//#region src/tactical-draw/tactical-draw.d.ts
+/**
+ * Host-supplied layer slot ids. Any omitted slot is allocated by the façade and
+ * released on `destroy()`.
+ */
+interface TacticalDrawLayerOptions {
+  graphics?: LayerId;
+  preview?: LayerId;
+  guide?: LayerId;
+  handles?: LayerId;
+}
+interface TacticalDrawOptions {
+  layers?: TacticalDrawLayerOptions;
+  /**
+   * Façade-level default style passed through to `renderControlMeasure` as the
+   * third (lowest priority) style layer per StyleResolver (#44). Shallow-merged
+   * over `BUILT_IN_GRAPHICS_STYLE` so every map engine renders the same default
+   * appearance when neither the host nor the measure supplies a style.
+   */
+  graphicsStyle?: ControlMeasureStyle;
+  /**
+   * Façade-level default interaction-affordance style. Per-slot, per-property
+   * merged with `DrawOptions.interactionStyle` / `EditOptions.interactionStyle`
+   * on top of built-in defaults. The `guide` slot is delivered as a layer
+   * style on the guide layer; handle slots ride per-feature. See ADR-0006.
+   */
+  interactionStyle?: InteractionStyle;
+  /**
+   * Optional id generator for measures produced by `draw()`. Defaults to a
+   * monotonically increasing `td-${n}` slug. Caller-supplied measure ids on
+   * the draw API itself are deferred (PRD #40 user-story-5 note).
+   */
+  generateId?: () => string;
+}
+interface EditOptions {
+  signal?: AbortSignal;
+  /**
+   * 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;
+  /**
+   * Default `true`. When `true`, a click on empty map (or on another graphics
+   * layer measure) closes the active edit. Clicks on preview / handle
+   * features are consumed and keep the edit open. Hosts that own their own
+   * close policy pass `false`.
+   */
+  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.
+   */
+  modes?: readonly EditMode[];
+  /**
+   * Per-call interaction style override scoped to this edit. Per-slot,
+   * per-property merged over the façade-level default and the built-ins.
+   * See ADR-0006.
+   */
+  interactionStyle?: InteractionStyle;
+  /**
+   * When `true` (default), the preview layer carries a rubber-band guide
+   * 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.
+   */
+  guide?: boolean;
+  /**
+   * Size anchor for the committed measure (ADR-0020). Symmetric with
+   * `DrawOptions.sizeAnchor`: editing a screen-anchored graphic as `"ground"`
+   * bakes/freezes it to meters; editing a ground graphic whose working options
+   * have been switched to pixels as `"screen"` keeps the pixel size. Default
+   * `"ground"`. Applied to the resolved snapshot only — the in-flight preview
+   * stays screen-anchored throughout the edit.
+   */
+  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
+ * before any pointer event is observed. Everything else is optional and is
+ * stamped onto the in-flight preview and final committed measure (see slices
+ * 2-7).
+ */
+type DrawMeasureDraft<K extends ControlMeasureKind = ControlMeasureKind> = {
+  kind: K;
+} & Partial<Omit<ControlMeasure<K>, "kind" | "controlPoints">> & {
+  controlPoints?: readonly Position[];
+};
+/**
+ * Interaction-only options for `TacticalDraw.draw`. Measure data — seed
+ * points, per-kind options, style, properties — lives on the `DrawMeasureDraft`
+ * passed as the first argument.
+ */
+interface DrawOptions {
+  signal?: AbortSignal;
+  /**
+   * Called synchronously once when a variable-length draw starts, before any
+   * pointer event is processed. The session lets a host wire a Done/Cancel
+   * toolbar to the active draw. Ignored for fixed-length kinds.
+   */
+  onSession?: (session: DrawSession) => void;
+  /**
+   * When `true` (default), the preview layer carries a rubber-band guide
+   * 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.
+   */
+  guide?: boolean;
+  /**
+   * Per-call interaction style override scoped to this draw. Only the `guide`
+   * slot is meaningful for draws today — handle slots are reserved for the
+   * edit path. See ADR-0006.
+   */
+  interactionStyle?: InteractionStyle;
+  /**
+   * Size anchor for the committed measure (ADR-0020). `"ground"` (default)
+   * bakes any pixel-denominated size to meters at the finishing zoom, so the
+   * graphic becomes static. `"screen"` keeps the pixel size, so the graphic
+   * holds a constant on-screen size and is re-rendered on every zoom. Only
+   * meaningful for pixel-sizable kinds (FLOT, fortified, antitank); a no-op
+   * otherwise. Not persisted — the resulting options shape encodes the anchor.
+   */
+  sizeAnchor?: SizeAnchor;
+}
+/**
+ * `TacticalDraw` façade — slice #6 (issue #45).
+ *
+ * Provides the constructor + lifecycle + `render(measures)` reconcile path.
+ * Interactive draw and edit live in later slices; the shape is in place so
+ * the surface is stable.
+ */
+declare class TacticalDraw {
+  private readonly adapter;
+  private readonly graphicsLayer;
+  private readonly previewLayer;
+  private readonly guideLayer;
+  private readonly handlesLayer;
+  private readonly ownedLayers;
+  private readonly graphicsStyle;
+  private readonly defaultInteractionStyle;
+  private readonly generateId;
+  private destroyed;
+  private hasRendered;
+  private readonly activeInteraction;
+  /**
+   * Tracked alongside `activeInteraction` whenever the interaction is an edit. The
+   * `render()` path needs the edited measure's id (to exclude it from
+   * reconcile) and a hook to surface external style changes — both live on
+   * `EditHandle` so the controller stays the single owner of edit state.
+   */
+  private activeEdit;
+  /**
+   * Host pick handlers registered via `td.onPick` / `td.onMeasurePick`. 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).
+   */
+  private readonly hostPickHandlers;
+  private readonly adapterPickUnsubs;
+  /**
+   * Captured graphics-layer pick that arrived during an active edit on a
+   * *different* measure. The edit controller closes the active session and
+   * then asks the façade to re-dispatch this pick to host handlers so that
+   * `td.edit(otherMeasure)` from a host pick handler runs as a fresh edit,
+   * not as a programmatic preemption.
+   */
+  private deferredGraphicsPick;
+  private idCounter;
+  private editCounter;
+  /**
+   * Snapshot of the host's last `render()` argument. The edit slice uses it
+   * to recompute the graphics-layer state during a lift / restore — the
+   * façade owns the policy because controllers shouldn't need to know the
+   * surrounding collection state.
+   */
+  private lastRenderedMeasures;
+  constructor(adapter: MapAdapter, options?: TacticalDrawOptions);
+  /**
+   * Render `measures` into features and write them to the graphics layer.
+   * Routes every measure through [[renderMeasureForAdapter]] so pixel sizing is
+   * resolved against the live map. Callers own any edit-exclusion policy — see
+   * `render()` (excludes the edited measure, owned by the preview layer) versus
+   * `restoreOriginalToGraphics` (no exclusion, the edit is ending).
+   */
+  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.
+   */
+  private readonly handleViewChange;
+  /**
+   * Reconcile the graphics layer against the authoritative list of measures.
+   * Idempotent. Throws synchronously on duplicate measure ids *before*
+   * mutating any layer. An empty list before any prior render is a no-op.
+   *
+   * Cross-layer semantics with an active edit (issue #51):
+   *  - The measure under edit is **excluded** from the reconcile pass — the
+   *    preview layer owns its working copy and the lift on the graphics layer
+   *    must stay in place.
+   *  - If the edited measure is absent from `measures`, the pending `edit`
+   *    promise rejects on the **next microtask** with reason `"removed"`.
+   *    `render` itself returns normally so host collection ops stay synchronous.
+   *  - If the edited measure is present and its `style` changed, the preview
+   *    picks up the new style on this render. `controlPoints` changes on the
+   *    edited measure are routed nowhere — the user's in-flight drag is never
+   *    yanked out from under them.
+   *
+   * Cross-layer semantics with an active draw: `render` only touches the
+   * graphics layer, so the draw's preview is undisturbed.
+   *
+   * Reentrancy: calling `td.render(...)` from inside `EditSession.onChange` is
+   * safe — `render` never re-enters the active edit or its preview / handle
+   * layers (the only edit-facing side effect, `notifyExternalMeasure`, is a
+   * pure style replay).
+   */
+  render(measures: readonly ControlMeasure[]): void;
+  /**
+   * Nested-call guard + preempt, shared by `draw` and `edit`. Returns a
+   * pre-rejected promise when called re-entrantly from inside another
+   * interaction's `onSession` (the outer is still mid-construction, so the
+   * nested one is preempted synchronously — #52). Otherwise preempts whichever
+   * draw / edit is in flight and returns `null`, signalling the caller to
+   * proceed. One interaction at a time per PRD #40.
+   */
+  private guardAndPreempt;
+  /**
+   * Reserve the single interaction slot around `create`, shared by `draw` and
+   * `edit`. Reserves the active tracker (and `activeEdit` for edits) synchronously so
+   * `onSettled` callbacks see a coherent state; the handle's settle path calls
+   * the wrapped `onSettled` which clears the slot for us, avoiding the
+   * "promise.then(clearActive)" microtask gap that left the interaction set across
+   * re-dispatched pick handlers. The backstop `.then` covers a controller that
+   * settled synchronously (already-aborted signal returns a pre-settled handle),
+   * whose `onSettled` fired before `active` was assigned. `extraSettle` runs the
+   * caller's own teardown (guide-style revert, dbl-click-zoom re-enable).
+   */
+  private runWithSlot;
+  /**
+   * Wrap a host `onSession` callback so the session is recorded on the tracker
+   * (exposing it via `activeSession`) before the host's own handler runs.
+   */
+  private trackSession;
+  /**
+   * Start an interactive draw. Fixed-length kinds commit automatically on the
+   * last required click. Variable-length kinds surface a `DrawSession` via
+   * `opts.onSession` and commit on `session.commit()`, `dblclick`, or a second
+   * click on the last added control point. All paths reject with
+   * `TacticalDrawAbortError` on signal / Escape / destroy / `session.abort()`.
+   */
+  draw<K extends ControlMeasureKind>(draft: DrawMeasureDraft<K>, options?: DrawOptions): Promise<ControlMeasureSnapshot<K>>;
+  /**
+   * Start an interactive edit on a single control measure. Returns a Promise
+   * that resolves with a `ControlMeasureSnapshot` 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`.
+   */
+  edit(measure: ControlMeasure, options?: EditOptions): Promise<ControlMeasureSnapshot>;
+  /**
+   * Subscribe to picks on committed control measures.
+   *
+   * The graphics layer is pre-bound, and `event.id` is the originating control
+   * measure id. Events retain the same close-then-pick ordering as
+   * {@link onPick}: when another measure is picked during an active edit, the
+   * current edit closes before the handler runs.
+   *
+   * Returns an idempotent unsubscribe function. An optional `signal` removes
+   * the handler when aborted.
+   */
+  onMeasurePick(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
+   * sees a click on a *different* graphics-layer measure, the edit closes
+   * first and only then are pick events delivered to host handlers — letting
+   * a host `td.edit(other)` from a pick handler run as a fresh edit instead
+   * of a programmatic preemption.
+   *
+   * Returns an unsubscribe function. Optional `signal` mirrors `adapter.onPick`.
+   */
+  onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
+  /**
+   * Abort the in-flight draw or edit. The default `"session"` reason matches
+   * `DrawSession.abort()` / `EditSession.abort()`.
+   *
+   * Returns `true` when an interaction was active, otherwise `false`.
+   */
+  cancel(reason?: TacticalDrawAbortReason): boolean;
+  /**
+   * 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;
+  /**
+   * 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
+   * the first call every public method throws `TacticalDrawDestroyedError`.
+   */
+  destroy(): void;
+  /**
+   * Decide whether to deliver `event` to host pick handlers immediately or
+   * defer it until after the active edit closes. The "defer" branch is the
+   * close-then-pick path: the edit controller's click handler will close the
+   * session and then invoke `dispatchHostPick(graphicsLayer, event)` via
+   * `onClickAwayGraphicsPick` to redeliver — guaranteeing `td.edit(other)`
+   * from a host pick handler observes a settled session.
+   */
+  private routePick;
+  private dispatchHostPick;
+  /** @internal — exposed for tests and future controllers. */
+  get layerIds(): {
+    graphics: LayerId;
+    preview: LayerId;
+    guide: LayerId;
+    handles: LayerId;
+  };
+  /**
+   * Apply the resolved guide-slot style for an interaction and return a
+   * revert closure to re-apply the base (built-in + façade) style on settle.
+   * Per-call overrides are scoped to a single interaction (ADR-0004/0006).
+   */
+  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).
+   *
+   * Returns `undefined` only when no slot would carry any value — keeps the
+   * downstream "no style on the feature" path intact for tests that assert
+   * the absence of `properties.style`.
+   */
+  private resolveInteractionStyle;
+  private assertAlive;
+}
+//#endregion
+//#region src/tactical-draw/errors.d.ts
+/**
+ * Error thrown when any `TacticalDraw` method is called after `destroy()`.
+ * See PRD #40 / issue #45.
+ */
+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 };