@orbat-mapper/tactical-draw 0.2.0-alpha.34 → 0.2.0-alpha.36

package/dist/index.d.mts

@@ -1,393 +1,8 @@
-import { AmplifierPlacement, AmplifierPlacements, ControlMeasure, ControlMeasureKind, ControlMeasureRender, ControlMeasureStyle, FillPattern, TextAmplifiers } from "@orbat-mapper/control-measures";
+import { S as PointerEventInfo, _ as fillPatternImageDimension, a as MapAdapter, b as EditPointerDriver, c as MapEventHandler, d as PickOptions, f as PixelCoordinate, g as HatchPattern, h as HATCH_PATTERNS, i as LayerId, l as PickEvent, m as TextStyleOptions, n as HandleStyle, o as MapCursor, p as StyleOptions, r as IconResource, s as MapEvent, t as FeatureGroup, u as PickHandler, v as fillPatternImageId, x as PointerCallback, y as makeFillPatternImage } from "./map-adapter-meRo5VY2.mjs";
+import { AmplifierPlacement, AmplifierPlacements, ControlMeasure, ControlMeasureKind, ControlMeasureRender, ControlMeasureStyle, TextAmplifiers } from "@orbat-mapper/control-measures";
 import { Feature, Position } from "geojson";
 
-//#region src/gestures/types.d.ts
-interface PointerEventInfo {
-  /** Per-event hit-tolerance override (e.g. larger for touch). */
-  hitTolerance?: number;
-  /**
-   * Whether the Alt/Option modifier was held for this pointer event. The edit
-   * controller reads this on pointer-down to turn a vertex hit into a delete
-   * (the GIS-standard Alt+click-to-delete gesture) instead of a drag. Only the
-   * mouse paths populate it; touch leaves it `undefined`.
-   */
-  altKey?: boolean;
-  /**
-   * Whether Shift was held for this pointer event. Rotation gestures use the
-   * live value to constrain transform-box angles to 15-degree increments.
-   */
-  shiftKey?: boolean;
-  /** Engine-native event, for drivers that need to call preventDefault etc. */
-  native?: unknown;
-}
-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/fill-pattern.d.ts
-/**
- * Shared hatch fill-pattern tiles for area control-measure fills (ADR-0035
- * `FillPattern`, excluding `"solid"` which every adapter already renders as a
- * flat color). Both the MapLibre adapter (raster `addImage` pattern) and the
- * OpenLayers adapter (canvas `Pattern` fill) need the *same* diagonal-hachure
- * texture, so it is rasterized once here in pure math — no `HTMLCanvasElement`
- * — so it works in adapter code and in jsdom/node tests alike.
- */
-type HatchPattern = Exclude<FillPattern, "solid">;
-/**
- * Every non-solid `FillPattern` as a runtime list — the value-level companion
- * to {@link HatchPattern}, so adapters can test membership and build filter
- * expressions without re-spelling the pattern vocabulary.
- */
-declare const HATCH_PATTERNS: readonly HatchPattern[];
-/**
- * Stable id for a rasterized tile, keyed by pattern and color. Adapters use
- * this as the image-registry key (MapLibre `addImage` id, OpenLayers pattern
- * cache key) so the same color+pattern never gets rasterized twice. Color is
- * lowercased so `"#FF0000"` and `"#ff0000"` share one texture.
- */
-declare function fillPatternImageId(color: string, pattern: HatchPattern): string;
-/**
- * Tile edge length in device pixels for a given `pixelRatio`. Must be a power
- * of two — MapLibre requires POT dimensions for seamless WebGL texture wrap —
- * and scales linearly with `pixelRatio` for the ratios that matter in
- * practice (1x/2x displays: 32 -> 64, both already POT). Non-POT products
- * (e.g. a 3x ratio, 32*3=96) round up to the next POT rather than losing the
- * power-of-two guarantee.
- */
-declare function fillPatternImageDimension(pixelRatio: number): number;
-/**
- * Rasterize one seamless hatch tile as a straight RGBA pixel buffer — no
- * canvas involved, so this runs identically in a browser adapter and in
- * jsdom/node tests. Diagonal lines are snapped to slope ±1 (45°) so the
- * mod-based coverage math in {@link lineCoverage} tiles exactly. `"hachure"`
- * draws the "/" diagonal, `"backhachure"` its "\" mirror, and `"cross"` unions
- * both via `Math.max` coverage.
- */
-declare function makeFillPatternImage(color: string, pattern: HatchPattern, pixelRatio?: number): {
-  width: number;
-  height: number;
-  data: Uint8ClampedArray;
-};
-//#endregion
-//#region src/map-adapter.d.ts
-type PixelCoordinate = [number, number];
-type MapCursor = "" | "default" | "crosshair" | "grab" | "grabbing" | "pointer";
-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;
-}
-/**
- * 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;
-  font?: string;
-  fillColor?: string;
-  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).
- * 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;
-  /**
-   * How `fillColor` paints a filled part's interior. Absent or `"solid"` is
-   * today's flat fill; `"hachure"`/`"backhachure"`/`"cross"` request the shared hatch texture
-   * ({@link makeFillPatternImage}). Alpha rides in `fillColor` — there is no
-   * separate opacity field. Adapters that cannot rasterize a pattern degrade
-   * to solid. Per-feature only: layer-level `StyleOptions` has no equivalent.
-   */
-  fillPattern?: "solid" | HatchPattern;
-  pointRadius?: number;
-}
-type LayerId = string;
-/** Canonical SVG resource shared by point features through `iconId`. */
-interface IconResource {
-  id: string;
-  svg: string;
-  width: number;
-  height: number;
-  anchor: [number, number];
-  /**
-   * Direct visible mark used to rank icon picks, in unscaled canvas coordinates.
-   * Hits elsewhere in the full canvas measure their distance from this rectangle;
-   * omit it to preserve whole-canvas distance-zero behavior.
-   */
-  coreRect?: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-  };
-}
-/**
- * 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;
-  /** 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.
-   */
-  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;
-   *  - the incoming array order is authoritative for render order — later
-   *    features draw on top, so a call that only reorders is a visible change.
-   *
-   * 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;
-  /**
-   * Defer an upcoming removal from `layerId` until the most recent update to
-   * `updatedLayerId` has completed in the engine. Optional because synchronous
-   * adapters already make cross-layer write order visible atomically.
-   */
-  deferLayerRemovalUntilLayerUpdate?(layerId: LayerId, updatedLayerId: LayerId): void;
-  /**
-   * Subscribe to click-style "pick" events for a specific layer. Basemap and
-   * other-layer clicks never fire the handler.
-   *
-   * 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.
-   * Outline-only polygon interiors additionally have bounded inward selection
-   * reach from visible viewport-clipped boundaries: 24 px for mouse/pen and
-   * 36 px for touch. A visible solid or patterned fill owns its full interior.
-   *
-   * Returns an unsubscribe function. The returned function and the optional
-   * `signal` are both honoured; either teardown path stops further events,
-   * and both are idempotent.
-   */
-  onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
-  /**
-   * Map Event Listeners
-   *
-   * Ordering contract: a `"click"` handler and the `onPick` handlers for the
-   * same user click MUST observe the pick first — adapters deliver picks and
-   * `"click"` from the same underlying engine event, in registration order.
-   * The draw/edit controllers register their pick subscriptions before their
-   * click handler and read the stashed pick inside it (click-away close /
-   * close-then-pick re-dispatch); an adapter that fires `"click"` from an
-   * earlier engine event than its picks breaks that contract (e.g. OL
-   * `click` vs `singleclick`).
-   */
-  on(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
-  off(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
-  /**
-   * Projection / Coordinate Utilities
-   */
-  toLonLat(coordinate: number[]): Position;
-  fromLonLat(position: Position): number[];
-  getPixelFromCoordinate(position: Position): PixelCoordinate | null;
-  /**
-   * Convert a viewport pixel to longitude/latitude. Optional so third-party
-   * adapters compiled against an older ABI remain valid.
-   */
-  getCoordinateFromPixel?(pixel: PixelCoordinate): Position | null;
-  /**
-   * Get current viewport size in CSS pixels.
-   */
-  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;
-  /**
-   * Get current view bearing, radians — the clockwise-from-north compass
-   * direction that screen-up points to (MapLibre-bearing semantics). `0` for
-   * engines/views that don't rotate.
-   */
-  getBearing(): number;
-  /**
-   * Listen for view changes (zoom/resolution)
-   */
-  onViewChange(handler: () => void): void;
-  offViewChange(handler: () => void): void;
-  /**
-   * The engine evaluates the meters→pixels clamp for ground-sized point
-   * symbols inside its own style layer, so meters-sized point symbols don't
-   * need view-change re-renders for size.
-   */
-  readonly scalesGroundPointSymbolsNatively?: boolean;
-  /**
-   * Construct an {@link EditPointerDriver} for `TacticalDraw`'s edit
-   * controller. The controller subscribes to pointer events on the returned
-   * 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;
-  /**
-   * 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
-interface FeatureOps {
-  adds: Feature[];
-  updates: Feature[];
-  /** Features whose id was absent from the incoming set. */
-  removes?: Feature[];
-  /**
-   * Complete, ordered snapshot of the layer after this op. The order is
-   * authoritative for render order (later features draw on top), so
-   * `applyFeatureOps` must leave the layer rendering in `full`'s order — a
-   * pure reorder ships identical content in a new order and still counts as a
-   * change. Adapters that rebuild the layer from `full` satisfy this for free;
-   * incremental adapters must reconcile order against it.
-   */
-  full: Feature[];
-  replace?: boolean;
-}
 type NormalizedEventHandler = (lonLat: Position, pixel: PixelCoordinate, originalEvent: unknown) => void;
 interface NativeEventEntry<TEventToken> {
   type: string;
@@ -397,10 +12,8 @@ interface NativeEventEntry<TEventToken> {
  * Abstract base class shared by all `MapAdapter` implementations.
  *
  * Owns shared bookkeeping (layer registry, feature cache, event-token
- * tracking) and orchestrates the public methods over a small
- * protected primitive surface that subclasses implement. See
- * `docs/adr/0001-map-adapter-base-class.md` for the rationale, in particular
- * around the `applyFeatureOps` primitive shape.
+ * tracking) and orchestrates the public methods over a small protected
+ * grouped desired-state primitive that subclasses implement.
  */
 declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> implements MapAdapter {
   protected layers: Map<string, TLayerHandle>;
@@ -409,6 +22,7 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
   protected featureCache: Map<string, Feature<import("geojson").Geometry, import("geojson").GeoJsonProperties>[]>;
   protected featuresChangedListeners: Map<string, Set<(features: Feature[]) => void>>;
   protected iconResources: Map<string, IconResource>;
+  private featureGroupState;
   private layerIconResourceIds;
   private layerCounter;
   private destroyed;
@@ -417,13 +31,9 @@ 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;
+  setLayerFeatureGroups(layerId: LayerId, groups: readonly FeatureGroup[]): void;
   abstract onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
   abstract createEditPointerDriver(): EditPointerDriver;
-  clearLayer(layerId: LayerId): void;
   on(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
   off(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
   onViewChange(handler: () => void): void;
@@ -434,11 +44,13 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
   protected destroyEngineResources(): void;
   protected applyIconResources(resources: readonly IconResource[]): void;
   protected getIconResource(id: string): IconResource | undefined;
+  protected getFeatureGroupOrder(layerId: LayerId, featureId: string | number | undefined): number | undefined;
   protected removeIconResource(id: string): void;
   private pruneIconResources;
   protected abstract createLayer(layerId: LayerId, style?: StyleOptions): TLayerHandle;
   protected abstract destroyLayer(handle: TLayerHandle): void;
-  protected abstract applyFeatureOps(layerId: LayerId, ops: FeatureOps): void;
+  /** Apply one validated, complete grouped desired state. */
+  protected abstract applyFeatureGroups(layerId: LayerId, groups: readonly FeatureGroup[]): void;
   protected abstract attachNativeEvent(type: "click" | "pointermove" | "dblclick", onEvent: NormalizedEventHandler): NativeEventEntry<TEventToken>;
   protected abstract detachNativeEvent(entry: NativeEventEntry<TEventToken>): void;
   protected abstract attachViewChange(handler: () => void): TViewToken;
@@ -529,6 +141,8 @@ interface PickCandidate {
   viewport: ScreenBounds;
   presentation: ResolvedPickPresentation;
   visualOrder: number;
+  /** Lower values mean a visually higher atomic feature group. */
+  featureGroupOrder?: number;
   iconFootprint?: readonly PixelCoordinate[];
   labelExtent?: LabelExtent;
 }
@@ -540,6 +154,11 @@ interface PickCandidateInput {
    * native ordering to topmost-first before calling into evaluation.
    */
   visualOrder: number;
+  /**
+   * Authoritative bottom-to-top group order normalized to lower = visually
+   * higher. Unlike `visualOrder`, native engine query order cannot override it.
+   */
+  featureGroupOrder?: number;
   /** The engine already reported this part as hit; retained as a fallback for engine-only marks. */
   nativeHit?: boolean;
   icon?: IconResource;
@@ -1281,8 +900,7 @@ interface TransformSession {
    * - **Removed** members (id in the current set, absent from the next) are
    *   committed at their current working state.
    * - **Added** members (id only in the next set) join at their passed input
-   *   state; if currently on the graphics layer they are lifted off it exactly
-   *   like initial members.
+   *   state and use their host-provided Graphic-stack slot when present.
    *
    * The transform box re-derives from the next member set at the session's
    * current box angle. Session-scoped state (`sizeAnchor`, box angle,
@@ -1299,11 +917,12 @@ interface TransformSession {
    * size left untouched, then cloned and rendered); an empty array when nothing
    * was removed. The outer `editMany` promise resolves with the snapshots of
    * the members in the set **at close time only**. Removed members are NOT
-   * written back to the graphics layer by the controller — the host folds the
-   * returned snapshots into its document and calls `td.render()`, the same
-   * contract as [[close]]. A removed member's exit snapshot is also delivered
-   * through [[onCommit]] — the recommended channel, since it covers this return
-   * value and the close-time promise resolution through a single subscription.
+   * retained in its Graphic-stack slot until the host acknowledges it by
+   * folding the returned snapshot into its document and calling `td.render()`,
+   * the same contract as [[close]]. A removed member's exit snapshot is also
+   * delivered through [[onCommit]] — the recommended channel, since it covers
+   * this return value and the close-time promise resolution through a single
+   * subscription.
    * Returns `undefined` (a silent no-op) after the session has settled.
    *
    * `setGraphics([])` on a live session delegates to [[close]]: it commits every
@@ -1378,9 +997,8 @@ interface TransformSession {
    *   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.
+   *   slot — `td.activeTransformSession` is `null`, so fold-then-render works
+   *   from inside the handler.
    * - `reason` distinguishes commit from abort but is deliberately coarse —
    *   no payload; snapshots were already delivered through [[onCommit]].
    *
@@ -1778,6 +1396,7 @@ declare class TacticalDraw {
   private readonly pointSymbols;
   private snappingOptions;
   private readonly resolveSnap;
+  private readonly graphicStack;
   private destroyed;
   private hasRendered;
   private readonly activeInteraction;
@@ -1821,12 +1440,7 @@ declare class TacticalDraw {
   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
-   * façade owns the policy because controllers shouldn't need to know the
-   * surrounding collection state.
-   */
+  /** Snapshot of the host's latest authoritative Graphic membership and order. */
   private lastRenderedMeasures;
   private snapGeometryFeatures;
   /**
@@ -1848,31 +1462,31 @@ declare class TacticalDraw {
   setSnappingOptions(options?: SnappingOptions): void;
   /** Clear transient host affordances when snapping or its interaction ends. */
   private clearSnapResult;
-  /**
-   * Render `measures` into features and write them to the graphics layer.
-   * Routes every measure through [[renderMeasureForAdapter]] so pixel sizing is
-   * resolved against the live map. Callers own any edit-exclusion policy — see
-   * `render()` (excludes the edited measure, owned by the preview layer) versus
-   * `settleToGraphics` (no exclusion, the edit is ending).
-   */
-  private renderMeasuresToGraphics;
+  /** Render one atomic Graphic group for the engine-neutral graphics stack. */
+  private renderGraphicGroup;
+  /** Submit one complete grouped desired state for the host stack plus overrides. */
+  private reconcileGraphicsStack;
+  /** Atomically publish several live renders into their host-owned Graphic slots. */
+  private publishWorkingGraphics;
+  /** Settle several stack overrides in one graphics-layer reconciliation. */
+  private settleWorkingGraphics;
   /**
    * Re-render the graphics layer on a view (zoom) change so pixel-denominated
    * 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.
+   * layer writes. A single-control-measure edit publishes through the stack
+   * coordinator; point symbols and transform members already present in the
+   * host stack do the same. Graphics without a host slot remain on preview.
    */
   private readonly handleViewChange;
   /**
-   * Every measure id currently lifted onto the preview layer by an active
-   * edit or group transform — excluded from `render()` / view-change
-   * reconciliation because the preview layer (not graphics) owns their
-   * working copy. Empty while idle.
+   * Every Graphic id owned by an active interaction. Used for highlight and
+   * pick routing; not every such Graphic is excluded from stack reconciliation.
    */
   private excludedInteractionIds;
+  /** Interaction ids still rendered on the legacy preview surface. */
+  private graphicsStackExcludedIds;
   /**
    * Live member ids of the active group transform, or `undefined` when none.
    * Falls back to the session ref because `onSession` fires from inside the
@@ -1886,24 +1500,24 @@ declare class TacticalDraw {
    * Idempotent. Throws synchronously on duplicate measure ids *before*
    * mutating any layer. An empty list before any prior render is a no-op.
    *
-   * Cross-layer semantics with an active edit (issue #51):
-   *  - The measure under edit is **excluded** from the reconcile pass — the
-   *    preview layer owns its working copy and the lift on the graphics layer
-   *    must stay in place.
+   * Cross-layer semantics with an active edit:
+   *  - The stack coordinator replaces the edited Graphic's host-owned slot
+   *    with its working render; membership and order remain host-authoritative.
    *  - If the edited measure is absent from `measures`, the pending `edit`
    *    promise rejects on the **next microtask** with reason `"removed"`.
    *    `render` itself returns normally so host collection ops stay synchronous.
-   *  - If the edited measure is present and its `style` changed, the preview
-   *    picks up the new style on this render. `controlPoints` changes on the
+   *  - If the edited measure is present and its `style` changed, its working
+   *    group picks up the new style on this render. `controlPoints` changes on the
    *    edited measure are routed nowhere — the user's in-flight drag is never
-   *    yanked out from under them.
+   *    yanked out from under them. A point symbol's complete working group remains
+   *    authoritative until settle, including any changed icon resource.
    *
    * Cross-layer semantics with an active draw: `render` only touches the
    * graphics layer, so the draw's preview is undisturbed.
    *
    * Reentrancy: calling `td.render(...)` from inside `EditSession.onChange` is
-   * safe — `render` never re-enters the active edit or its preview / handle
-   * layers (the only edit-facing side effect, `notifyExternalMeasure`, is a
+   * safe — `render` never re-enters the active edit or its handle layer (the
+   * only edit-facing side effect, `notifyExternalMeasure`, is a
    * pure style replay).
    */
   render(measures: readonly Graphic[]): void;
@@ -1912,7 +1526,7 @@ declare class TacticalDraw {
    * idempotent (mirrors {@link render}): a non-interactive outline box is drawn
    * around each still-rendered graphic on the dedicated highlight layer — no
    * draw / edit / transform session, no promise, no pick subscription. Passing
-   * `[]` clears every highlight. Unknown ids and ids currently lifted into an
+   * `[]` clears every highlight. Unknown ids and ids currently active in an
    * active edit / transform session are skipped (the live session's own visuals
    * supersede the passive outline). Hosts use it for Excalidraw-style
    * "locked selection" chrome.
@@ -1921,9 +1535,9 @@ declare class TacticalDraw {
   /**
    * Project the current {@link highlightedIds} into one outline `LineString`
    * per graphic and reconcile them onto the highlight layer. Idempotent and
-   * id-keyed via `adapter.updateLayerFeatures`, so a set-replace removes stale
-   * outlines and an unchanged set is a cheap no-op write. Skips ids that are
-   * unknown (not in the last render) or lifted into an active session, and
+   * grouped by graphic id, so desired-state replacement removes stale outlines
+   * and an unchanged set is a cheap no-op write. Skips ids that are
+   * unknown (not in the last render) or active in an interaction session, and
    * bails gracefully when the adapter cannot invert pixels to coordinates
    * (`getCoordinateFromPixel` is optional in the MapAdapter ABI).
    */
@@ -2004,9 +1618,10 @@ declare class TacticalDraw {
   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
+   * (ADR-0017 "Multi-select" slice). Every host-provided member stays in its
+   * Graphic-stack slot; only a member without a host slot uses preview. The box
+   * (corner scale, rotate grip, drag-anywhere body translate) applies rigidly
+   * to all of them at once. Returns a Promise that
    * resolves with `GraphicSnapshot<ControlMeasure>[]` on `session.close()` and rejects
    * with `TacticalDrawAbortError` on signal / Escape / destroy / preempt /
    * `session.abort()`. Key the resolved snapshots by `snapshot.graphic.id`:
@@ -2275,4 +1890,4 @@ declare function nearestWorldCopyLng(lng: number, refLng: number): number;
 /** `nearestWorldCopyLng` applied to a lon/lat position. */
 declare function nearestWorldCopyPosition(position: Position, refLng: number): Position;
 //#endregion
-export { BaseMapAdapter, type CombinedAbort, DEFAULT_LABEL_SIZE_PIXELS, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, type DrawMeasureDraft, type DrawOptions, type DrawPointSymbolDraft, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type Graphic, type GraphicEditChangeEvent, type GraphicEditSession, type GraphicGeometrySnappingOptions, type GraphicRender, type GraphicSnapshot, type GuideStyle, HATCH_PATTERNS, type HandleStyle, type HatchPattern, type IconResource, type InteractionHit, type InteractionStyle, type LabelExtent, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type MergedPickFeature, type NativeEventEntry, type PickCandidate, type PickCandidateHit, type PickCandidateHitKind, type PickCandidateInput, type PickEvaluationContext, type PickEvent, type PickHandler, type PickOptions, type PickPointerType, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type ResolvedPickPresentation, type RotatedScreenBounds, type ScreenBounds, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type SnapCandidate, type SnapCandidateProvider, type SnapCandidateRequest, type SnapInteraction, type SnapResult, type SnappingOptions, type StyleOptions, TEXT_HALO_COLOR, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextSizeProps, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, type TransientChangeEvent, type TransientPhase, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, effectivePointSymbolPixelSize, evaluatePickCandidates, fillPatternImageDimension, fillPatternImageId, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, makeFillPatternImage, mergeNativeAndCachedPickFeatures, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pickPointerType, pointSymbolFootprint, renderOrderToVisualOrder, resizePointSymbolSize, resolveGroundTextSizePixels, resolvePickPresentation, resolveTextHaloWidth, resolveTextSizePixels, tryControlMeasureIdFromFeature };
+export { BaseMapAdapter, type CombinedAbort, DEFAULT_LABEL_SIZE_PIXELS, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, type DrawMeasureDraft, type DrawOptions, type DrawPointSymbolDraft, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureGroup, type Graphic, type GraphicEditChangeEvent, type GraphicEditSession, type GraphicGeometrySnappingOptions, type GraphicRender, type GraphicSnapshot, type GuideStyle, HATCH_PATTERNS, type HandleStyle, type HatchPattern, type IconResource, type InteractionHit, type InteractionStyle, type LabelExtent, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type MergedPickFeature, type NativeEventEntry, type PickCandidate, type PickCandidateHit, type PickCandidateHitKind, type PickCandidateInput, type PickEvaluationContext, type PickEvent, type PickHandler, type PickOptions, type PickPointerType, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type ResolvedPickPresentation, type RotatedScreenBounds, type ScreenBounds, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type SnapCandidate, type SnapCandidateProvider, type SnapCandidateRequest, type SnapInteraction, type SnapResult, type SnappingOptions, type StyleOptions, TEXT_HALO_COLOR, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextSizeProps, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, type TransientChangeEvent, type TransientPhase, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, effectivePointSymbolPixelSize, evaluatePickCandidates, fillPatternImageDimension, fillPatternImageId, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, makeFillPatternImage, mergeNativeAndCachedPickFeatures, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pickPointerType, pointSymbolFootprint, renderOrderToVisualOrder, resizePointSymbolSize, resolveGroundTextSizePixels, resolvePickPresentation, resolveTextHaloWidth, resolveTextSizePixels, tryControlMeasureIdFromFeature };