@clarify/edge-router 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -883,11 +883,6 @@ function stampRoutePoint(v) {
 	if (!v.isConnPoint) pt.vn = v.vn;
 	return pt;
 }
-//! @brief   The ConnRef class represents a connector object.
-//!
-//! Connectors are a (possible multi-segment) line between two points.
-//! They are routed intelligently so as not to overlap any of the shape
-//! objects in the Router scene.
 var Edge = class {
 	router;
 	/** @internal */ _id;
@@ -927,33 +922,22 @@ var Edge = class {
 		this.updateEndPoint("src", src);
 		this.updateEndPoint("tar", dst);
 	}
-	//! @brief   Returns a reference to the current raw "debug" route for the connector.
 	route() {
 		return this._route;
 	}
-	//! @brief   Returns a reference to the current display version of the route.
 	displayRoute() {
 		if (this._displayRoute.empty()) this._displayRoute = this._route.simplify();
 		return this._displayRoute;
 	}
-	//! @brief   Returns ConnEnds specifying what this connector is attached to.
 	endpointConnEnds() {
 		let source = this.getConnEndForEndpointVertex(this._srcVert);
 		let destination = this.getConnEndForEndpointVertex(this._dstVert);
 		if (source && destination) return [source, destination];
 		return null;
 	}
-	//! @brief   Returns the obstacle anchors (shape or junction) at each end of
-	//!          this connector.  Either element is null when that endpoint is a
-	//!          free-floating point rather than attached to an anchor.
-	//!
-	//! Mirrors the C++ `ConnRef::endpointAnchors()` (which returns a pair of
-	//! Obstacle pointers).  Used by HyperedgeRerouter to walk hyperedge topology.
 	endpointAnchors() {
 		return [this._srcConnend ? this._srcConnend._anchorObj : null, this._dstConnend ? this._dstConnend._anchorObj : null];
 	}
-	//! @brief  Allows the user to specify a set of checkpoints that this
-	//!         connector will route via.
 	setRoutingCheckpoints(checkpoints) {
 		this._checkpoints = checkpoints;
 		for (const vert of this._checkpointVertices) {
@@ -971,32 +955,22 @@ var Edge = class {
 			this._checkpointVertices.push(vertex);
 		}
 	}
-	//! @brief   Returns the current set of routing checkpoints for this connector.
 	routingCheckpoints() {
 		return this._checkpoints;
 	}
-	//! @brief  Returns candidate destination endpoint positions used by the
-	//!         orthogonal-routing "only-turn-when-aligned" optimisation.
-	//!
-	//! Since shape-pin endpoints are not supported, this is just the junction
-	//! position (or empty for free-floating endpoints).
 	possibleDstPinPoints() {
 		if (this._dstConnend && this._dstConnend.junction()) return [this._dstConnend.position()];
 		return [];
 	}
-	//! @brief  Sets the hat-crossings flag.
 	setHateCrossings(val) {
 		this._hateCrossings = val;
 	}
-	//! @brief  Returns the hat-crossings flag.
 	doesHateCrossings() {
 		return this._hateCrossings;
 	}
-	//! @brief  Sets the route directly (internal use).
 	set_route(route) {
 		this._displayRoute.ps = route.ps.slice();
 	}
-	//! @brief  Generates the path for this connector.
 	generatePath() {
 		if (!this._needsRerouteFlag) return false;
 		if (!this._dstVert || !this._srcVert) return false;
@@ -1222,9 +1196,6 @@ function midVertexNumber(p0, p1, c) {
 	}
 	return 8;
 }
-//! @brief  Break up overlapping parallel segments that are not the same edge
-//!         in the visibility graph, i.e., where one segment is a subsegment
-//!         of another.
 function splitBranchingSegments(poly, polyIsConn, conn, tolerance = 0) {
 	let i = 1;
 	while (i < conn.ps.length) {
@@ -1623,8 +1594,6 @@ var Direction = class Direction extends OptionSet {
 	static inline = new Direction([Direction.inlineStart, Direction.inlineEnd]);
 	static all = new Direction([Direction.block, Direction.inline]);
 };
-//! A point that a connector route must visit, with optional arrival/departure
-//! direction constraints.
 var Checkpoint = class {
 	point;
 	arrivalDirections;
@@ -1635,8 +1604,6 @@ var Checkpoint = class {
 		this.departureDirections = departureDirections;
 	}
 };
-//! Represents one endpoint of a connector — either a free-floating point or
-//! a junction anchor.  Shape-pin endpoints are not supported in this port.
 var Endpoint = class {
 	/** @internal */ _type;
 	/** @internal */ _point;
@@ -1761,9 +1728,6 @@ var VertInf = class {
 		this.isTarEndpoint = roles.isTarEndpoint ?? false;
 		this.isDimensionChangePartner = roles.isDimensionChangePartner ?? false;
 	}
-	//! Replace identity (objID + vn), position, and optionally role flags.
-	//! Use `resetPoint` if only the position needs updating (e.g. when a
-	//! shape moves but keeps the same corner indices).
 	resetIdAndPoint(objID, vn, point, roles) {
 		this.objID = objID;
 		this.vn = vn;
@@ -1771,7 +1735,6 @@ var VertInf = class {
 		this.point.vn = vn;
 		if (roles) this.applyRoles(roles);
 	}
-	//! Update position only; identity (objID + vn) and roles are preserved.
 	resetPoint(point) {
 		this.point = new Point(point.x, point.y);
 		this.point.vn = this.vn;
@@ -1965,10 +1928,6 @@ var Obstacle = class {
 		this._lastVert.shNext = firstVertex;
 		this._firstVert.shPrev = lastVertex;
 	}
-	//! Returns the anchor's centre vertex if it has one — junctions do, shapes
-	//! do not.  Used by HyperedgeRerouter to resolve a junction-anchored
-	//! endpoint into a routable vertex.  Default implementation returns null
-	//! (suitable for ShapeRef); JunctionRef overrides.
 	centreVertex() {
 		return null;
 	}
@@ -2026,7 +1985,6 @@ var Obstacle = class {
 };
 //#endregion
 //#region src/junction.ts
-//! Represents a fixed or free-floating junction between connectors.
 var Junction = class Junction extends Obstacle {
 	followingConns = /* @__PURE__ */ new Set();
 	_position;
@@ -2309,14 +2267,6 @@ function processShiftEvent(scanline, e, dim, pass) {
 		if (!scanline.erase(v)) throw new Error("processShiftEvent: failed to erase Node from scanline");
 	}
 }
-//! @brief   Determines the spatial limits for each shift segment in the given
-//!          dimension.  Mirrors the C++ `buildOrthogonalChannelInfo`.
-//!
-//! For each event scan line we run four passes:
-//!   1) Close handlers (limits from current neighbours)
-//!   2) Remove closing events from the scanline
-//!   3) Add opening events to the scanline
-//!   4) Open handlers (limits from new neighbours)
 function buildOrthogonalChannelInfo(router, dim, segmentList) {
 	if (segmentList.length === 0) return;
 	const altDim = 1 - dim;
@@ -2358,12 +2308,6 @@ function buildOrthogonalChannelInfo(router, dim, segmentList) {
 	}
 	if (scanline.size() !== 0) throw new Error("buildOrthogonalChannelInfo: scanline non-empty after sweep");
 }
-//! @brief   For each orthogonal connector, mark every (segment, point) pair
-//!          where a routing checkpoint lies on the route.  Each match is
-//!          appended to displayRoute.checkpointsOnRoute as [segmentIndex, pt].
-//!
-//! The `segmentIndex` is `ind * 2` for a checkpoint that lands on a bendpoint
-//! and `(ind * 2) - 1` for one that lies along a segment.
 function buildConnectorRouteCheckpointCache(router) {
 	for (const conn of router.connRefs) {
 		const displayRoute = conn.displayRoute();
@@ -2377,8 +2321,6 @@ function buildConnectorRouteCheckpointCache(router) {
 		}
 	}
 }
-//! @brief   Clear the per-route checkpoint cache built by
-//!          buildConnectorRouteCheckpointCache.
 function clearConnectorRouteCheckpointCache(router) {
 	for (const conn of router.connRefs) conn.displayRoute().checkpointsOnRoute = [];
 }
@@ -2386,8 +2328,6 @@ function clearConnectorRouteCheckpointCache(router) {
 //#region src/vpsc.ts
 const ZERO_UPPERBOUND = -1e-10;
 const LAGRANGIAN_TOLERANCE = -1e-4;
-//! Thrown when satisfy() cannot resolve the constraint set (e.g. an equality
-//! cycle).  `path` is the active path of constraints that caused the failure.
 var UnsatisfiableError = class extends Error {
 	path;
 	constructor(path = []) {
@@ -2410,8 +2350,6 @@ var PositionStats = class {
 		this.A2 += wi * ai * ai;
 	}
 };
-//! A variable to be positioned, with a desired position and a weight that
-//! controls how strongly it resists being moved away from that position.
 var Variable = class {
 	id;
 	desiredPosition;
@@ -2430,7 +2368,6 @@ var Variable = class {
 		this.weight = weight;
 		this.scale = scale;
 	}
-	//! Derivative of the local cost wrt this variable's position.
 	dfdv() {
 		return 2 * this.weight * (this.position() - this.desiredPosition);
 	}
@@ -2447,8 +2384,6 @@ var Variable = class {
 		return b.posn + this.offset;
 	}
 };
-//! A separation (or equality) constraint between two Variables of the form
-//! `right.position - left.position >= gap` (or `==` when equality is true).
 var Constraint = class {
 	left;
 	right;
@@ -2465,9 +2400,6 @@ var Constraint = class {
 		this.gap = gap;
 		this.equality = equality;
 	}
-	//! How much slack the constraint has, i.e. `right - left - gap`.  Negative
-	//! values mean the constraint is violated.  Returns Number.MAX_VALUE when
-	//! the constraint has been flagged unsatisfiable.
 	slack() {
 		if (this.unsatisfiable) return Number.MAX_VALUE;
 		if (this.needsScaling) return this.right.scale * this.right.position() - this.gap - this.left.scale * this.left.position();
@@ -2536,9 +2468,6 @@ var ConstraintHeap = class {
 		}
 	}
 };
-//! A connected component of variables linked by active constraints.  Inside a
-//! block all variables move together; the block's `posn` is the optimum of
-//! the unconstrained sub-problem for those variables.
 var Block = class Block {
 	vars = [];
 	posn = 0;
@@ -2564,8 +2493,6 @@ var Block = class Block {
 		this.posn = (this.ps.AD - this.ps.AB) / this.ps.A2;
 		if (Number.isNaN(this.posn)) throw new Error("VPSC: Block.posn became NaN");
 	}
-	//! Recompute posn from the current variable offsets (called after a merge
-	//! or moveBlocks pass).
 	updateWeightedPosition() {
 		this.ps.AB = 0;
 		this.ps.AD = 0;
@@ -2591,9 +2518,6 @@ var Block = class Block {
 		}
 		return h;
 	}
-	//! Merge two blocks across constraint c (selecting which side is `this`
-	//! and which is the merged-in block by size, to keep the operation
-	//! amortised cheap).
 	mergeWith(b, c) {
 		const dist = c.right.offset - c.left.offset - c.gap;
 		const l = c.left.block;
@@ -2602,8 +2526,6 @@ var Block = class Block {
 		else l.mergeInto(r, c, -dist);
 		return b.deleted ? this : b;
 	}
-	//! Merge b into this block across c.  All variables of b are shifted by
-	//! `dist` so that c is satisfied as an equality.
 	/** @internal */
 	mergeInto(b, c, dist) {
 		c.active = true;
@@ -2615,7 +2537,6 @@ var Block = class Block {
 		if (Number.isNaN(this.posn)) throw new Error("VPSC: Block.posn became NaN");
 		b.deleted = true;
 	}
-	//! Move the contents of b's in-heap into this block's in-heap.
 	mergeIn(b) {
 		this.findMinInConstraint();
 		b.findMinInConstraint();
@@ -2714,16 +2635,12 @@ var Block = class Block {
 			this.reset_active_lm(c.left, v);
 		}
 	}
-	//! Find the constraint with the smallest Lagrange multiplier — the one
-	//! most "wanting" to split.
 	findMinLM() {
 		const holder = { c: null };
 		this.reset_active_lm(this.vars[0], null);
 		this.compute_dfdv(this.vars[0], null, holder);
 		return holder.c;
 	}
-	//! Like findMinLM but restricted to the active path between two specific
-	//! variables.  Throws UnsatisfiableError when no such path exists.
 	findMinLMBetween(lv, rv) {
 		this.reset_active_lm(this.vars[0], null);
 		this.compute_dfdv(this.vars[0], null, null);
@@ -2741,8 +2658,6 @@ var Block = class Block {
 		for (const c of v.in) if (this.canFollowLeft(c, u)) this.populateSplitBlock(b, c.left, v);
 		for (const c of v.out) if (this.canFollowRight(c, u)) this.populateSplitBlock(b, c.right, v);
 	}
-	//! Active path between u and v in the block's active-constraint tree.
-	//! Result is pushed into `path` (in reverse order; matches C++).
 	getActivePathBetween(path, u, v, w) {
 		if (u === v) return true;
 		for (const c of u.in) if (this.canFollowLeft(c, w)) {
@@ -2759,8 +2674,6 @@ var Block = class Block {
 		}
 		return false;
 	}
-	//! Search the active tree from u for a directed path of `right` traversals
-	//! to v.
 	isActiveDirectedPathBetween(u, v) {
 		if (u === v) return true;
 		for (const c of u.out) if (this.canFollowRight(c, null)) {
@@ -2778,8 +2691,6 @@ var Block = class Block {
 		}
 		return false;
 	}
-	//! Split this block across the violated path between vl and vr.  Sets `lb`
-	//! and `rb` (returned via a 2-tuple) and marks this block as deleted.
 	splitBetween(vl, vr) {
 		const c = this.findMinLMBetween(vl, vr);
 		const { l, r } = this.split(c);
@@ -2790,7 +2701,6 @@ var Block = class Block {
 			r
 		};
 	}
-	//! Split into two new blocks across c (which becomes inactive).
 	split(c) {
 		c.active = false;
 		const l = new Block(this.blocks);
@@ -2802,7 +2712,6 @@ var Block = class Block {
 			r
 		};
 	}
-	//! Sum of squared distances from desired positions, weighted.
 	cost() {
 		let c = 0;
 		for (const v of this.vars) {
@@ -2812,8 +2721,6 @@ var Block = class Block {
 		return c;
 	}
 };
-//! Container for all current Blocks.  Owns the timestamp counter used by the
-//! priority queues to detect out-of-date heap entries.
 var Blocks = class {
 	blockTimeCtr = 0;
 	m_blocks = [];
@@ -2833,7 +2740,6 @@ var Blocks = class {
 	insert(block) {
 		this.m_blocks.push(block);
 	}
-	//! Topological order on variables derived from the constraint DAG.
 	totalOrder() {
 		const order = [];
 		for (const v of this.vs) v.visited = false;
@@ -2845,8 +2751,6 @@ var Blocks = class {
 		for (const c of v.out) if (!c.right.visited) this.dfsVisit(c.right, order);
 		order.push(v);
 	}
-	//! Process incoming constraints, most violated to least, merging with
-	//! left-neighbour blocks until no more violated in-constraints remain.
 	mergeLeft(r) {
 		r.timeStamp = ++this.blockTimeCtr;
 		r.setUpInConstraints();
@@ -2893,7 +2797,6 @@ var Blocks = class {
 	removeBlock(doomed) {
 		doomed.deleted = true;
 	}
-	//! Drop deleted blocks from the live list.
 	cleanup() {
 		let i = 0;
 		for (let j = 0; j < this.m_blocks.length; j++) {
@@ -2903,9 +2806,6 @@ var Blocks = class {
 		}
 		this.m_blocks.length = i;
 	}
-	//! Split block b across c, then run mergeLeft / mergeRight to consume any
-	//! violations created by the split.  Returns the two surviving blocks (but
-	//! note: they may have been further merged during the rebalance).
 	split(b, c) {
 		const { l, r } = b.split(c);
 		this.m_blocks.push(l);
@@ -2923,16 +2823,12 @@ var Blocks = class {
 			r: rPrime
 		};
 	}
-	//! Total squared cost across all blocks.
 	cost() {
 		let c = 0;
 		for (const b of this.m_blocks) c += b.cost();
 		return c;
 	}
 };
-//! Incremental VPSC solver.  Construct with the variable and constraint
-//! lists, then call `satisfy()` to find a feasible solution or `solve()` to
-//! drive cost to a local minimum.
 var IncSolver = class {
 	splitCnt = 0;
 	bs;
@@ -2962,11 +2858,9 @@ var IncSolver = class {
 		this.inactive = cs.slice();
 		for (const c of this.inactive) c.active = false;
 	}
-	//! Returns the current Blocks container (mainly for tests / debugging).
 	getBlocks() {
 		return this.bs;
 	}
-	//! Returns the variable list (read-only by convention).
 	getVariables() {
 		return this.vs;
 	}
@@ -2984,8 +2878,6 @@ var IncSolver = class {
 			if (Number.isNaN(v.finalPosition)) throw new Error("VPSC: variable finalPosition NaN");
 		}
 	}
-	//! Drive cost(): satisfy() + while-cost-decreases-loop.  Returns true if
-	//! any blocks remain merged at the end (the C++ contract).
 	solve() {
 		this.satisfy();
 		let lastCost = Number.MAX_VALUE;
@@ -3103,12 +2995,6 @@ const freeWeight$1 = 1e-5;
 const strongWeight = .001;
 const strongerWeight = 1;
 const fixedWeight$1 = 1e5;
-//! The concrete ShiftSegment implementation used during orthogonal nudging.
-//!
-//! Each instance represents a segment of a connector's display route that
-//! may be shifted along `dimension`.  Construction takes the low and high
-//! route-index of the segment endpoints; the actual coordinates are read
-//! lazily from `connRef.displayRoute().ps`.
 var NudgingShiftSegment = class {
 	connRef;
 	/** @internal */ variable;
@@ -3169,10 +3055,6 @@ var NudgingShiftSegment = class {
 	get zBend() {
 		return this._zBend;
 	}
-	//! Assign a VPSC Variable describing this segment's desired position and
-	//! how strongly it resists moving.  The `justUnifying` flag distinguishes
-	//! the unifying preprocessing pass from the main nudging pass — see
-	//! ImproveOrthogonalRoutes.execute.
 	createSolverVariable(justUnifying) {
 		const nudgeFinalSegments = this.connRef.router.options.nudgeOrthogonalSegmentsConnectedToShapes;
 		let varID = freeSegmentID$1;
@@ -3192,7 +3074,6 @@ var NudgingShiftSegment = class {
 		} else if (!this.finalSegment) weight = strongWeight;
 		this.variable = new Variable(varID, varPos, weight);
 	}
-	//! Push the solver's chosen position back into the route.
 	updatePositionsFromSolver(_justUnifying) {
 		if (this.fixed) return;
 		let newPos = this.variable.finalPosition;
@@ -3228,10 +3109,6 @@ var NudgingShiftSegment = class {
 		if (this._highC()) return 1;
 		return 0;
 	}
-	//! Returns true if `rhs` shares an overlap with this segment such that the
-	//! two need to be constrained against each other in the nudger.  Counts
-	//! collinear-sharing-endpoint pairs as overlapping so they can be nudged
-	//! apart where possible.
 	overlapsWith(rhsSuper, dim) {
 		const rhs = rhsSuper;
 		const altDim = (dim + 1) % 2;
@@ -3309,9 +3186,6 @@ var NudgingShiftSegment = class {
 };
 //#endregion
 //#region src/utilities/pos-vert-inf.ts
-//! A breakpoint along a candidate visibility segment — a position on the
-//! perpendicular axis combined with the vertex (which may be a shape corner,
-//! a connection point, or a dummy lattice vertex) at that position.
 function sameId(a, b) {
 	return a.objID === b.objID && a.vn === b.vn;
 }
@@ -3446,11 +3320,6 @@ function getPosVertInfDirections(v, dim) {
 	}
 	return 0;
 }
-//! A candidate horizontal/vertical visibility segment produced during sweep.
-//! Stores its extent along the segment axis (`begin`..`finish`) and its
-//! perpendicular position (`pos`), plus a sorted set of vertices that lie on
-//! it (`vertInfs`) and intersection break-points discovered during the cross
-//! sweep (`breakPoints`).
 var LineSegment = class {
 	begin;
 	finish;
@@ -3654,10 +3523,6 @@ var LineSegment = class {
 };
 //#endregion
 //#region src/utilities/segment-list-wrapper.ts
-//! A list of LineSegments with overlap-merging insertion.  The list keeps the
-//! invariant that no two segments overlap; on insertion a new segment that
-//! overlaps existing ones is merged into the first overlap, and subsequent
-//! overlapping segments are merged into the first and removed.
 var SegmentListWrapper = class {
 	/** @internal */ _list = [];
 	insert(segment) {
@@ -3708,8 +3573,6 @@ const channelLeftID = 2;
 const channelRightID = 3;
 const freeWeight = 1e-5;
 const fixedWeight = 1e5;
-//! A pair of unsigned values that can be compared and used as keys.  The
-//! smaller index is stored first so {a,b} and {b,a} compare equal.
 var UnsignedPair = class {
 	_index1;
 	_index2;
@@ -3744,8 +3607,6 @@ var UnsignedPairSet = class {
 		return this._items.size;
 	}
 };
-//! Comparator used when merging NudgingShiftSegments — sorts route indexes by
-//! point position in `dimension`.
 var CmpIndexes = class {
 	connRef;
 	dimension;
@@ -3759,12 +3620,6 @@ var CmpIndexes = class {
 		return a < b ? -1 : a > b ? 1 : 0;
 	}
 };
-//! Given a router and a list of possible horizontal segments, plus a possible
-//! vertical visibility segment, compute and add edges to the orthogonal
-//! visibility graph for all visibility edges.
-//!
-//! Modifies `segments` in place — segments whose finish position is behind
-//! the vertical line are committed and removed.
 function intersectSegments(router, segments, vertLine) {
 	if (segments.length === 0) {
 		vertLine.generateVisibilityEdgesFromBreakpointSet(router, 1);
@@ -3934,10 +3789,6 @@ function processEventHori(router, scanline, segments, e, pass) {
 		if (!scanline.erase(v)) throw new Error("orthogonal: failed to erase Node from scanline");
 	}
 }
-//! Pins or connector endpoints sitting on the leading/trailing edge of the
-//! visibility graph may only have visibility in the outward direction (away
-//! from the graph).  Add the supplied visibility flags so they can still be
-//! reached.
 function fixConnectionPointVisibilityOnOutsideOfVisibilityGraph(events, addedVisibility) {
 	const totalEvents = events.length;
 	if (totalEvents === 0) return;
@@ -3955,12 +3806,6 @@ function fixConnectionPointVisibilityOnOutsideOfVisibilityGraph(events, addedVis
 		if (events[revIndex].v.c) events[revIndex].v.c.visDirections = events[revIndex].v.c.visDirections.add(addedVisibility);
 	}
 }
-//! @brief  Build the static orthogonal visibility graph for the router.
-//!
-//! Runs two sweepline passes (one per dimension) over every obstacle corner,
-//! junction corner (when fixed), and connector endpoint, populating
-//! `router.visOrthogGraph` with the lattice of horizontal/vertical visibility
-//! edges and tagging every vertex with XL_*/XH_*/YL_*/YH_* property flags.
 function generateStaticOrthogonalVisGraph(router) {
 	let events = [];
 	for (const obstacle of router.m_obstacles) {
@@ -4150,9 +3995,6 @@ function buildOrthogonalNudgingSegments(router, dim, segmentList) {
 		}
 	}
 }
-//! Comparator for the line-order sort used during nudging.  Orders segments
-//! that share a position by their PtOrder map ranking, falling back to
-//! fixedOrder / c-bend order for fixed and c-bend segments.
 var CmpLineOrder = class {
 	orders;
 	dimension;
@@ -4160,8 +4002,6 @@ var CmpLineOrder = class {
 		this.orders = orders;
 		this.dimension = dimension;
 	}
-	//! Returns `{ lessThan, comparable }`.  `comparable` is false when the two
-	//! segments can't be ordered against each other.
 	compare(lhsSuper, rhsSuper) {
 		const lhs = lhsSuper;
 		const rhs = rhsSuper;
@@ -4244,9 +4084,6 @@ function linesort(nudgeFinalSegments, origList, comparison) {
 	}
 	return resultList;
 }
-//! A pair of variable indices marking a candidate "potential" equality
-//! constraint between two free segments.  Used in the unifying pass to
-//! greedily glue free segments to the same position.
 var PotentialSegmentConstraint = class {
 	index1;
 	index2;
@@ -4490,25 +4327,13 @@ var ImproveOrthogonalRoutes = class {
 };
 //#endregion
 //#region src/hyperedgetree.ts
-//! Map from a junction to the tree node that represents it.
-//! Map from a VertInf to the tree node it became.
-//! @brief   A node in the hyperedge tree.
-//!
-//! Carries a position, optional junction, optional VertInf marker (used to
-//! identify terminals), and the list of edges incident on this node.
 var HyperedgeTreeNode = class {
 	edges;
 	junction;
 	point;
-	//! VertInf representing the original endpoint of a connector that landed
-	//! at this node.  Used by buildHyperedgeTreeToRoot to remember terminals.
 	finalVertex;
-	//! True if this terminal node is the source of its connector (vs target).
 	isConnectorSource;
-	//! True if this node is the extra dummy endpoint used for connection-pin
-	//! routing — removed from the final route when present.
 	isPinDummyEndpoint;
-	//! Used during recursive traversals to detect cycles.
 	visited;
 	constructor() {
 		this.edges = [];
@@ -4519,20 +4344,9 @@ var HyperedgeTreeNode = class {
 		this.isPinDummyEndpoint = false;
 		this.visited = false;
 	}
-	//! Traverses the tree and writes each branch's path back to its connector's
-	//! display route.  `pass === 0` clears each connector's route; `pass === 1`
-	//! actually writes the points.
 	writeEdgesToConns(ignored, pass, setRouteOps) {
 		for (const curr of this.edges) if (curr !== ignored) curr.writeEdgesToConns(this, pass, setRouteOps);
 	}
-	//! Traverses the tree from a junction outwards, creating fresh ConnRefs
-	//! for each branch.  Each new connector's src endpoint is the junction
-	//! we started at; tar endpoint is set when we reach the next junction or
-	//! a terminal.
-	//!
-	//! The caller supplies a `connFactory` that creates a fresh connector
-	//! attached to the supplied junction; this keeps hyperedgetree.ts free of
-	//! a real ConnRef dependency.
 	addConns(ignored, router, oldConns, conn, connFactory, setConnEndAtTerminal, setConnEndAtJunction) {
 		if (!conn && !this.junction) throw new Error("HyperedgeTreeNode.addConns: conn or junction required");
 		for (const curr of this.edges) if (curr !== ignored) {
@@ -4542,12 +4356,6 @@ var HyperedgeTreeNode = class {
 			curr.addConns(this, router, oldConns, connFactory, setConnEndAtTerminal, setConnEndAtJunction);
 		}
 	}
-	//! Traverses the tree and rewrites connector ConnEnds whose junction
-	//! may have changed during hyperedge improvement.  `forward` tracks the
-	//! traversal direction relative to a connector's src/tar orientation.
-	//!
-	//! The caller supplies `getEnds`, `getEndJunction`, and
-	//! `setEndToJunction` callbacks so we don't depend on ConnRef directly.
 	updateConnEnds(ignored, forward, changedConns, getEnds, setEndToJunction) {
 		for (const edge of this.edges) {
 			if (edge === ignored) continue;
@@ -4563,42 +4371,27 @@ var HyperedgeTreeNode = class {
 			edge.updateConnEnds(this, next, changedConns, getEnds, setEndToJunction);
 		}
 	}
-	//! Traverses the tree and accumulates the JunctionRefs and ConnRefs that
-	//! make up the hyperedge.  Used by HyperedgeImprover to know what objects
-	//! are affected by a re-route.
 	listJunctionsAndConnectors(ignored, junctions, connectors) {
 		if (this.junction) junctions.push(this.junction);
 		for (const curr of this.edges) if (curr !== ignored) curr.listJunctionsAndConnectors(this, junctions, connectors);
 	}
-	//! Returns true if this node cannot be moved during hyperedge improvement.
-	//! Conditions: it has only one edge (a terminal), its junction is fixed.
 	isImmovable() {
 		if (this.edges.length === 1 || this.junction && this.junction.positionFixed()) return true;
 		return false;
 	}
-	//! Recursively deletes the subtree on the other side of every edge
-	//! except `ignored`.  Used to tear down a hyperedge tree.  TS doesn't
-	//! need to free anything; we simply detach edges so GC can collect them.
 	deleteEdgesExcept(ignored) {
 		for (const curr of this.edges) if (curr !== ignored) curr.deleteNodesExcept(this);
 		this.edges = [];
 	}
-	//! Removes a specific edge from this node's edge list (all occurrences).
 	disconnectEdge(edge) {
 		for (let i = this.edges.length - 1; i >= 0; i--) if (this.edges[i] === edge) this.edges.splice(i, 1);
 	}
-	//! Moves every edge attached to `oldNode` to be attached to this node
-	//! instead.  Used when collapsing two coincident nodes into one.
 	spliceEdgesFrom(oldNode) {
 		if (oldNode === this) throw new Error("HyperedgeTreeNode.spliceEdgesFrom: cannot splice from self");
 		while (oldNode.edges.length > 0) oldNode.edges[0].replaceNode(oldNode, this);
 	}
 };
-//! @brief   An edge in the hyperedge tree.  Connects exactly two nodes
-//!          and tracks the connector this segment will become.
 var HyperedgeTreeEdge = class HyperedgeTreeEdge {
-	//! Pair of endpoint nodes; conventionally `first` is the "from" side
-	//! when traversing.  Either can be null briefly during disconnect.
 	ends;
 	conn;
 	constructor(node1, node2, conn) {
@@ -4607,22 +4400,16 @@ var HyperedgeTreeEdge = class HyperedgeTreeEdge {
 		node1.edges.push(this);
 		node2.edges.push(this);
 	}
-	//! Returns the node at the other end from `from`.
 	followFrom(from) {
 		if (this.ends[0] === from) return this.ends[1];
 		return this.ends[0];
 	}
-	//! True when both endpoints share the same position.
 	zeroLength() {
 		return this.ends[0].point.eq(this.ends[1].point);
 	}
-	//! True when both endpoints have the same coordinate along `dimension`
-	//! (i.e. the edge is axis-aligned in that dimension).
 	hasOrientation(dimension) {
 		return this.ends[0].point.at(dimension) === this.ends[1].point.at(dimension);
 	}
-	//! Replaces `oldNode` with `newNode` on whichever side it appears.
-	//! `oldNode` is detached and `newNode` gains the edge in its list.
 	replaceNode(oldNode, newNode) {
 		if (this.ends[0] === oldNode) {
 			oldNode.disconnectEdge(this);
@@ -4634,11 +4421,6 @@ var HyperedgeTreeEdge = class HyperedgeTreeEdge {
 			this.ends[1] = newNode;
 		}
 	}
-	//! Traverses outward from `ignored`, writing the segment between this
-	//! edge's two endpoints into the appropriate connector's display route.
-	//!
-	//! `pass === 0` clears each connector's route; `pass === 1` writes points.
-	//! `setRouteOps` provides connector-side primitives.
 	writeEdgesToConns(ignored, pass, setRouteOps) {
 		if (this.ends[0] === null || this.ends[1] === null) throw new Error("HyperedgeTreeEdge.writeEdgesToConns: edge has null endpoint");
 		if (this.conn === null) throw new Error("HyperedgeTreeEdge.writeEdgesToConns: missing conn");
@@ -4668,9 +4450,6 @@ var HyperedgeTreeEdge = class HyperedgeTreeEdge {
 		}
 		nextNode.writeEdgesToConns(this, pass, setRouteOps);
 	}
-	//! Traverses outwards through this edge, creating connectors as the
-	//! traversal crosses junctions and terminals.  See
-	//! HyperedgeTreeNode.addConns for the callback shape.
 	addConns(ignored, router, oldConns, connFactory, setConnEndAtTerminal, setConnEndAtJunction) {
 		if (this.conn === null) throw new Error("HyperedgeTreeEdge.addConns: missing conn");
 		let endNode = null;
@@ -4685,9 +4464,6 @@ var HyperedgeTreeEdge = class HyperedgeTreeEdge {
 		if (endNode && endNode.finalVertex) setConnEndAtTerminal(this.conn, endNode.finalVertex, oldConns);
 		else if (endNode && endNode.junction) setConnEndAtJunction(this.conn, endNode.junction);
 	}
-	//! Traverses outwards, rewriting connector ConnEnds whose junction
-	//! has been adjusted by hyperedge improvement.  See
-	//! HyperedgeTreeNode.updateConnEnds for callback semantics.
 	updateConnEnds(ignored, forward, changedConns, getEnds, setEndToJunction) {
 		let endNode = null;
 		if (this.ends[0] && this.ends[0] !== ignored) {
@@ -4706,20 +4482,11 @@ var HyperedgeTreeEdge = class HyperedgeTreeEdge {
 			}
 		}
 	}
-	//! Traverses outwards, accumulating the JunctionRefs and ConnRefs in
-	//! the hyperedge.  Records the connector once per traversal.
 	listJunctionsAndConnectors(ignored, junctions, connectors) {
 		if (this.conn && !connectors.includes(this.conn)) connectors.push(this.conn);
 		if (this.ends[0] !== ignored && this.ends[0]) this.ends[0].listJunctionsAndConnectors(this, junctions, connectors);
 		else if (this.ends[1] !== ignored && this.ends[1]) this.ends[1].listJunctionsAndConnectors(this, junctions, connectors);
 	}
-	//! Splits this edge by inserting a fresh node at `point`.  The existing
-	//! edge stays attached to `source` on one side and to the new node on
-	//! the other; a fresh edge connects the new node to the original target.
-	//!
-	//! Returns the newly created node so callers can position more edges off
-	//! it (the C++ creates the new HyperedgeTreeEdge purely for its side
-	//! effect — the constructor wires itself into both endpoint lists).
 	splitFromNodeAtPoint(source, point) {
 		if (this.ends[1] === source) {
 			const tmp = this.ends[0];
@@ -4736,7 +4503,6 @@ var HyperedgeTreeEdge = class HyperedgeTreeEdge {
 		split.edges.push(this);
 		return split;
 	}
-	//! Detaches this edge from both endpoints and clears its `ends` array.
 	disconnectEdge() {
 		if (this.ends[0] === null || this.ends[1] === null) throw new Error("HyperedgeTreeEdge.disconnectEdge: edge already disconnected");
 		this.ends[0].disconnectEdge(this);
@@ -4744,9 +4510,6 @@ var HyperedgeTreeEdge = class HyperedgeTreeEdge {
 		this.ends[0] = null;
 		this.ends[1] = null;
 	}
-	//! Recursively detaches nodes on the other side of this edge (except
-	//! `ignored`).  TS doesn't need to free anything; we null out the
-	//! pointers so GC reclaims the detached subtree.
 	deleteNodesExcept(ignored) {
 		if (this.ends[0] && this.ends[0] !== ignored) this.ends[0].deleteEdgesExcept(this);
 		this.ends[0] = null;
@@ -4835,8 +4598,6 @@ function vertHeapLess(a, b) {
 function edgeHeapLess(a, b) {
 	return a.mtstDist() < b.mtstDist();
 }
-//! @brief   Builds a minimum terminal spanning tree for a set of terminal
-//!          vertices.
 var MinimumTerminalSpanningTree = class {
 	router;
 	terminals;
@@ -4864,13 +4625,9 @@ var MinimumTerminalSpanningTree = class {
 		this.vHeap = new BinaryHeap(vertHeapLess);
 		this.beHeap = new BinaryHeap(edgeHeapLess);
 	}
-	//! Returns the root junction node of the constructed tree (null until
-	//! construct{Sequential,Interleaved}() runs).
 	rootJunction() {
 		return this.m_rootJunction;
 	}
-	//! Tears down the constructed hyperedge tree subtree (callers may instead
-	//! rely on GC; this exists to mirror the C++ destructor).
 	dispose() {
 		if (this.m_rootJunction) {
 			this.m_rootJunction.deleteEdgesExcept(null);
@@ -4897,9 +4654,6 @@ var MinimumTerminalSpanningTree = class {
 		this.allsets.splice(lo, 1);
 		this.allsets.push(merged);
 	}
-	//! Returns the HyperedgeTreeNode for a given vertex, creating it if needed.
-	//! When two vertices end up at the same node, that node becomes a junction.
-	//! Also wires a fresh HyperedgeTreeEdge to `prevNode` if supplied.
 	addNode(vertex, prevNode) {
 		let node;
 		const existing = this.nodes.get(vertex);
@@ -4921,8 +4675,6 @@ var MinimumTerminalSpanningTree = class {
 		if (prevNode) new HyperedgeTreeEdge(prevNode, node, null);
 		return node;
 	}
-	//! Walks backwards along pathNext links, materialising HyperedgeTreeNodes
-	//! and edges as it goes.  Stops when it reaches a junction or terminal.
 	buildHyperedgeTreeToRoot(currVert, prevNode, prevVert, markEdges = false) {
 		if (prevNode && prevNode.junction) return;
 		while (currVert) {
@@ -4943,9 +4695,6 @@ var MinimumTerminalSpanningTree = class {
 			currVert = currVert.pathNext;
 		}
 	}
-	//! Resets sptfDist and treeRootPointer for every vertex on the pathNext
-	//! chain starting at `currVert`.  Returns the old tree-root pointer for
-	//! the first vertex that already had sptfDist === 0.
 	resetDistsForPath(currVert, newRootVertPtr) {
 		if (!currVert) throw new Error("resetDistsForPath: currVert must not be null");
 		let cv = currVert;
@@ -4962,8 +4711,6 @@ var MinimumTerminalSpanningTree = class {
 		}
 		throw new Error("resetDistsForPath: walked off the end");
 	}
-	//! Recursively marks the rest of an existing hyperedge with the new root
-	//! pointer so all vertices on a freshly-committed branch share one root.
 	rewriteRestOfHyperedge(vert, newTreeRootPtr) {
 		vert.setTreeRootPointer(newTreeRootPtr);
 		const edgeList = this.getOrthogonalEdgesFromVertex(vert, null);
@@ -4972,10 +4719,6 @@ var MinimumTerminalSpanningTree = class {
 			if (v.sptfDist === 0) this.rewriteRestOfHyperedge(v, newTreeRootPtr);
 		}
 	}
-	//! Creates (if necessary) and returns the dummy orthogonal partner for a
-	//! given vertex.  The partner sits at the same point but is on a different
-	//! "layer" — turning between the two layers costs `penalty` (default
-	//! bendPenalty).  This models the rectilinear bend cost.
 	orthogonalPartner(vert, penalty = 0) {
 		if (penalty === 0) penalty = this.bendPenalty;
 		if (vert.orthogonalPartner === null) {
@@ -4987,8 +4730,6 @@ var MinimumTerminalSpanningTree = class {
 		}
 		return vert.orthogonalPartner;
 	}
-	//! Removes bridging edges from `beHeap` whose endpoints no longer connect
-	//! distinct trees or whose roots have been pruned.
 	removeInvalidBridgingEdges() {
 		const valid = [];
 		for (const e of this.beHeap.arr) {
@@ -4999,10 +4740,6 @@ var MinimumTerminalSpanningTree = class {
 		}
 		this.beHeap.replaceWith(valid);
 	}
-	//! Returns every orthogonal edge incident on `vert`, paired with the
-	//! "partner" vertex on the other side (which may be `vert`'s real
-	//! neighbour or its orthogonal partner depending on layer).  Pre-computes
-	//! the orthogonal partner if not present.
 	getOrthogonalEdgesFromVertex(vert, prev) {
 		const edgeList = [];
 		if (!vert) throw new Error("getOrthogonalEdgesFromVertex: vert required");
@@ -5027,8 +4764,6 @@ var MinimumTerminalSpanningTree = class {
 		}
 		return edgeList;
 	}
-	//! Builds the MTST using sequential (Dijkstra-then-Kruskal) construction.
-	//! Slower / weaker than the interleaved variant, kept for parity.
 	constructSequential() {
 		const vHeap = new BinaryHeap(vertHeapLess);
 		const beHeap = new BinaryHeap(edgeHeapLess);
@@ -5107,8 +4842,6 @@ var MinimumTerminalSpanningTree = class {
 		this.nodes.clear();
 		this.allsets.length = 0;
 	}
-	//! Builds the MTST using interleaved Dijkstra/Kruskal construction —
-	//! preferred over the sequential variant.
 	constructInterleaved() {
 		this.origTerminals = new Set(this.terminals);
 		const endVert = this.router.vertices.end();
@@ -5165,9 +4898,6 @@ var MinimumTerminalSpanningTree = class {
 		for (const v of this.extraVertices) v.removeFromGraph(false);
 		this.extraVertices.length = 0;
 	}
-	//! Returns true if a new leaf can join an old leaf without introducing a
-	//! bend.  The exact rules depend on whether the old leaf is itself a
-	//! terminal (sptfDist === 0) or a propagated vertex.
 	connectsWithoutBend(oldLeaf, newLeaf) {
 		if (oldLeaf.sptfDist === 0) {
 			let hyperedgeConnection = false;
@@ -5186,8 +4916,6 @@ var MinimumTerminalSpanningTree = class {
 		if (oldLeaf.pathNext) return colinear(oldLeaf.pathNext.point, oldLeaf.point, newLeaf.point);
 		return true;
 	}
-	//! Returns the real vertices of a bridging edge, swapping in orthogonal
-	//! partners when needed to make orientation comparisons meaningful.
 	realVerticesCountingPartners(edge) {
 		const v1 = edge.vert1();
 		const v2 = edge.vert2();
@@ -5199,9 +4927,6 @@ var MinimumTerminalSpanningTree = class {
 		}
 		return [r1, r2];
 	}
-	//! Commits to a particular bridging edge — merges the two terminal trees,
-	//! materialises the path on the HyperedgeTree, and rewrites root pointers
-	//! so all vertices on the committed branch share a single tree root.
 	commitToBridgingEdge(e) {
 		const ends = this.realVerticesCountingPartners(e);
 		const r1 = ends[0].treeRoot();
@@ -5247,17 +4972,6 @@ var MinimumTerminalSpanningTree = class {
 };
 //#endregion
 //#region src/hyperedge.ts
-//! Lists of junctions and connectors created, deleted, and changed during
-//! a hyperedge rerouting or improvement pass.
-//!
-//! `changedConnectorList` is only populated by HyperedgeImprover — for the
-//! rerouter it always stays empty.
-//! A list of newly created junctions.
-//! A list of newly created connectors.
-//! A list of deleted junctions.
-//! A list of deleted connectors.
-//! A list of changed connectors (HyperedgeImprover only — always empty for
-//! HyperedgeRerouter results).
 function getHyperedgeVertex(end, router) {
 	if (end._anchorObj !== null) {
 		const centre = end._anchorObj.centreVertex();
@@ -5279,16 +4993,6 @@ function getHyperedgeVertex(end, router) {
 		vertex
 	};
 }
-//! @brief   The HyperedgeRerouter class is a convenience object used to
-//!          register hyperedges for full rerouting.
-//!
-//! To work with this class, get a reference via `Router.hyperedgeRerouter()`.
-//!
-//! Registering a hyperedge stages it for rerouting — the rerouting itself
-//! happens the next time `Router.route()` is called, just before connector
-//! routes are generated.  After `route()` returns, the caller can read
-//! `newAndDeletedObjectLists(index)` to learn what junctions and connectors
-//! were created and deleted for that hyperedge.
 var HyperedgeRerouter = class {
 	router;
 	hyperedges;
@@ -5298,11 +5002,6 @@ var HyperedgeRerouter = class {
 	m_deleted_connectors_vector = [];
 	m_terminal_vertices_vector = [];
 	m_added_vertices = [];
-	//! How many fresh `VertInf`s `calcHyperedgeConnectors` injected into
-	//! `router.vertices` (free-floating terminals whose position+direction
-	//! didn't match any existing connector endpoint).  Used by `Router.route()`
-	//! to decide whether the static vis graph needs rebuilding before MTST
-	//! runs: zero added → existing visibility is fine, MTST can start.
 	/** @internal */
 	addedVertexCount() {
 		return this.m_added_vertices.length;
@@ -5311,12 +5010,9 @@ var HyperedgeRerouter = class {
 		this.hyperedges = hyperedges;
 		this.router = router;
 	}
-	//! @brief   The number of hyperedges that have been registered.
 	count() {
 		return this.hyperedges.length;
 	}
-	//! @brief   Returns the new/deleted objects for the hyperedge registered at
-	//!          `index`.  Call this after `Router.route()` has run.
 	newAndDeletedObjectLists(index) {
 		if (index > this.count()) throw new Error(`HyperedgeRerouter: index ${index} out of range (count=${this.count()})`);
 		return {
@@ -5402,10 +5098,6 @@ var HyperedgeRerouter = class {
 		}
 	}
 	/** @internal */
-	//! Perform the actual rerouting.  Called from `Router.route()` before
-	//! individual connector routing.  Builds an MTST per registered hyperedge,
-	//! writes the tree back to fresh ConnRef objects, then deletes the old
-	//! junctions and connectors.
 	performRerouting() {
 		this.m_new_junctions_vector = Array.from({ length: this.count() }, () => []);
 		this.m_new_connectors_vector = Array.from({ length: this.count() }, () => []);
@@ -5476,8 +5168,6 @@ function makeSetRouteOps() {
 //#endregion
 //#region src/router.ts
 var Router = class {
-	//! Canonical list of every obstacle (shapes + junctions) known to the
-	//! router.
 	m_obstacles;
 	connRefs;
 	visOrthogGraph;
@@ -5513,9 +5203,6 @@ var Router = class {
 		this._nextObjectId = 1;
 		this.m_in_crossing_rerouting_stage = false;
 	}
-	//! @brief  Returns the next unused internal object id and advances the
-	//!         counter.  Used by `Obstacle` and `ConnRef` to tag their owning
-	//!         `VertInf.objID` and cache keys.  Not part of the public API.
 	/** @internal */
 	_assignObjectId() {
 		return this._nextObjectId++;
@@ -5525,49 +5212,30 @@ var Router = class {
 		obstable.makeActive();
 		return obstable;
 	}
-	//! @brief  Registers a generic obstacle in the router's obstacle list.
-	//!         Called by Obstacle.makeActive — not part of the public API.
 	/** @internal */
 	addObstacle(obstacle) {
 		this.m_obstacles.push(obstacle);
 	}
-	//! @brief  Removes a generic obstacle.  Called by Obstacle.makeInactive.
 	/** @internal */
 	removeObstacle(obstacle) {
 		const idx = this.m_obstacles.indexOf(obstacle);
 		if (idx !== -1) this.m_obstacles.splice(idx, 1);
 	}
-	//! @brief  Adds a junction to the router scene.  Called from the
-	//!         JunctionRef constructor.
 	addJunction(junction) {
 		junction.makeActive();
 	}
-	//! @brief  Remove a connector from the router scene.
-	//!
-	//! Called from JunctionRef.removeJunctionAndMergeConnectors — applications
-	//! that want to remove a connector should use this method (instead of the
-	//! C++ deleteConnector → ActionInfo dance).
 	deleteConnector(connector) {
 		connector.makeInactive();
 	}
-	//! @brief  Remove a junction from the router scene.
-	//!
-	//! Called from JunctionRef.removeJunctionAndMergeConnectors — applications
-	//! can also call it directly.
 	deleteJunction(junction) {
 		if (junction.isActive()) {
 			junction.removeFromGraph();
 			junction.makeInactive();
 		}
 	}
-	//! @brief  Returns whether the router is currently in the crossing-penalty
-	//!         rerouting stage.  Used by makepath to suppress some penalties
-	//!         during the first routing pass.
 	isInCrossingPenaltyReroutingStage() {
 		return this.m_in_crossing_rerouting_stage;
 	}
-	//! @brief  Rebuild the static orthogonal visibility graph if it's been
-	//!         invalidated.  See orthogonal.ts.
 	regenerateStaticBuiltGraph() {
 		this.visOrthogGraph.clear();
 		generateStaticOrthogonalVisGraph(this);
@@ -5586,18 +5254,6 @@ var Router = class {
 		}
 		return this.hyperedgesForRerouting.length - 1;
 	}
-	//! @brief  Run the orthogonal routing pipeline over every active connector.
-	//!
-	//! Replaces the C++ `processTransaction` minus the action-replay machinery.
-	//! Pipeline:
-	//!   1. Rebuild the static orthogonal visibility graph (stub — TODO(orthogonal)).
-	//!   2. Walk connRefs and call generatePath() on each.  Connectors whose
-	//!      `_needsRerouteFlag` / `_falsePath` is false are no-ops, so this is
-	//!      safe to call after each individual mutation.
-	//!   3. Nudge orthogonal routes (stub — TODO(orthogonal)).
-	//!   4. Improve hyperedge routes (stub — TODO(hyperedgeimprover)).
-	//!
-	//! @return  true if any connector had its route updated.
 	route() {
 		this.regenerateStaticBuiltGraph();
 		let rerouted = /* @__PURE__ */ new Set();