@istar-ts/core 0.14.2 → 0.15.0-beta.1

package/dist/index.js

@@ -762,14 +762,204 @@ function defaultHubPosition(model, source, target, size) {
 		y: (a.y + b.y) / 2 - size.height / 2
 	};
 }
+/** Space kept between inner elements and an actor's boundary (piStar's `updateBoundary` adds 10px). */
+const ACTOR_PADDING = 10;
+/** A kind's default size, absent any per-host override (see `actorBounds`' `defaultSizeOf`). */
+function metamodelSizeOf(metamodel, kind) {
+	return metamodel.elements.get(kind)?.size ?? {
+		width: 0,
+		height: 0
+	};
+}
+/**
+* An actor's boundary: the kind's default-size rectangle at the actor's position, grown to
+* include every inner element (each padded by `ACTOR_PADDING`), like piStar's `updateBoundary`
+* (which floors on the kind's default size, not the actor's last expanded `display` size; an
+* inner element's own `display` size does override, same as its rendered size elsewhere).
+* Shared by `@istar-ts/react`'s node layout and `@istar-ts/glsp`'s GModel, so an actor draws the
+* same box in both: children are looked up by category (`metamodelOf`), not `istar.*` names.
+*
+* `defaultSizeOf` resolves a kind's default size; it defaults to the metamodel's, but a host
+* whose registry overrides a kind's size independently of the metamodel (`@istar-ts/react`'s
+* `IstarRegistry`) must pass one that reads its own sizes, or its boundary would stop matching
+* what it actually draws.
+*/
+function actorBounds(model, actorId, metamodel = metamodelOf(model), defaultSizeOf = (kind) => metamodelSizeOf(metamodel, kind)) {
+	const actor = model.elements.get(actorId);
+	if (!actor) throw new Error(`no element "${actorId}" in the model`);
+	const meta = metamodel;
+	const ownSize = defaultSizeOf(actor.kind);
+	let minX = actor.x;
+	let minY = actor.y;
+	let maxX = actor.x + ownSize.width;
+	let maxY = actor.y + ownSize.height;
+	for (const child of model.elements.values()) {
+		if (child.parent !== actorId) continue;
+		if (meta.elements.get(child.kind)?.category === "actor") continue;
+		const base = defaultSizeOf(child.kind);
+		const width = child.display?.width ?? base.width;
+		const height = child.display?.height ?? base.height;
+		minX = Math.min(minX, child.x - 10);
+		minY = Math.min(minY, child.y - 10);
+		maxX = Math.max(maxX, child.x + width + 10);
+		maxY = Math.max(maxY, child.y + height + 10);
+	}
+	return {
+		x: minX,
+		y: minY,
+		width: maxX - minX,
+		height: maxY - minY
+	};
+}
+/** Space kept between a suggested box and any existing element (`suggestPosition`). */
+const SUGGEST_MARGIN = 20;
+/** Step between candidate positions on the grid `suggestPosition` scans. */
+const SUGGEST_STEP = 40;
+/** How many rings out `suggestPosition` scans before falling back to `guaranteedFreePoint`. */
+const SUGGEST_MAX_RING = 25;
+function boxesOverlap(a, b) {
+	return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+function padded(box, margin) {
+	return {
+		x: box.x - margin,
+		y: box.y - margin,
+		width: box.width + margin * 2,
+		height: box.height + margin * 2
+	};
+}
+function firstFreeCandidate(candidates, size, obstacles, fallback) {
+	for (const point of candidates) {
+		const box = {
+			x: point.x,
+			y: point.y,
+			width: size.width,
+			height: size.height
+		};
+		if (!obstacles.some((obstacle) => boxesOverlap(padded(box, 20), obstacle))) return point;
+	}
+	return fallback;
+}
+/**
+* A point guaranteed to overlap no obstacle, however dense the model: past the right edge of
+* every obstacle's box, so no obstacle can reach it regardless of its y (`suggestPosition`'s
+* last-resort fallback, once every ring candidate is taken).
+*/
+function guaranteedFreePoint(obstacles, referenceY) {
+	if (obstacles.length === 0) return {
+		x: 0,
+		y: referenceY
+	};
+	return {
+		x: Math.max(...obstacles.map((box) => box.x + box.width)) + 20,
+		y: referenceY
+	};
+}
+/** Candidate positions in expanding square rings around `center`, in a fixed scan order. */
+function ringCandidates(center, maxRing) {
+	const points = [center];
+	for (let ring = 1; ring <= maxRing; ring++) {
+		const offset = ring * SUGGEST_STEP;
+		for (let dx = -offset; dx <= offset; dx += SUGGEST_STEP) {
+			points.push({
+				x: center.x + dx,
+				y: center.y - offset
+			});
+			points.push({
+				x: center.x + dx,
+				y: center.y + offset
+			});
+		}
+		for (let dy = -offset + SUGGEST_STEP; dy <= offset - SUGGEST_STEP; dy += SUGGEST_STEP) {
+			points.push({
+				x: center.x - offset,
+				y: center.y + dy
+			});
+			points.push({
+				x: center.x + offset,
+				y: center.y + dy
+			});
+		}
+	}
+	return points;
+}
+function modelBoxes(model, defaultSizeOf) {
+	const boxes = [];
+	for (const element of model.elements.values()) {
+		const base = defaultSizeOf(element.kind);
+		const width = element.display?.width ?? base.width;
+		const height = element.display?.height ?? base.height;
+		boxes.push({
+			x: element.x,
+			y: element.y,
+			width,
+			height
+		});
+	}
+	return boxes;
+}
+/**
+* A free spot for a new element of `kind`, overlapping no existing element (sizes from the
+* metamodel, or `defaultSizeOf` for a host with its own size overrides, as in `actorBounds`).
+*
+* Scans a deterministic, fixed-order set of candidates — rings around `near` when given, else
+* the container's interior, else rings around the origin — and returns the first whose padded
+* box (`SUGGEST_MARGIN`) overlaps nothing; same input always yields the same output. However
+* dense the model, the result never overlaps: once every ring candidate is taken, it falls back
+* to a point past the right edge of every obstacle (`guaranteedFreePoint`).
+*
+* Inside `containerId`, the candidate stays within the actor's current boundary (`actorBounds`)
+* when there is room, or goes just past its last child when the boundary is full — the boundary
+* grows from there, same as any other inner element (`actorBounds`).
+*/
+function suggestPosition(model, options) {
+	const metamodel = options.metamodel ?? metamodelOf(model);
+	const defaultSizeOf = options.defaultSizeOf ?? ((kind) => metamodelSizeOf(metamodel, kind));
+	const size = defaultSizeOf(options.kind);
+	const obstacles = modelBoxes(model, defaultSizeOf);
+	const near = typeof options.near === "string" ? model.elements.get(options.near) : options.near;
+	const nearPoint = near ? "kind" in near ? {
+		x: near.x,
+		y: near.y
+	} : near : void 0;
+	if (options.containerId) {
+		const bounds = actorBounds(model, options.containerId, metamodel, defaultSizeOf);
+		const candidates = ringCandidates(nearPoint ?? {
+			x: bounds.x + 10,
+			y: bounds.y + 10
+		}, SUGGEST_MAX_RING).filter((point) => point.x >= bounds.x + 10 && point.y >= bounds.y + 10 && point.x + size.width <= bounds.x + bounds.width - 10 && point.y + size.height <= bounds.y + bounds.height - 10);
+		if (candidates.length > 0) {
+			const sentinel = {
+				x: NaN,
+				y: NaN
+			};
+			const found = firstFreeCandidate(candidates, size, obstacles, sentinel);
+			if (found !== sentinel) return found;
+		}
+		const pastLastChild = {
+			x: bounds.x + bounds.width + 10,
+			y: bounds.y + 10
+		};
+		return firstFreeCandidate(ringCandidates(pastLastChild, SUGGEST_MAX_RING), size, obstacles, guaranteedFreePoint(obstacles, pastLastChild.y));
+	}
+	const start = nearPoint ?? (obstacles.length > 0 ? {
+		x: Math.max(...obstacles.map((box) => box.x + box.width)) + 20,
+		y: 0
+	} : {
+		x: 0,
+		y: 0
+	});
+	return firstFreeCandidate(ringCandidates(start, SUGGEST_MAX_RING), size, obstacles, guaranteedFreePoint(obstacles, start.y));
+}
 //#endregion
 //#region src/constraints.ts
 const OK = { ok: true };
-function fail$1(code, reason) {
+function fail$1(code, reason, end) {
 	return {
 		ok: false,
 		code,
-		reason
+		reason,
+		end
 	};
 }
 /**
@@ -799,8 +989,8 @@ function canLink(model, source, target, kind, options = {}) {
 	const metamodel = options.metamodel ?? metamodelOf(model);
 	const s = resolve(any, source);
 	const t = resolve(any, target) ?? any.links.get(refId(target));
-	if (!s) return fail$1("unknown-element", `unknown source element "${refId(source)}"`);
-	if (!t) return fail$1("unknown-element", `unknown target element "${refId(target)}"`);
+	if (!s) return fail$1("unknown-element", `unknown source element "${refId(source)}"`, "source");
+	if (!t) return fail$1("unknown-element", `unknown target element "${refId(target)}"`, "target");
 	let definition = metamodel.links.get(kind);
 	if (!definition) return fail$1("unknown-link-kind", `unknown link kind "${String(kind)}"`);
 	if (definition.parts && !isLinkRef(t) && metamodel.elements.get(t.kind)?.of === definition.kind) definition = metamodel.links.get(definition.parts.leg) ?? definition;
@@ -851,7 +1041,7 @@ function hubCheck(graph, definition, source, target) {
 }
 /** The built-in (iStar 2.0) rules only know element targets. */
 function elementTargetOnly(definition) {
-	return fail$1("invalid-target", `the target of ${/^[aeiou]/i.test(definition.label) ? "an" : "a"} ${definition.label} link must be an element, not a link`);
+	return fail$1("invalid-target", `the target of ${/^[aeiou]/i.test(definition.label) ? "an" : "a"} ${definition.label} link must be an element, not a link`, "target");
 }
 function refId(ref) {
 	return typeof ref === "string" ? ref : ref.id;
@@ -927,16 +1117,16 @@ const is = (graph, element, ...shortNames) => {
 };
 const isDependum = (element) => element.isDependum === true;
 const isALink = (graph, source, target) => {
-	if (!is(graph, source, "Actor", "Role")) return fail$1("invalid-source", "the source of Is-A links must be a Role or a general Actor (iStar 2.0 Guide, Page 6).");
+	if (!is(graph, source, "Actor", "Role")) return fail$1("invalid-source", "the source of Is-A links must be a Role or a general Actor (iStar 2.0 Guide, Page 6).", "source");
 	if (source.kind !== target.kind) return fail$1("actor-types-differ", "the source and target of Is-A links must be of the same type - Actor and Actor, or Role and Role (iStar 2.0 Guide, Page 6).");
-	if (!is(graph, target, "Actor", "Role")) return fail$1("invalid-target", "the target of Is-A links must be a Role or a general Actor (iStar 2.0 Guide, Page 6).");
+	if (!is(graph, target, "Actor", "Role")) return fail$1("invalid-target", "the target of Is-A links must be a Role or a general Actor (iStar 2.0 Guide, Page 6).", "target");
 	if (source.id === target.id) return fail$1("self-link", "you cannot make Is-A links from an actor onto itself.");
 	if (graph.isThereLinkBetween(source, target)) return fail$1("duplicate-link", "there can only be one Actor link between the same two actors (iStar 2.0 Guide, Page 14).");
 	return OK;
 };
 const participatesInLink = (graph, source, target) => {
-	if (!graph.isActor(source)) return fail$1("invalid-source", "the source of a Participates-In link must be some kind of actor (iStar 2.0 Guide, Page 6)");
-	if (!graph.isActor(target)) return fail$1("invalid-target", "the target of a Participates-In link must be some kind of actor (iStar 2.0 Guide, Page 6)");
+	if (!graph.isActor(source)) return fail$1("invalid-source", "the source of a Participates-In link must be some kind of actor (iStar 2.0 Guide, Page 6)", "source");
+	if (!graph.isActor(target)) return fail$1("invalid-target", "the target of a Participates-In link must be some kind of actor (iStar 2.0 Guide, Page 6)", "target");
 	if (source.id === target.id) return fail$1("self-link", "you cannot make a Participates-In link from an actor onto itself.");
 	if (graph.isThereLinkBetween(source, target)) return fail$1("duplicate-link", "there can only be one Actor link between the same two actors (iStar 2.0 Guide, Page 14).");
 	return OK;
@@ -947,30 +1137,30 @@ function owningActorId(graph, element) {
 }
 const dependencyLink = (graph, source, target) => {
 	if (source.id === target.id) return fail$1("self-link", "a Dependency link cannot link an element onto itself");
-	if (isDependum(source)) return fail$1("dependum-endpoint", "a Dependency link cannot start from a dependum");
-	if (isDependum(target)) return fail$1("dependum-endpoint", "a Dependency link cannot end in a dependum");
+	if (isDependum(source)) return fail$1("dependum-endpoint", "a Dependency link cannot start from a dependum", "source");
+	if (isDependum(target)) return fail$1("dependum-endpoint", "a Dependency link cannot end in a dependum", "target");
 	if (owningActorId(graph, source) === owningActorId(graph, target)) return fail$1("same-actor", "a Dependency link must involve two different actors (iStar 2.0 Guide, Page 14)");
-	if (graph.isTargetOfType(source, "istar.OrRefinementLink") || graph.isTargetOfType(source, "istar.AndRefinementLink")) return fail$1("refined-depender", "a refined element cannot be the Depender Element in a Dependency link (iStar 2.0 Guide, Page 14). Instead, you can try to add the Dependency originating from a child.");
-	if (graph.isTargetOfType(source, "istar.ContributionLink")) return fail$1("contributed-depender", "a contributed element cannot be the Depender Element in a Dependency link (iStar 2.0 Guide, Page 14). Instead, you can try to add the Dependency originating from a child.");
+	if (graph.isTargetOfType(source, "istar.OrRefinementLink") || graph.isTargetOfType(source, "istar.AndRefinementLink")) return fail$1("refined-depender", "a refined element cannot be the Depender Element in a Dependency link (iStar 2.0 Guide, Page 14). Instead, you can try to add the Dependency originating from a child.", "source");
+	if (graph.isTargetOfType(source, "istar.ContributionLink")) return fail$1("contributed-depender", "a contributed element cannot be the Depender Element in a Dependency link (iStar 2.0 Guide, Page 14). Instead, you can try to add the Dependency originating from a child.", "source");
 	return OK;
 };
 function refinementLink(label) {
 	const other = label === "AND" ? "istar.OrRefinementLink" : "istar.AndRefinementLink";
 	return (graph, source, target) => {
-		if (!is(graph, source, "Task", "Goal")) return fail$1("invalid-source", `the source of an ${label}-refinement link must be a Goal or a Task (iStar 2.0 Guide, Table 1)`);
-		if (!is(graph, target, "Task", "Goal")) return fail$1("invalid-target", `the target of an ${label}-refinement link must be a Goal or a Task (iStar 2.0 Guide, Table 1)`);
+		if (!is(graph, source, "Task", "Goal")) return fail$1("invalid-source", `the source of an ${label}-refinement link must be a Goal or a Task (iStar 2.0 Guide, Table 1)`, "source");
+		if (!is(graph, target, "Task", "Goal")) return fail$1("invalid-target", `the target of an ${label}-refinement link must be a Goal or a Task (iStar 2.0 Guide, Table 1)`, "target");
 		if (source.id === target.id) return fail$1("self-link", `you cannot make an ${label}-refinement link from an element onto itself`);
 		if (isDependum(source) || isDependum(target)) return fail$1("dependum-endpoint", `you cannot make an ${label}-refinement link with a dependum (iStar 2.0 Guide, Page 14)`);
 		if (source.parent !== target.parent) return fail$1("different-actors", `the source and target of an ${label}-refinement link must pertain to the same actor (iStar 2.0 Guide, Page 14)`);
 		if (graph.isThereLinkBetween(source, target)) return fail$1("duplicate-link", "there can only be one refinement link between the same two elements");
-		if (graph.isSourceOfType(target, "istar.DependencyLink")) return fail$1("depender-target", "you cannot refine a Depender Element; that is, an element that is the source of a Dependency (iStar 2.0 Guide, Page 14). Instead, you can try to move the dependency to the sub-element.");
-		if (graph.isTargetOfType(target, other)) return fail$1("mixed-refinement", label === "AND" ? "you cannot mix AND-refinements with OR-refinements targeting the same element (iStar 2.0 Guide, Page 10)." : "you cannot mix OR-refinements with AND-refinements targeting the same element (iStar 2.0 Guide, Page 10).");
+		if (graph.isSourceOfType(target, "istar.DependencyLink")) return fail$1("depender-target", "you cannot refine a Depender Element; that is, an element that is the source of a Dependency (iStar 2.0 Guide, Page 14). Instead, you can try to move the dependency to the sub-element.", "target");
+		if (graph.isTargetOfType(target, other)) return fail$1("mixed-refinement", label === "AND" ? "you cannot mix AND-refinements with OR-refinements targeting the same element (iStar 2.0 Guide, Page 10)." : "you cannot mix OR-refinements with AND-refinements targeting the same element (iStar 2.0 Guide, Page 10).", "target");
 		return OK;
 	};
 }
 const neededByLink = (graph, source, target) => {
-	if (!is(graph, source, "Resource")) return fail$1("invalid-source", "the source of a Needed-By link must be a Resource (iStar 2.0 Guide, Table 1)");
-	if (!is(graph, target, "Task")) return fail$1("invalid-target", "the target of a Needed-By link must be a Task (iStar 2.0 Guide, Table 1)");
+	if (!is(graph, source, "Resource")) return fail$1("invalid-source", "the source of a Needed-By link must be a Resource (iStar 2.0 Guide, Table 1)", "source");
+	if (!is(graph, target, "Task")) return fail$1("invalid-target", "the target of a Needed-By link must be a Task (iStar 2.0 Guide, Table 1)", "target");
 	if (source.id === target.id) return fail$1("self-link", "you cannot make a Needed-By link from an element onto itself");
 	if (isDependum(source) || isDependum(target)) return fail$1("dependum-endpoint", "you cannot make a Needed-By link with a dependum (iStar 2.0 Guide, Page 14)");
 	if (source.parent !== target.parent) return fail$1("different-actors", "the source and target of a Needed-By link must pertain to the same actor (iStar 2.0 Guide, Page 14)");
@@ -978,19 +1168,19 @@ const neededByLink = (graph, source, target) => {
 	return OK;
 };
 const contributionLink = (graph, source, target) => {
-	if (!is(graph, source, "Goal", "Quality", "Task", "Resource")) return fail$1("invalid-source", "the source of a Contribution link must be a Goal, a Quality, a Task or a Resource (iStar 2.0 Guide, Table 1)");
-	if (!is(graph, target, "Quality")) return fail$1("invalid-target", "the target of a Contribution link must be a Quality (iStar 2.0 Guide, Table 1)");
+	if (!is(graph, source, "Goal", "Quality", "Task", "Resource")) return fail$1("invalid-source", "the source of a Contribution link must be a Goal, a Quality, a Task or a Resource (iStar 2.0 Guide, Table 1)", "source");
+	if (!is(graph, target, "Quality")) return fail$1("invalid-target", "the target of a Contribution link must be a Quality (iStar 2.0 Guide, Table 1)", "target");
 	if (source.id === target.id) return fail$1("self-link", "you cannot make a Contribution link from an element onto itself (iStar 2.0 Guide, Page 15)");
 	if (isDependum(source) || isDependum(target)) return fail$1("dependum-endpoint", "you cannot make a Contribution link with a dependum (iStar 2.0 Guide, Page 14)");
 	if (source.parent !== target.parent) return fail$1("different-actors", "the source and target of a Contribution link must pertain to the same actor (iStar 2.0 Guide, Page 14)");
 	if (graph.isThereLinkBetween(source, target, "istar.ContributionLink")) return fail$1("duplicate-link", "there can only be one Contribution link between the same two elements");
 	if (graph.isThereLinkBetween(source, target, "istar.QualificationLink")) return fail$1("contribution-and-qualification", "you cannot have Contribution and Qualification links between the same two elements (iStar 2.0 Guide, Page 15)");
-	if (graph.isSourceOfType(target, "istar.DependencyLink")) return fail$1("depender-target", "you cannot contribute to a Depender Element; that is, an element that is the source of a Dependency (iStar 2.0 Guide, Page 14). Instead, you can try to move the dependency to the sub-quality.");
+	if (graph.isSourceOfType(target, "istar.DependencyLink")) return fail$1("depender-target", "you cannot contribute to a Depender Element; that is, an element that is the source of a Dependency (iStar 2.0 Guide, Page 14). Instead, you can try to move the dependency to the sub-quality.", "target");
 	return OK;
 };
 const qualificationLink = (graph, source, target) => {
-	if (!is(graph, source, "Quality")) return fail$1("invalid-source", "the source of a Qualification link must be a Quality (iStar 2.0 Guide, Table 1)");
-	if (!is(graph, target, "Goal", "Task", "Resource")) return fail$1("invalid-target", "the target of a Qualification link must be a Goal, a Task or a Resource (iStar 2.0 Guide, Table 1)");
+	if (!is(graph, source, "Quality")) return fail$1("invalid-source", "the source of a Qualification link must be a Quality (iStar 2.0 Guide, Table 1)", "source");
+	if (!is(graph, target, "Goal", "Task", "Resource")) return fail$1("invalid-target", "the target of a Qualification link must be a Goal, a Task or a Resource (iStar 2.0 Guide, Table 1)", "target");
 	if (source.id === target.id) return fail$1("self-link", "you cannot make a Qualification link from an element onto itself");
 	if (isDependum(source) || isDependum(target)) return fail$1("dependum-endpoint", "you cannot make a Qualification link with a dependum (iStar 2.0 Guide, Page 14)");
 	if (source.parent !== target.parent) return fail$1("different-actors", "the source and target of a Qualification link must pertain to the same actor (iStar 2.0 Guide, Page 14)");
@@ -1030,12 +1220,12 @@ function matchesSelector(graph, element, selector) {
 function declarativeCheck(graph, definition, rules, rulesKind, source, target) {
 	const name = definition.label;
 	const article = /^[aeiou]/i.test(name) ? "an" : "a";
-	if (!rules.sources.some((selector) => matchesSelector(graph, source, selector))) return fail$1("invalid-source", `the source of ${article} ${name} link must be ${describe(graph, rules.sources)}`);
+	if (!rules.sources.some((selector) => matchesSelector(graph, source, selector))) return fail$1("invalid-source", `the source of ${article} ${name} link must be ${describe(graph, rules.sources)}`, "source");
 	if (!rules.targets.some((selector) => matchesSelector(graph, target, selector))) {
 		const targetKind = isLinkRef(target) ? void 0 : graph.metamodel.elements.get(target.kind);
 		const hubOf = targetKind?.role === "hub" && targetKind.of !== void 0 ? graph.metamodel.links.get(targetKind.of) : void 0;
-		if (hubOf) return fail$1("hub-target", `you cannot make ${article} ${name} link towards the hub of ${/^[aeiou]/i.test(hubOf.label) ? "an" : "a"} ${hubOf.label} link`);
-		return fail$1("invalid-target", `the target of ${article} ${name} link must be ${describe(graph, rules.targets)}`);
+		if (hubOf) return fail$1("hub-target", `you cannot make ${article} ${name} link towards the hub of ${/^[aeiou]/i.test(hubOf.label) ? "an" : "a"} ${hubOf.label} link`, "target");
+		return fail$1("invalid-target", `the target of ${article} ${name} link must be ${describe(graph, rules.targets)}`, "target");
 	}
 	if (!rules.allowSelf && source.id === target.id) return fail$1("self-link", `you cannot make ${article} ${name} link from an element onto itself`);
 	if (definition.category === "node" && !isLinkRef(target)) {
@@ -1790,6 +1980,20 @@ function withFileMetamodel(model, block) {
 //#region src/operations.ts
 var ModelOperationError = class extends Error {
 	name = "ModelOperationError";
+	/** The element or link the error is about, when the operation named one. */
+	elementId;
+	constructor(message, elementId) {
+		super(message);
+		this.elementId = elementId;
+	}
+	/** As a `GoalDiagnostic`, anchored on `elementId` (empty string if the error names none). */
+	toDiagnostic() {
+		return {
+			elementId: this.elementId ?? "",
+			severity: "error",
+			message: this.message
+		};
+	}
 };
 const defaultIdGenerator = () => {
 	const c = globalThis.crypto;
@@ -1819,12 +2023,12 @@ function derive(from, changes) {
 }
 function requireElement(model, id) {
 	const element = model.elements.get(id);
-	if (!element) throw new ModelOperationError(`unknown element "${id}"`);
+	if (!element) throw new ModelOperationError(`unknown element "${id}"`, id);
 	return element;
 }
 function requireLink(model, id) {
 	const link = model.links.get(id);
-	if (!link) throw new ModelOperationError(`unknown link "${id}"`);
+	if (!link) throw new ModelOperationError(`unknown link "${id}"`, id);
 	return link;
 }
 function withoutUndefined(value) {
@@ -1838,10 +2042,10 @@ function addElement(model, input, ctx = {}) {
 	const definition = metamodel.elements.get(input.kind);
 	if (!definition) throw new ModelOperationError(`unknown element kind "${input.kind}" in ${metamodel.name}`);
 	const id = input.id ?? (ctx.createId ?? defaultIdGenerator)();
-	if (m.elements.has(id) || m.links.has(id)) throw new ModelOperationError(`id "${id}" is already in use`);
+	if (m.elements.has(id) || m.links.has(id)) throw new ModelOperationError(`id "${id}" is already in use`, id);
 	if (input.parent !== void 0) {
 		if (definition.category === "actor") throw new ModelOperationError("actors cannot be nested");
-		if (!isActorIn$1(m, requireElement(m, input.parent).kind)) throw new ModelOperationError(`parent "${input.parent}" is not an actor`);
+		if (!isActorIn$1(m, requireElement(m, input.parent).kind)) throw new ModelOperationError(`parent "${input.parent}" is not an actor`, input.parent);
 	}
 	const element = withoutUndefined({
 		id,
@@ -1910,10 +2114,10 @@ function moveElement(model, id, x, y) {
 function nestElement(model, id, parent) {
 	const m = any(model);
 	const current = requireElement(m, id);
-	if (isActorIn$1(m, current.kind)) throw new ModelOperationError("actors cannot be nested");
-	if (current.isDependum) throw new ModelOperationError("a dependum cannot be nested");
+	if (isActorIn$1(m, current.kind)) throw new ModelOperationError("actors cannot be nested", id);
+	if (current.isDependum) throw new ModelOperationError("a dependum cannot be nested", id);
 	if ((current.parent ?? null) === parent) return model;
-	if (parent !== null && !isActorIn$1(m, requireElement(m, parent).kind)) throw new ModelOperationError(`parent "${parent}" is not an actor`);
+	if (parent !== null && !isActorIn$1(m, requireElement(m, parent).kind)) throw new ModelOperationError(`parent "${parent}" is not an actor`, parent);
 	const elements = new Map(m.elements);
 	elements.delete(id);
 	const { parent: _old, ...rest } = current;
@@ -1991,12 +2195,27 @@ function removeCascade(model, elementIds, linkIds) {
 	});
 }
 /**
+* Maps a failing `connect` result to a `GoalDiagnostic`, anchored on the end named by the
+* `LinkCheck`'s `end` field (`target` when a check doesn't single out one end, such as
+* `self-link` or `actor-types-differ`). `undefined` for a successful result.
+*/
+function connectResultToDiagnostic(result, endpoints) {
+	if (result.ok) return void 0;
+	return {
+		elementId: (result.end ?? "target") === "source" ? endpoints.source : endpoints.target,
+		severity: "error",
+		message: result.reason,
+		code: result.code
+	};
+}
+/**
 * Adds a link between two elements if the iStar constraints allow it.
 *
 * With an n-ary kind (`arity: 'n'`), a `target` that is one of the kind's hubs gets a new leg
-* from `source` (see `addLeg`). Any other target gets a new hub, centred between source and
-* target, with a leg from `source` and an end to `target`. `input.id` and `customProperties`
-* then go to the hub, and `label` and `name` to the end.
+* from `source` (see `addLeg`), taking `input.id` or `input.legId` (default a fresh id) as the
+* leg's id. Any other target gets a new hub, centred between source and target, with a leg from
+* `source` and an end to `target`. `input.id` and `customProperties` then go to the hub, `label`
+* and `name` to the end, and `legId`/`endId` (default fresh ids) to the leg and end.
 */
 function connect(model, input, options = {}) {
 	const m = any(model);
@@ -2025,7 +2244,7 @@ function connect(model, input, options = {}) {
 		if (!m.links.has(target)) requireElement(m, target);
 	}
 	const id = input.id ?? (options.createId ?? defaultIdGenerator)();
-	if (m.elements.has(id) || m.links.has(id)) throw new ModelOperationError(`id "${id}" is already in use`);
+	if (m.elements.has(id) || m.links.has(id)) throw new ModelOperationError(`id "${id}" is already in use`, id);
 	const link = withoutUndefined({
 		id,
 		kind,
@@ -2046,7 +2265,13 @@ function connectHub(m, definition, input, options) {
 	const metamodel = metaOf(m);
 	const parts = definition.parts;
 	const { source, target } = input;
-	if (m.elements.get(target)?.kind === parts.hub) return addLeg(typed(m), target, source, options);
+	if (m.elements.get(target)?.kind === parts.hub) {
+		const legId = input.id ?? input.legId;
+		return addLeg(typed(m), target, source, {
+			...options,
+			...legId === void 0 ? {} : { id: legId }
+		});
+	}
 	if (!options.force) {
 		const check = canLink(m, source, target, definition.kind);
 		if (!check.ok) return check;
@@ -2055,8 +2280,8 @@ function connectHub(m, definition, input, options) {
 	const to = requireElement(m, target);
 	const createId = options.createId ?? defaultIdGenerator;
 	const hubId = input.id ?? createId();
-	const legId = createId();
-	const endId = createId();
+	const legId = input.legId ?? createId();
+	const endId = input.endId ?? createId();
 	for (const [i, id] of [
 		hubId,
 		legId,
@@ -2065,7 +2290,7 @@ function connectHub(m, definition, input, options) {
 		hubId,
 		legId,
 		endId
-	].indexOf(id) !== i) throw new ModelOperationError(`id "${id}" is already in use`);
+	].indexOf(id) !== i) throw new ModelOperationError(`id "${id}" is already in use`, id);
 	const position = defaultHubPosition(m, from, to, metamodel.elements.get(parts.hub)?.size ?? {
 		width: 20,
 		height: 20
@@ -2116,14 +2341,14 @@ function addLeg(model, hubId, source, options = {}) {
 	const metamodel = metaOf(m);
 	const hub = requireElement(m, hubId);
 	const base = metamodel.links.get(metamodel.elements.get(hub.kind)?.of ?? "");
-	if (metamodel.elements.get(hub.kind)?.role !== "hub" || !base?.parts) throw new ModelOperationError(`"${hubId}" is not the hub of an n-ary link`);
+	if (metamodel.elements.get(hub.kind)?.role !== "hub" || !base?.parts) throw new ModelOperationError(`"${hubId}" is not the hub of an n-ary link`, hubId);
 	const kind = base.parts.leg;
 	if (!options.force) {
 		const check = canLink(m, source, hubId, kind);
 		if (!check.ok) return check;
 	} else requireElement(m, source);
 	const id = options.id ?? (options.createId ?? defaultIdGenerator)();
-	if (m.elements.has(id) || m.links.has(id)) throw new ModelOperationError(`id "${id}" is already in use`);
+	if (m.elements.has(id) || m.links.has(id)) throw new ModelOperationError(`id "${id}" is already in use`, id);
 	const leg = {
 		id,
 		kind,
@@ -2146,7 +2371,7 @@ function addLeg(model, hubId, source, options = {}) {
 function removeLeg(model, legId) {
 	const m = any(model);
 	const leg = requireLink(m, legId);
-	if (metaOf(m).links.get(leg.kind)?.role !== "leg") throw new ModelOperationError(`"${legId}" is not a leg of an n-ary link`);
+	if (metaOf(m).links.get(leg.kind)?.role !== "leg") throw new ModelOperationError(`"${legId}" is not a leg of an n-ary link`, legId);
 	return disconnect(model, legId);
 }
 /** Adds depender → dependum → dependee. */
@@ -2190,7 +2415,7 @@ function addDependency(model, input, options = {}) {
 		source: dependum.id,
 		target: dependee.id
 	};
-	for (const id of [id1, id2]) if (added.model.elements.has(id) || added.model.links.has(id) || id1 === id2) throw new ModelOperationError(`id "${id}" is already in use`);
+	for (const id of [id1, id2]) if (added.model.elements.has(id) || added.model.links.has(id) || id1 === id2) throw new ModelOperationError(`id "${id}" is already in use`, id);
 	return {
 		ok: true,
 		model: typed(derive(m, {
@@ -2972,6 +3197,101 @@ function fromNodeIdDiagnostics(diagnostics) {
 	return result;
 }
 //#endregion
-export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, DIAGRAM_LAYOUT_KEY, DSM3_FILE_KEYS, DSM3_TOOL, ELEMENT_KINDS, FILE_METAMODEL_KEY, HUB_ENTRY_KEY, ISTAR_2_0, ISTAR_2_0_DECLARATION, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, LINK_SELECTOR, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, addDependency, addElement, addLeg, boolean, canLink, childrenOf, compareSeverity, connect, createDiagnosticsStore, createEmptyModel, createModelStore, defaultHubPosition, defaultIdGenerator, defineMetamodel, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, detectFramework, detectPrefix, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementCenter, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, fromLspDiagnostic, fromLspDiagnostics, fromNodeIdDiagnostic, fromNodeIdDiagnostics, getSourceLayout, groupDiagnostics, hostMetamodelOf, hubEntryLayoutKey, hubLinkOf, hubOfLink, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isHubElement, isLinkKind, isLinkRef, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkBehavesLike, linkKindDefinition, linkTargetOf, linksOf, mergeDiagnostics, metamodelOf, moveElement, nestElement, number, parsePistar, prop, reference, removeElement, removeElements, removeLeg, setHostMetamodel, shortKindName, string, targetsLinks, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
+//#region src/palette.ts
+/**
+* The data part of each kind's palette entry: label, grouping, ordering, and the presets a
+* toolbar entry creates with (a link's `value`, a dependency's `dependum`, an element's
+* `properties`). React-free so a host can answer "what can I add here" (GLSP's
+* `RequestContextActions`) without the react package. Icons, titles and components are
+* presentation and stay in `packages/react/src/registry`, which derives its default entries
+* from `DEFAULT_PALETTE`.
+*/
+function defaultElementEntry(kind, index) {
+	const actor = isActorKind(kind);
+	return {
+		label: shortKindName(kind),
+		order: actor ? index : 30 + index,
+		section: actor ? "actors" : "elements",
+		...actor ? { group: "actors" } : {}
+	};
+}
+const CONTRIBUTION_ENTRY_LABELS = {
+	make: "Make (++)",
+	help: "Help (+)",
+	hurt: "Hurt (-)",
+	break: "Break (--)"
+};
+const LINK_ENTRIES = {
+	"istar.IsALink": [{
+		label: "Is A",
+		order: 10,
+		group: "actor-links",
+		section: "actors"
+	}],
+	"istar.ParticipatesInLink": [{
+		label: "Participates-In",
+		order: 11,
+		group: "actor-links",
+		section: "actors"
+	}],
+	"istar.DependencyLink": NODE_KINDS.map((dependum, i) => ({
+		label: `${shortKindName(dependum)} dependency`,
+		dependum,
+		order: 20 + i,
+		group: "dependencies",
+		section: "actors"
+	})),
+	"istar.AndRefinementLink": [{
+		label: "And",
+		order: 40,
+		section: "elements"
+	}],
+	"istar.OrRefinementLink": [{
+		label: "Or",
+		order: 41,
+		section: "elements"
+	}],
+	"istar.NeededByLink": [{
+		label: "Needed-By",
+		order: 42,
+		section: "elements"
+	}],
+	"istar.QualificationLink": [{
+		label: "Qualification",
+		order: 43,
+		section: "elements"
+	}],
+	"istar.ContributionLink": CONTRIBUTION_LABELS.map((value, i) => ({
+		label: CONTRIBUTION_ENTRY_LABELS[value],
+		value,
+		order: 50 + i,
+		group: "contributions",
+		section: "elements"
+	}))
+};
+/** piStar's dropdown buttons. */
+const DEFAULT_PALETTE_GROUPS = {
+	actors: { label: "Actor" },
+	"actor-links": { label: "Actor links" },
+	dependencies: { label: "Dependency" },
+	contributions: { label: "Contribution" }
+};
+function buildDefaultPalette() {
+	const elements = {};
+	ELEMENT_KINDS.forEach((kind, i) => {
+		elements[kind] = defaultElementEntry(kind, i);
+	});
+	const links = {};
+	for (const kind of LINK_KINDS) links[kind] = LINK_ENTRIES[kind];
+	return {
+		elements,
+		links,
+		groups: DEFAULT_PALETTE_GROUPS
+	};
+}
+/** The palette data of iStar 2.0, as piStar's toolbar presents it. */
+const DEFAULT_PALETTE = buildDefaultPalette();
+//#endregion
+export { ACTOR_KINDS, ACTOR_LINK_KINDS, ACTOR_PADDING, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEFAULT_PALETTE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, DIAGRAM_LAYOUT_KEY, DSM3_FILE_KEYS, DSM3_TOOL, ELEMENT_KINDS, FILE_METAMODEL_KEY, HUB_ENTRY_KEY, ISTAR_2_0, ISTAR_2_0_DECLARATION, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, LINK_SELECTOR, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, SUGGEST_MARGIN, actorBounds, addDependency, addElement, addLeg, boolean, canLink, childrenOf, compareSeverity, connect, connectResultToDiagnostic, createDiagnosticsStore, createEmptyModel, createModelStore, defaultHubPosition, defaultIdGenerator, defineMetamodel, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, detectFramework, detectPrefix, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementCenter, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, fromLspDiagnostic, fromLspDiagnostics, fromNodeIdDiagnostic, fromNodeIdDiagnostics, getSourceLayout, groupDiagnostics, hostMetamodelOf, hubEntryLayoutKey, hubLinkOf, hubOfLink, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isHubElement, isLinkKind, isLinkRef, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkBehavesLike, linkKindDefinition, linkTargetOf, linksOf, mergeDiagnostics, metamodelOf, moveElement, nestElement, number, parsePistar, prop, reference, removeElement, removeElements, removeLeg, setHostMetamodel, shortKindName, string, suggestPosition, targetsLinks, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
 
 //# sourceMappingURL=index.js.map