@orbat-mapper/tactical-draw 0.2.0-alpha.8 → 0.2.0-alpha.9

package/dist/index.d.mts

@@ -648,13 +648,15 @@ interface TransformSession {
    * **Return value** — the committed exit snapshots of the members removed *by
    * this call*, built exactly like [[close]]'s snapshots (pixel size baked to
    * ground unless `sizeAnchor` is `"screen"`, then cloned and rendered); an
-   * empty array when nothing was removed. This is the *only* delivery of a
-   * removed member's exit state: 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]]. Returns `undefined` (a silent no-op) after the
-   * session has settled.
+   * empty array when nothing was removed. The outer `editMany` promise resolves
+   * with the snapshots of the members in the set **at close time only**.
+   * Removed members are NOT written back to the graphics layer by the
+   * controller — the host folds the returned snapshots into its document and
+   * calls `td.render()`, the same contract as [[close]]. A removed member's
+   * exit snapshot is also delivered through [[onCommit]] — the recommended
+   * channel, since it covers this return value and the close-time promise
+   * resolution through a single subscription. Returns `undefined` (a silent
+   * no-op) after the session has settled.
    *
    * `setMembers([])` on a live session delegates to [[close]]: it commits every
    * current member, resolves the promise with their snapshots, and returns that
@@ -667,8 +669,9 @@ interface TransformSession {
    * set at close time) and resolves the outer `editMany` promise with the same
    * value (the same reference — no double-bake of ground-anchored sizes). A
    * member removed mid-session via [[setMembers]] is not included here; its exit
-   * snapshot was returned from that `setMembers` call. Returns `undefined` after
-   * the session has settled (idempotent no-op).
+   * snapshot was returned from that `setMembers` call (and delivered to
+   * [[onCommit]] at that time). Returns `undefined` after the session has
+   * settled (idempotent no-op).
    */
   close(): ControlMeasureSnapshot[] | undefined;
   /** Reject the outer `editMany` promise with reason `"session"`. */
