@orbat-mapper/tactical-draw 0.2.0-alpha.37 → 0.2.0-alpha.38

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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 { 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-BIlrWk6y.mjs";
 import { AmplifierPlacement, AmplifierPlacements, ControlMeasure, ControlMeasureKind, ControlMeasureRender, ControlMeasureStyle, TextAmplifiers } from "@orbat-mapper/control-measures";
 import { Feature, Position } from "geojson";
 
@@ -400,6 +400,15 @@ interface PointSymbolCapability {
   readonly defaultRotation: number;
   render(symbol: PointSymbol): PointSymbolRender;
   invalidate(): void;
+  /**
+   * Monotonic counter that increments on each `invalidate()` call. Consumers
+   * (e.g. a render cache keyed on graphic snapshot identity) may read this to
+   * detect that previously rendered point-symbol output is stale even though
+   * the graphic snapshot itself is unchanged. Optional — when absent,
+   * invalidation cannot be detected by cache layers, so they must not attempt
+   * to key on it.
+   */
+  readonly generation?: number;
 }
 declare function isPointSymbol(graphic: unknown): graphic is PointSymbol;
 declare function clonePointSymbol(symbol: PointSymbol): PointSymbol;
@@ -1443,6 +1452,23 @@ declare class TacticalDraw {
   /** Snapshot of the host's latest authoritative Graphic membership and order. */
   private lastRenderedMeasures;
   private snapGeometryFeatures;
+  /**
+   * Rendered graphics-layer groups, keyed on Graphic snapshot identity. See
+   * {@link renderGraphicGroup} for the invalidation contract; swapped for a
+   * fresh map (not cleared entry-by-entry) so stale entries are collectable.
+   */
+  private graphicGroupCache;
+  /**
+   * Last {@link PointSymbolCapability.generation} observed from `pointSymbols`,
+   * initialised from the capability at construction. Compared at the top of
+   * every {@link reconcileGraphicsStack} so a host calling `invalidate()` after
+   * changing renderer-global config (e.g. milsymbol options) drops the render
+   * cache even though the Graphic snapshots handed to `render()` are
+   * unchanged — otherwise the cache would keep serving pre-invalidation
+   * output and the capability would never be re-consulted. `undefined` when
+   * there is no capability, or the capability doesn't expose `generation`.
+   */
+  private lastSeenPointSymbolGeneration;
   /**
    * Ids of graphics currently carrying a passive selection-highlight outline
    * ({@link setHighlightedGraphics}). Declarative set-replace, no session —
@@ -1462,8 +1488,34 @@ declare class TacticalDraw {
   setSnappingOptions(options?: SnappingOptions): void;
   /** Clear transient host affordances when snapping or its interaction ends. */
   private clearSnapResult;
-  /** Render one atomic Graphic group for the engine-neutral graphics stack. */
+  /**
+   * Render one atomic Graphic group for the engine-neutral graphics stack,
+   * reusing the previous render when nothing that feeds it has changed.
+   *
+   * The cache is keyed on the Graphic snapshot's object identity: hosts hand
+   * `render()` a fresh object whenever a graphic's data changes, so a changed
+   * graphic misses by construction. (A host that mutates a Graphic in place and
+   * re-renders the same reference is outside the contract — `render()` has
+   * always been documented as taking snapshots.) Rendered output also depends
+   * on live view state and on the resolved graphics style; the style is fixed
+   * at construction, and every view change drops the whole cache. Crucially,
+   * the view cannot change during a box drag (drag-pan is disabled), so every
+   * graphic outside the selection stays a cache hit for the whole gesture and
+   * per-frame reconcile cost becomes O(selection) rather than O(document).
+   */
   private renderGraphicGroup;
+  /**
+   * Render a Graphic group from scratch and stamp it with a fresh revision,
+   * drawn from the module-scoped {@link nextGraphicGroupRevision} counter (see
+   * its doc comment for why it isn't a per-instance field).
+   */
+  private buildGraphicGroup;
+  /**
+   * Drop every cached render. Called whenever an input shared by all graphic
+   * renders changes — the live view state, or (via {@link reconcileGraphicsStack})
+   * the point-symbol capability's `generation`.
+   */
+  private invalidateGraphicGroupCache;
   /** 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. */

package/dist/index.mjs

@@ -486,7 +486,8 @@ var BaseMapAdapter = class {
 		const nextGroups = groups.map((group) => ({
 			id: group.id,
 			features: [...group.features],
-			iconResources: [...group.iconResources]
+			iconResources: [...group.iconResources],
+			revision: group.revision
 		}));
 		const nextFeatures = nextGroups.flatMap((group) => group.features);
 		const nextResourcesById = /* @__PURE__ */ new Map();
@@ -4768,6 +4769,42 @@ function boundProperty(key, value) {
 	return value !== void 0 && Number.isFinite(value) && value > 0 ? { [key]: value } : {};
 }
 //#endregion
+//#region src/tactical-draw/frame-coalescer.ts
+/**
+* @param run Callback invoked with the latest scheduled args, at most once per frame.
+*/
+function createFrameCoalescer(run) {
+	const raf = globalThis.requestAnimationFrame?.bind(globalThis);
+	const cancelRaf = globalThis.cancelAnimationFrame?.bind(globalThis);
+	if (!raf || !cancelRaf) return {
+		schedule(...args) {
+			run(...args);
+		},
+		cancel() {}
+	};
+	let handle = null;
+	let latestArgs = null;
+	return {
+		schedule(...args) {
+			latestArgs = args;
+			if (handle !== null) return;
+			handle = raf(() => {
+				handle = null;
+				const pending = latestArgs;
+				latestArgs = null;
+				if (pending) run(...pending);
+			});
+		},
+		cancel() {
+			if (handle !== null) {
+				cancelRaf(handle);
+				handle = null;
+			}
+			latestArgs = null;
+		}
+	};
+}
+//#endregion
 //#region src/tactical-draw/transform-controller.ts
 /** No point symbol may scale below this factor of its own size — mirrors the box-drag floor. */
 const MIN_POINT_SYMBOL_SIZE = .1;
@@ -5479,12 +5516,14 @@ function runGroupTransform(opts) {
 		renderHandlesLayer();
 		recomputeDirty();
 	}
+	const boxDragPaintCoalescer = createFrameCoalescer(paintBoxDragSnapshot);
 	const onDriverMove = (pixel, info) => {
 		if (ctx.settled) return;
-		if (activeBoxDrag) paintBoxDragSnapshot(pixel, info?.shiftKey);
+		if (activeBoxDrag) boxDragPaintCoalescer.schedule(pixel, info?.shiftKey);
 	};
 	const onDriverUp = (pixel, info) => {
 		if (!activeBoxDrag) return;
+		boxDragPaintCoalescer.cancel();
 		if (ctx.settled) {
 			activeBoxDrag = null;
 			dragInFlight = false;
@@ -5545,6 +5584,7 @@ function runGroupTransform(opts) {
 			if (settlement.status === "rejected") settleEmitter.emit(settleReasonFromError(settlement.error));
 		},
 		extraTeardown: () => {
+			boxDragPaintCoalescer.cancel();
 			if (activeBoxDrag !== null) {
 				driver.setDragPanEnabled(true);
 				activeBoxDrag = null;
@@ -5930,6 +5970,17 @@ var GraphicStackCoordinator = class {
 //#endregion
 //#region src/tactical-draw/tactical-draw.ts
 /**
+* Source of {@link FeatureGroup.revision} stamps. Module-scoped rather than a
+* per-instance counter: adapters keep per-group bundles on host-supplied layer
+* handles, and `destroy()` intentionally leaves those layers untouched so a
+* host can attach a fresh façade to the same adapter/layer for reuse. An
+* instance counter would restart at 1 on the new façade, so a bundle the
+* previous façade stored at revision 1 — with different content — would
+* compare equal and the adapter would wrongly skip the repaint. A counter
+* shared across every façade in the JS realm guarantees revisions never repeat.
+*/
+let nextGraphicGroupRevision = 0;
+/**
 * `TacticalDraw` façade — slice #6 (issue #45).
 *
 * Provides the constructor + lifecycle + `render(measures)` reconcile path.
@@ -5998,6 +6049,23 @@ var TacticalDraw = class {
 	lastRenderedMeasures = [];
 	snapGeometryFeatures = [];
 	/**
+	* Rendered graphics-layer groups, keyed on Graphic snapshot identity. See
+	* {@link renderGraphicGroup} for the invalidation contract; swapped for a
+	* fresh map (not cleared entry-by-entry) so stale entries are collectable.
+	*/
+	graphicGroupCache = /* @__PURE__ */ new WeakMap();
+	/**
+	* Last {@link PointSymbolCapability.generation} observed from `pointSymbols`,
+	* initialised from the capability at construction. Compared at the top of
+	* every {@link reconcileGraphicsStack} so a host calling `invalidate()` after
+	* changing renderer-global config (e.g. milsymbol options) drops the render
+	* cache even though the Graphic snapshots handed to `render()` are
+	* unchanged — otherwise the cache would keep serving pre-invalidation
+	* output and the capability would never be re-consulted. `undefined` when
+	* there is no capability, or the capability doesn't expose `generation`.
+	*/
+	lastSeenPointSymbolGeneration;
+	/**
 	* Ids of graphics currently carrying a passive selection-highlight outline
 	* ({@link setHighlightedGraphics}). Declarative set-replace, no session —
 	* re-projected on every view change and re-evaluated at the end of every
@@ -6017,6 +6085,7 @@ var TacticalDraw = class {
 		this.defaultInteractionStyle = options?.interactionStyle;
 		this.generateId = options?.generateId ?? (() => `td-${++this.idCounter}`);
 		this.pointSymbols = options?.pointSymbols;
+		this.lastSeenPointSymbolGeneration = this.pointSymbols?.generation;
 		this.snappingOptions = options?.snapping;
 		this.resolveSnap = createSnapResolver(adapter, () => this.lastRenderedMeasures, () => this.snapGeometryFeatures, () => this.snappingOptions);
 		const owned = /* @__PURE__ */ new Set();
@@ -6044,27 +6113,68 @@ var TacticalDraw = class {
 	clearSnapResult() {
 		this.snappingOptions?.onSnap?.(null);
 	}
-	/** Render one atomic Graphic group for the engine-neutral graphics stack. */
+	/**
+	* Render one atomic Graphic group for the engine-neutral graphics stack,
+	* reusing the previous render when nothing that feeds it has changed.
+	*
+	* The cache is keyed on the Graphic snapshot's object identity: hosts hand
+	* `render()` a fresh object whenever a graphic's data changes, so a changed
+	* graphic misses by construction. (A host that mutates a Graphic in place and
+	* re-renders the same reference is outside the contract — `render()` has
+	* always been documented as taking snapshots.) Rendered output also depends
+	* on live view state and on the resolved graphics style; the style is fixed
+	* at construction, and every view change drops the whole cache. Crucially,
+	* the view cannot change during a box drag (drag-pan is disabled), so every
+	* graphic outside the selection stays a cache hit for the whole gesture and
+	* per-frame reconcile cost becomes O(selection) rather than O(document).
+	*/
 	renderGraphicGroup(graphic) {
-		const renderOpts = { graphicsStyle: this.graphicsStyle };
+		const cached = this.graphicGroupCache.get(graphic);
+		if (cached) return cached;
+		const group = this.buildGraphicGroup(graphic);
+		this.graphicGroupCache.set(graphic, group);
+		return group;
+	}
+	/**
+	* Render a Graphic group from scratch and stamp it with a fresh revision,
+	* drawn from the module-scoped {@link nextGraphicGroupRevision} counter (see
+	* its doc comment for why it isn't a per-instance field).
+	*/
+	buildGraphicGroup(graphic) {
+		const revision = ++nextGraphicGroupRevision;
 		if (isPointSymbol(graphic)) {
 			if (!this.pointSymbols) throw new PointSymbolCapabilityRequiredError();
 			const plan = renderPointSymbolForAdapter(this.adapter, this.pointSymbols, graphic);
 			return {
 				id: graphic.id,
 				features: [plan.feature],
-				iconResources: [plan.resource]
+				iconResources: [plan.resource],
+				revision
 			};
 		}
-		const render = renderMeasureForAdapter(this.adapter, graphic, renderOpts);
+		const render = renderMeasureForAdapter(this.adapter, graphic, { graphicsStyle: this.graphicsStyle });
 		return {
 			id: graphic.id,
 			features: render.features,
-			iconResources: []
+			iconResources: [],
+			revision
 		};
 	}
+	/**
+	* Drop every cached render. Called whenever an input shared by all graphic
+	* renders changes — the live view state, or (via {@link reconcileGraphicsStack})
+	* the point-symbol capability's `generation`.
+	*/
+	invalidateGraphicGroupCache() {
+		this.graphicGroupCache = /* @__PURE__ */ new WeakMap();
+	}
 	/** Submit one complete grouped desired state for the host stack plus overrides. */
 	reconcileGraphicsStack(graphics = this.lastRenderedMeasures) {
+		const currentGeneration = this.pointSymbols?.generation;
+		if (currentGeneration !== this.lastSeenPointSymbolGeneration) {
+			this.invalidateGraphicGroupCache();
+			this.lastSeenPointSymbolGeneration = currentGeneration;
+		}
 		const groups = this.graphicStack.desiredGroups(graphics, (graphic) => this.renderGraphicGroup(graphic));
 		this.adapter.setLayerFeatureGroups(this.graphicsLayer, groups);
 		this.snapGeometryFeatures = groups.flatMap((group) => group.features);
@@ -6093,6 +6203,7 @@ var TacticalDraw = class {
 	*/
 	handleViewChange = () => {
 		if (this.destroyed || !this.hasRendered) return;
+		this.invalidateGraphicGroupCache();
 		this.renderHighlights();
 		const excluded = this.graphicsStackExcludedIds();
 		const visible = excluded.size > 0 ? this.lastRenderedMeasures.filter((m) => !excluded.has(m.id)) : this.lastRenderedMeasures;

package/dist/{map-adapter-meRo5VY2.d.mts → map-adapter-BIlrWk6y.d.mts}

@@ -188,6 +188,15 @@ interface FeatureGroup {
   id: string;
   features: readonly Feature[];
   iconResources: readonly IconResource[];
+  /**
+   * Monotonic stamp identifying this group's rendered content, when the
+   * producer supplies one. Two groups with the same `id` and the same
+   * `revision` carry byte-identical `features` and `iconResources`, so an
+   * adapter may skip any diff or upload work for them. A missing `revision`
+   * means "unknown" — adapters must fall back to their own comparison and
+   * must never treat two absent stamps as equal.
+   */
+  revision?: number;
 }
 /**
  * Click-style hit event delivered by {@link MapAdapter.onPick}.

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { a as MapAdapter, f as PixelCoordinate, i as LayerId } from "./map-adapter-meRo5VY2.mjs";
+import { a as MapAdapter, f as PixelCoordinate, i as LayerId } from "./map-adapter-BIlrWk6y.mjs";
 import { Feature } from "geojson";
 
 //#region src/testing/feature-group-conformance.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbat-mapper/tactical-draw",
-  "version": "0.2.0-alpha.37",
+  "version": "0.2.0-alpha.38",
   "description": "Engine-agnostic draw/edit core for tactical control measures (MIL-STD-2525 / APP-6). The MapAdapter ABI and bring-your-own-engine entry point for the tactical-draw package family.",
   "license": "MIT",
   "author": "Orbat Mapper",