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

package/dist/index.d.mts

@@ -490,6 +490,24 @@ interface InteractionStyle {
  */
 type EditMode = "reshape" | "transform" | "delete";
 //#endregion
+//#region src/tactical-draw/session-events.d.ts
+/**
+ * The reason a session (`TransformSession`, `EditSession`, or `DrawSession`)
+ * settled, delivered to that session's `onSettled` handler (#191 / #194 /
+ * #197). `"close"` covers every commit path of the owning session —
+ * `TransformSession.close()` / `EditSession.close()` / `DrawSession.commit()`,
+ * a click-away close, a gesture commit (dblclick, a second click/tap on the
+ * finishing vertex, a click on another graphics-layer measure), or
+ * `TransformSession.setMembers([])`. `"error"` is the commit-time snapshot
+ * build throwing (the outer promise rejects with that error, not a
+ * `TacticalDrawAbortError`). The remaining values replay
+ * `TacticalDrawAbortError.reason` verbatim: `"escape"`, `"signal"`,
+ * `"session"` (`session.abort()` / `event.abort()`), `"preempted"`,
+ * `"destroyed"`, and `"removed"` (edit / transform only — a measure dropped
+ * from `td.render()`'s measure set).
+ */
+type SettleReason = "close" | "error" | TacticalDrawAbortReason;
+//#endregion
 //#region src/tactical-draw/edit-session.d.ts
 /**
  * Surface delivered via `td.edit(measure, opts).onSession` and synchronously
@@ -497,7 +515,8 @@ type EditMode = "reshape" | "transform" | "delete";
  *
  * `measure` is the immutable edit-start input. `controlPoints` is live working
  * state. After the session settles (`close` / `abort`), every method is a
- * silent no-op.
+ * silent no-op (except [[onSettled]] — late registration still delivers,
+ * asynchronously).
  */
 interface EditSession {
   /** Immutable edit-start input. */
@@ -557,6 +576,47 @@ interface EditSession {
    * have run.
    */
   onChange(listener: (event: EditChangeEvent) => void): () => void;
+  /**
+   * Subscribe to the committed snapshot — the single delivery channel for the
+   * `ControlMeasureSnapshot` this session ever commits (#197, mirroring
+   * `TransformSession.onCommit` #191). Fires exactly once, synchronously from
+   * within the [[close]] call that produced it (`session.close()`,
+   * `event.close()` from [[onChange]], a click-away close, or a click on
+   * another graphics-layer measure), with the same reference [[close]]
+   * returns and the outer `edit` promise resolves with. Never fires on abort.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]]. Returns an unsubscribe function; registering after the
+   * session has settled returns a no-op unsubscribe and the listener never
+   * fires.
+   */
+  onCommit(handler: (snapshot: ControlMeasureSnapshot) => void): () => void;
+  /**
+   * Subscribe to the session's settlement — the lifecycle complement of
+   * [[onCommit]]: `onCommit` delivers *what* was committed, `onSettled` says
+   * the session is *over* and why (#197, mirroring
+   * `TransformSession.onSettled` #194). Fires exactly once, when the session
+   * settles by any path, commit or abort, with a `SettleReason`.
+   *
+   * - On the commit path it fires **after** [[onCommit]]'s emission, so a
+   *   listener that clears selection state observes a document that already
+   *   contains the committed snapshot.
+   * - On every path it fires **after** the facade has already cleared
+   *   `td.activeSession` — so fold-then-render works from inside the handler.
+   * - `reason` distinguishes commit from abort but is deliberately coarse —
+   *   no payload; the snapshot was already delivered through [[onCommit]].
+   *
+   * Registering after the session has already settled is **not** a no-op
+   * (unlike [[onChange]] / [[onCommit]]): the handler is invoked
+   * asynchronously (on a microtask) exactly once with the settle reason;
+   * unsubscribing before that microtask runs cancels the delivery.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]] / [[onCommit]]. Returns an unsubscribe function.
+   */
+  onSettled(handler: (reason: SettleReason) => void): () => void;
 }
 /**
  * Delivered to `EditSession.onChange` listeners once per completed gesture.
@@ -586,17 +646,6 @@ interface EditChangeEvent {
 }
 //#endregion
 //#region src/tactical-draw/transform-session.d.ts
-/**
- * The reason a `TransformSession` settled, delivered to [[TransformSession.onSettled]].
- * `"close"` covers every commit path — `close()`, `setMembers([])`, a
- * click-away close, or `TransformChangeEvent.close()`. `"error"` is the
- * close-time snapshot build throwing (the `editMany` promise rejected with
- * that error, not a `TacticalDrawAbortError`). The remaining values mirror
- * `TacticalDrawAbortError.reason` exactly: `"escape"`, `"signal"`, `"session"`
- * (`session.abort()` / `event.abort()`), `"preempted"`, `"destroyed"`, and
- * `"removed"` (a member dropped from `td.render()`'s measure set).
- */
-type SettleReason = "close" | "error" | TacticalDrawAbortReason;
 /**
  * Surface delivered via `td.editMany(measures, opts).onSession` and
  * synchronously available from `td.activeTransformSession` while the group
@@ -793,7 +842,8 @@ interface TransformChangeEvent {
  * kinds. Also available from `td.activeSession` while the draw is live.
  *
  * After the draw has settled — either via `commit()` returning `true` or
- * `abort()` resolving — every method is a silent no-op.
+ * `abort()` resolving — every method is a silent no-op (except [[onSettled]]
+ * — late registration still delivers, asynchronously).
  */
 interface DrawSession {
   /** Live snapshot of the committed control points. Copy on read. */
@@ -815,6 +865,45 @@ interface DrawSession {
    * are collected and rethrown after all listeners run.
    */
   onChange(listener: (session: DrawSession) => void): () => void;
+  /**
+   * Subscribe to the committed snapshot — the single delivery channel for the
+   * `ControlMeasureSnapshot` this session ever commits (#197, mirroring
+   * `TransformSession.onCommit` #191). Fires exactly once, synchronously from
+   * within the commit that produced it (`session.commit()`, dblclick, or a
+   * second click/tap on the finishing vertex), with the same reference the
+   * outer `draw` promise resolves with — the committed snapshot, not just the
+   * measure. Never fires on abort.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]]. Returns an unsubscribe function; registering after the
+   * session has settled returns a no-op unsubscribe and the listener never
+   * fires.
+   */
+  onCommit(handler: (snapshot: ControlMeasureSnapshot) => void): () => void;
+  /**
+   * Subscribe to the session's settlement — the lifecycle complement of
+   * [[onCommit]]: `onCommit` delivers *what* was committed, `onSettled` says
+   * the session is *over* and why (#197, mirroring
+   * `TransformSession.onSettled` #194). Fires exactly once, when the session
+   * settles by any path, commit or abort, with a `SettleReason`.
+   *
+   * - On the commit path it fires **after** [[onCommit]]'s emission.
+   * - On every path it fires **after** the facade has already cleared
+   *   `td.activeSession` — so fold-then-render works from inside the handler.
+   * - `reason` distinguishes commit from abort but is deliberately coarse —
+   *   no payload; the snapshot was already delivered through [[onCommit]].
+   *
+   * Registering after the session has already settled is **not** a no-op
+   * (unlike [[onChange]] / [[onCommit]]): the handler is invoked
+   * asynchronously (on a microtask) exactly once with the settle reason;
+   * unsubscribing before that microtask runs cancels the delivery.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]] / [[onCommit]]. Returns an unsubscribe function.
+   */
+  onSettled(handler: (reason: SettleReason) => void): () => void;
 }
 //#endregion
 //#region src/tactical-draw/tactical-draw.d.ts
@@ -1144,6 +1233,12 @@ declare class TacticalDraw {
    * `opts.onSession` and commit on `session.commit()`, `dblclick`, or a second
    * click on the last added control point. All paths reject with
    * `TacticalDrawAbortError` on signal / Escape / destroy / `session.abort()`.
+   *
+   * For a variable-length draw, `DrawSession.onCommit` is the single delivery
+   * channel for the committed snapshot and `DrawSession.onSettled` is the
+   * lifecycle signal for when the session is over and why (#197) — together
+   * they make the returned promise non-load-bearing for hosts that adopt them.
+   * Fixed-length kinds have no session and settle only through the promise.
    */
   draw<K extends ControlMeasureKind>(draft: DrawMeasureDraft<K>, options?: DrawOptions): Promise<ControlMeasureSnapshot<K>>;
   /**
@@ -1155,6 +1250,11 @@ declare class TacticalDraw {
    * Default click-away (`closeOnClickAway: true`) closes the edit on a click
    * outside the preview / handle features. Hosts that own close policy pass
    * `false`.
+   *
+   * `EditSession.onCommit` is the single delivery channel for the committed
+   * snapshot and `EditSession.onSettled` is the lifecycle signal for when the
+   * session is over and why (#197) — together they make the returned promise
+   * non-load-bearing for hosts that adopt them.
    */
   edit(measure: ControlMeasure, options?: EditOptions): Promise<ControlMeasureSnapshot>;
   /**

package/dist/index.mjs

@@ -1007,6 +1007,117 @@ function outlinePreview$1(points) {
 	return features;
 }
 //#endregion
+//#region src/tactical-draw/session-events.ts
+/**
+* Map a settle-time error to its `SettleReason`: a `TacticalDrawAbortError`
+* replays its own `reason` verbatim; anything else (a `produce` throw from
+* `ctx.commit`) is the commit-time snapshot build failing, reported as
+* `"error"`.
+*/
+function settleReasonFromError(error) {
+	return isTacticalDrawAbortError(error) ? error.reason : "error";
+}
+/**
+* Fan a `runInteraction` settlement out to a session's commit + settle
+* emitters — the shared body of the `onSettled` wrappers in the edit and draw
+* controllers (transform emits its close-path settle from `commitClose`
+* instead, so it does not use this). On the commit path, emit the snapshot
+* then the `"close"` settle in a try/finally so a throwing `onCommit` listener
+* cannot starve the settle emission; on the reject path, emit the settle with
+* the reason derived from the error. Callers run their own facade
+* slot-clearing (`onSettled()`) before this so a listener observes a cleared
+* `td.activeSession`.
+*/
+function settleFromInteraction(settlement, commitEmitter, settleEmitter) {
+	if (settlement.status === "committed") try {
+		commitEmitter.emit(settlement.value);
+	} finally {
+		settleEmitter.emit("close");
+	}
+	else settleEmitter.emit(settleReasonFromError(settlement.error));
+}
+/**
+* Subscribe/emit machinery shared by `TransformSession.onSettled`,
+* `EditSession.onSettled`, and `DrawSession.onSettled` (#191 / #194 / #197):
+* a settle-exactly-once latch, synchronous emission to every listener with
+* exception collection (single rethrow, `AggregateError` otherwise when more
+* than one listener throws), and a late-registration path that delivers the
+* latched reason on a microtask exactly once when a handler subscribes after
+* the session has already settled.
+*
+* `listenerErrorsMessage` becomes the `AggregateError` message — pass a
+* session-specific string (e.g. `"EditSession.onSettled listener errors"`).
+*/
+function createSettleEmitter(listenerErrorsMessage) {
+	const listeners = /* @__PURE__ */ new Set();
+	/** Set exactly once, by `emit` — also the "has settled" latch and the reason replayed to late registrations. */
+	let settledReason = null;
+	return {
+		emit(reason) {
+			if (settledReason !== null) return;
+			settledReason = reason;
+			const current = [...listeners];
+			listeners.clear();
+			const errors = [];
+			for (const listener of current) try {
+				listener(reason);
+			} catch (err) {
+				errors.push(err);
+			}
+			if (errors.length === 1) throw errors[0];
+			if (errors.length > 1) throw new AggregateError(errors, listenerErrorsMessage);
+		},
+		register(handler) {
+			if (settledReason !== null) {
+				const reason = settledReason;
+				let cancelled = false;
+				queueMicrotask(() => {
+					if (!cancelled) handler(reason);
+				});
+				return () => {
+					cancelled = true;
+				};
+			}
+			listeners.add(handler);
+			return () => {
+				listeners.delete(handler);
+			};
+		}
+	};
+}
+/**
+* Subscribe/emit machinery shared by `TransformSession.onCommit`,
+* `EditSession.onCommit`, and `DrawSession.onCommit`: a listener set with
+* synchronous, exception-collecting emission (single rethrow, `AggregateError`
+* otherwise). Unlike `createSettleEmitter`, `emit` may be called more than
+* once — a transform's `setMembers` can commit several removal batches before
+* the close batch — and there is no latch or late-registration path:
+* registration-time `ctx.settled` guards stay in the controllers, mirroring
+* `onChange`.
+*/
+function createCommitEmitter(listenerErrorsMessage) {
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		emit(value) {
+			const current = [...listeners];
+			const errors = [];
+			for (const listener of current) try {
+				listener(value);
+			} catch (err) {
+				errors.push(err);
+			}
+			if (errors.length === 1) throw errors[0];
+			if (errors.length > 1) throw new AggregateError(errors, listenerErrorsMessage);
+		},
+		register(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+//#endregion
 //#region src/tactical-draw/draw-controller-variable.ts
 const PREVIEW_CM_ID = "__td_preview__";
 const PREVIEW_CURSOR = "crosshair";
@@ -1064,6 +1175,8 @@ function runVariableLengthDraw(options) {
 	let ctx;
 	const savedCursor = "";
 	const changeListeners = /* @__PURE__ */ new Set();
+	const commitEmitter = createCommitEmitter("DrawSession.onCommit listener errors");
+	const settleEmitter = createSettleEmitter("DrawSession.onSettled listener errors");
 	function canCommitNow() {
 		const n = committed.length;
 		if (typeof max === "number" && n > max) return false;
@@ -1100,6 +1213,13 @@ function runVariableLengthDraw(options) {
 			return () => {
 				changeListeners.delete(listener);
 			};
+		},
+		onCommit(listener) {
+			if (ctx.settled) return () => {};
+			return commitEmitter.register(listener);
+		},
+		onSettled(handler) {
+			return settleEmitter.register(handler);
 		}
 	};
 	function fireChange() {
@@ -1199,7 +1319,10 @@ function runVariableLengthDraw(options) {
 		signal,
 		layers: [previewLayer, guideLayer],
 		onViewChange: rescaleOnViewChange,
-		onSettled,
+		onSettled: (settlement) => {
+			if (onSettled) onSettled();
+			settleFromInteraction(settlement, commitEmitter, settleEmitter);
+		},
 		attach(c) {
 			ctx = c;
 			c.onTeardown(() => {
@@ -1897,6 +2020,8 @@ function runEdit(opts) {
 	*/
 	let pendingModes = null;
 	const changeListeners = /* @__PURE__ */ new Set();
+	const commitEmitter = createCommitEmitter("EditSession.onCommit listener errors");
+	const settleEmitter = createSettleEmitter("EditSession.onSettled listener errors");
 	/**
 	* The transform box's rotation, in radians, session-scoped (ADR-0017 decision
 	* #2): starts at `0` (axis-aligned) and accumulates every committed rotate
@@ -2300,6 +2425,13 @@ function runEdit(opts) {
 				changeListeners.delete(listener);
 			};
 		},
+		onCommit(listener) {
+			if (ctx.settled) return () => {};
+			return commitEmitter.register(listener);
+		},
+		onSettled(handler) {
+			return settleEmitter.register(handler);
+		},
 		[COMMIT_GESTURE_FOR_TEST]: (nextPoints) => {
 			commitGesture(nextPoints);
 		},
@@ -2553,7 +2685,10 @@ function runEdit(opts) {
 			handlesLayer
 		],
 		onViewChange: rescaleOnViewChange,
-		onSettled,
+		onSettled: (settlement) => {
+			if (onSettled) onSettled();
+			settleFromInteraction(settlement, commitEmitter, settleEmitter);
+		},
 		attach(c) {
 			ctx = c;
 			driver = adapter.createEditPointerDriver();
@@ -2746,10 +2881,8 @@ 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();
-	const settleListeners = /* @__PURE__ */ new Set();
-	/** Set exactly once, by `emitSettled` — also the "has settled been emitted" latch and the reason replayed to late registrations. */
-	let settledReason = null;
+	const commitEmitter = createCommitEmitter("TransformSession.onCommit listener errors");
+	const settleEmitter = createSettleEmitter("TransformSession.onSettled listener errors");
 	/** 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. */
@@ -2971,51 +3104,6 @@ function runGroupTransform(opts) {
 		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");
-	}
-	/**
-	* Map a settle-time error to its `SettleReason`: a `TacticalDrawAbortError`
-	* replays its own `reason` verbatim; anything else (a `produce` throw from
-	* `ctx.commit`) is the close-time snapshot build failing, reported as
-	* `"error"`.
-	*/
-	function settleReasonFromError(error) {
-		return isTacticalDrawAbortError(error) ? error.reason : "error";
-	}
-	/**
-	* Deliver the session's settlement to every `onSettled` listener — fires
-	* exactly once, whichever path settles first wins the reason. Mirrors
-	* `emitCommit`'s exception-collection contract (one throw if single,
-	* `AggregateError` otherwise), so a throwing listener cannot suppress a
-	* later one nor leave `settledReason` unset.
-	*/
-	function emitSettled(reason) {
-		if (settledReason !== null) return;
-		settledReason = reason;
-		const listeners = [...settleListeners];
-		settleListeners.clear();
-		const errors = [];
-		for (const listener of listeners) try {
-			listener(reason);
-		} catch (err) {
-			errors.push(err);
-		}
-		if (errors.length === 1) throw errors[0];
-		if (errors.length > 1) throw new AggregateError(errors, "TransformSession.onSettled listener errors");
-	}
-	/**
 	* Commit via `ctx.commit` and emit the close batch to `onCommit` listeners,
 	* then emit the settle to `onSettled` listeners (#194) — in a try/finally so
 	* a throwing `onCommit` listener cannot starve the settle emission. The
@@ -3031,9 +3119,9 @@ function runGroupTransform(opts) {
 	function commitClose() {
 		const snapshots = ctx.commit(rebuildRenderedAll);
 		if (snapshots !== void 0) try {
-			emitCommit(snapshots);
+			commitEmitter.emit(snapshots);
 		} finally {
-			emitSettled("close");
+			settleEmitter.emit("close");
 		}
 		return snapshots;
 	}
@@ -3114,7 +3202,7 @@ function runGroupTransform(opts) {
 		renderAllPreviews();
 		renderHandlesLayer();
 		recomputeDirty();
-		if (removedSnapshots.length > 0) emitCommit(removedSnapshots);
+		if (removedSnapshots.length > 0) commitEmitter.emit(removedSnapshots);
 		return removedSnapshots;
 	}
 	function close() {
@@ -3153,26 +3241,10 @@ function runGroupTransform(opts) {
 		},
 		onCommit(listener) {
 			if (ctx.settled) return () => {};
-			commitListeners.add(listener);
-			return () => {
-				commitListeners.delete(listener);
-			};
+			return commitEmitter.register(listener);
 		},
 		onSettled(handler) {
-			if (settledReason !== null) {
-				const reason = settledReason;
-				let cancelled = false;
-				queueMicrotask(() => {
-					if (!cancelled) handler(reason);
-				});
-				return () => {
-					cancelled = true;
-				};
-			}
-			settleListeners.add(handler);
-			return () => {
-				settleListeners.delete(handler);
-			};
+			return settleEmitter.register(handler);
 		}
 	};
 	let activeBoxDrag = null;
@@ -3290,7 +3362,7 @@ function runGroupTransform(opts) {
 		onViewChange: rescaleOnViewChange,
 		onSettled: (settlement) => {
 			if (onSettled) onSettled();
-			if (settlement.status === "rejected") emitSettled(settleReasonFromError(settlement.error));
+			if (settlement.status === "rejected") settleEmitter.emit(settleReasonFromError(settlement.error));
 		},
 		attach(c) {
 			ctx = c;
@@ -3655,6 +3727,12 @@ var TacticalDraw = class {
 	* `opts.onSession` and commit on `session.commit()`, `dblclick`, or a second
 	* click on the last added control point. All paths reject with
 	* `TacticalDrawAbortError` on signal / Escape / destroy / `session.abort()`.
+	*
+	* For a variable-length draw, `DrawSession.onCommit` is the single delivery
+	* channel for the committed snapshot and `DrawSession.onSettled` is the
+	* lifecycle signal for when the session is over and why (#197) — together
+	* they make the returned promise non-load-bearing for hosts that adopt them.
+	* Fixed-length kinds have no session and settle only through the promise.
 	*/
 	draw(draft, options) {
 		this.assertAlive();
@@ -3713,6 +3791,11 @@ var TacticalDraw = class {
 	* Default click-away (`closeOnClickAway: true`) closes the edit on a click
 	* outside the preview / handle features. Hosts that own close policy pass
 	* `false`.
+	*
+	* `EditSession.onCommit` is the single delivery channel for the committed
+	* snapshot and `EditSession.onSettled` is the lifecycle signal for when the
+	* session is over and why (#197) — together they make the returned promise
+	* non-load-bearing for hosts that adopt them.
 	*/
 	edit(measure, options) {
 		this.assertAlive();

package/package.json

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