@@ -686,6 +689,33 @@ interface TransformSession {
    * have run — mirrors `EditSession.onChange` (issue #49).
    */
   onChange(listener: (event: TransformChangeEvent) => void): () => void;
+  /**
+   * Subscribe to committed exit-snapshot batches — the single delivery channel
+   * for every `ControlMeasureSnapshot[]` this session ever commits (#191). Fires
+   * exactly once per batch:
+   *
+   * - The members [[setMembers]] removes, but only when that call actually
+   *   removed at least one member.
+   * - The close-time members on any commit path: [[close]], `setMembers([])`,
+   *   a click-away close, or `TransformChangeEvent.close()`.
+   *
+   * Never fires on an abort/reject path. Fires synchronously from within the
+   * `setMembers`/`close` call that produced the batch, before that call
+   * returns, and the array delivered here is the same reference that call
+   * returns (and, for the close batch, the same reference the `editMany`
+   * promise resolves with). This is the recommended single fold path for exit
+   * state — subscribe once in `onSession` and every committed snapshot, from
+   * either delivery site, arrives here exactly once; the `setMembers` return
+   * value and the promise resolution are unchanged and remain valid for
+   * backward compatibility.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]]. Returns an unsubscribe function; registering after the
+   * session has settled returns a no-op unsubscribe and the listener never
+   * fires.
+   */
+  onCommit(handler: (snapshots: ControlMeasureSnapshot[]) => void): () => void;
 }
 /**
  * Delivered to `TransformSession.onChange` listeners once per completed group
@@ -1104,8 +1134,41 @@ declare class TacticalDraw {
    * `measures.length` must be >= 1; a single-element array behaves like an
    * `edit` with only `transform` mode. Throws `TypeError` synchronously (before
    * any preemption) for an empty array or duplicate ids.
+   *
+   * For a selection that changes over time (shift-click toggle, marquee
+   * replace), prefer [[syncTransformMembers]] over hand-rolling the
+   * live-session-vs-fresh-`editMany` branch, and subscribe to
+   * `TransformSession.onCommit` as the single fold path for exit snapshots.
    */
   editMany(measures: ControlMeasure[], options?: EditManyOptions): Promise<ControlMeasureSnapshot[]>;
+  /**
+   * One-call selection-sync: mutate the live group transform's member set in
+   * place, or start a fresh `editMany` when no transform is live (#191). This
+   * owns the "live session → `setMembers`, else → `editMany`" branch that every
+   * host otherwise hand-rolls against `activeTransformSession`.
+   *
+   * The facade knows session liveness synchronously — `activeTransformSessionRef`
+   * is cleared inside the settle path, before control returns to host code — so
+   * unlike a host's own `activeTransformSession ? setMembers : editMany` check,
+   * this can never observe a stale ref pointing at an already-settled session.
+   * The settled-race fall-through hosts had to hand-roll for that gap is owned
+   * here instead: a `setMembers` call that (implausibly) still returns
+   * `undefined` falls through to a fresh `editMany` rather than silently
+   * dropping the selection.
+   *
+   * `measures: []` closes any live session (committing every member) and is a
+   * no-op while idle. With a live session, `options` is ignored — session-scoped
+   * state (`sizeAnchor`, box angle, close-on-click-away policy) is sticky per
+   * `setMembers`'s contract; `options` applies only when this call starts a
+   * fresh `editMany`. Exit snapshots are delivered via the session's
+   * `onCommit` — subscribe once in `options.onSession`. The underlying
+   * `editMany` promise is owned by the facade; its abort rejections are
+   * swallowed here (non-abort errors surface as unhandled rejections). Throws
+   * `TypeError` synchronously on duplicate ids, from either path. Starting a
+   * fresh transform preempts any other in-flight draw/edit exactly like
+   * `editMany`.
+   */
+  syncTransformMembers(measures: readonly ControlMeasure[], options?: EditManyOptions): void;
   /**
    * Subscribe to picks on committed control measures.
    *

package/dist/index.mjs

@@ -2737,6 +2737,7 @@ function runGroupTransform(opts) {
 	/** Same click-away suppression role as `edit-controller.ts`'s flag of the same name. */
 	let suppressClickAway = false;
 	const changeListeners = /* @__PURE__ */ new Set();
+	const commitListeners = /* @__PURE__ */ new Set();
 	/** Session-scoped box rotation (ADR-0017 decision #2), shared by the whole group. */
 	let boxAngle = 0;
 	/** The group box fitted over every member's rendered geometry, or `null` when nothing projects this frame. */
@@ -2944,7 +2945,7 @@ function runGroupTransform(opts) {
 			errors.push(err);
 		}
 		if (abortRequested) ctx.fail(new TacticalDrawAbortError("session"));
-		else if (closeRequested) ctx.commit(rebuildRenderedAll);
+		else if (closeRequested) commitClose();
 		else if (rejectRequested && !ctx.settled && members === membersAtEmission) {
 			restorePointsByMember(previousPointsByMember);
 			sizeAnchor = previousSizeAnchor;
@@ -2957,6 +2958,35 @@ function runGroupTransform(opts) {
 		if (errors.length === 1) throw errors[0];
 		if (errors.length > 1) throw new AggregateError(errors, "TransformSession.onChange listener errors");
 	}
+	/**
+	* Deliver a committed exit-snapshot batch to every `onCommit` listener — the
+	* single delivery channel for both the `setMembers`-removed batch and the
+	* close-time batch (#191). Same exception-collection contract as `emitChange`.
+	*/
+	function emitCommit(snapshots) {
+		const errors = [];
+		for (const listener of [...commitListeners]) try {
+			listener(snapshots);
+		} catch (err) {
+			errors.push(err);
+		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "TransformSession.onCommit listener errors");
+	}
+	/**
+	* Commit via `ctx.commit` and emit the close batch to `onCommit` listeners.
+	* The emission happens after the interaction core has settled (teardown and
+	* `onSettled` already ran inside `ctx.commit`), so a listener that calls
+	* `td.render()` sees these members no longer excluded from reconcile — the
+	* fold-then-render pattern works from inside the handler. `undefined` covers
+	* both an already-settled session and a `produce` throw (the promise
+	* rejects); neither emits.
+	*/
+	function commitClose() {
+		const snapshots = ctx.commit(rebuildRenderedAll);
+		if (snapshots !== void 0) emitCommit(snapshots);
+		return snapshots;
+	}
 	function commitGesture(nextConcatPoints, preGestureOptionsOverrideByMember) {
 		if (ctx.settled) return;
 		const previousPointsByMember = clonePointsByMember();
@@ -3034,10 +3064,11 @@ function runGroupTransform(opts) {
 		renderAllPreviews();
 		renderHandlesLayer();
 		recomputeDirty();
+		if (removedSnapshots.length > 0) emitCommit(removedSnapshots);
 		return removedSnapshots;
 	}
 	function close() {
-		return ctx.commit(rebuildRenderedAll);
+		return commitClose();
 	}
 	const session = {
 		get measures() {
@@ -3069,6 +3100,13 @@ function runGroupTransform(opts) {
 			return () => {
 				changeListeners.delete(listener);
 			};
+		},
+		onCommit(listener) {
+			if (ctx.settled) return () => {};
+			commitListeners.add(listener);
+			return () => {
+				commitListeners.delete(listener);
+			};
 		}
 	};
 	let activeBoxDrag = null;
@@ -3173,11 +3211,11 @@ function runGroupTransform(opts) {
 		if (localPreview || localHandles) return;
 		const isMember = localGraphics ? members.some((m) => m.measure.id === localGraphics.id) : false;
 		if (localGraphics && !isMember) {
-			ctx.commit(rebuildRenderedAll);
+			commitClose();
 			if (onClickAwayGraphicsPick) onClickAwayGraphicsPick(localGraphics);
 			return;
 		}
-		ctx.commit(rebuildRenderedAll);
+		commitClose();
 	};
 	const core = runInteraction({
 		adapter,
@@ -3665,6 +3703,11 @@ var TacticalDraw = class {
 	* `measures.length` must be >= 1; a single-element array behaves like an
 	* `edit` with only `transform` mode. Throws `TypeError` synchronously (before
 	* any preemption) for an empty array or duplicate ids.
+	*
+	* For a selection that changes over time (shift-click toggle, marquee
+	* replace), prefer [[syncTransformMembers]] over hand-rolling the
+	* live-session-vs-fresh-`editMany` branch, and subscribe to
+	* `TransformSession.onCommit` as the single fold path for exit snapshots.
 	*/
 	editMany(measures, options) {
 		this.assertAlive();
@@ -3713,6 +3756,42 @@ var TacticalDraw = class {
 		}, extraSettle);
 	}
 	/**
+	* One-call selection-sync: mutate the live group transform's member set in
+	* place, or start a fresh `editMany` when no transform is live (#191). This
+	* owns the "live session → `setMembers`, else → `editMany`" branch that every
+	* host otherwise hand-rolls against `activeTransformSession`.
+	*
+	* The facade knows session liveness synchronously — `activeTransformSessionRef`
+	* is cleared inside the settle path, before control returns to host code — so
+	* unlike a host's own `activeTransformSession ? setMembers : editMany` check,
+	* this can never observe a stale ref pointing at an already-settled session.
+	* The settled-race fall-through hosts had to hand-roll for that gap is owned
+	* here instead: a `setMembers` call that (implausibly) still returns
+	* `undefined` falls through to a fresh `editMany` rather than silently
+	* dropping the selection.
+	*
+	* `measures: []` closes any live session (committing every member) and is a
+	* no-op while idle. With a live session, `options` is ignored — session-scoped
+	* state (`sizeAnchor`, box angle, close-on-click-away policy) is sticky per
+	* `setMembers`'s contract; `options` applies only when this call starts a
+	* fresh `editMany`. Exit snapshots are delivered via the session's
+	* `onCommit` — subscribe once in `options.onSession`. The underlying
+	* `editMany` promise is owned by the facade; its abort rejections are
+	* swallowed here (non-abort errors surface as unhandled rejections). Throws
+	* `TypeError` synchronously on duplicate ids, from either path. Starting a
+	* fresh transform preempts any other in-flight draw/edit exactly like
+	* `editMany`.
+	*/
+	syncTransformMembers(measures, options) {
+		this.assertAlive();
+		const session = this.activeTransformSessionRef;
+		if (session) {
+			if (session.setMembers(measures) !== void 0) return;
+		}
+		if (measures.length === 0) return;
+		this.editMany([...measures], options).catch(ignoreAbort);
+	}
+	/**
 	* Subscribe to picks on committed control measures.
 	*
 	* The graphics layer is pre-bound, and `event.id` is the originating control

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbat-mapper/tactical-draw",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.0-alpha.9",
   "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",