@istar-ts/core 0.10.1 → 0.12.0

package/dist/index.cjs

@@ -268,7 +268,9 @@ function extendMetamodel(base, extension) {
 			} } : {},
 			...parent ? { behavesLike: parent.kind } : {},
 			pistarType: type,
-			extension: extension.name
+			extension: extension.name,
+			...declaration.shape ? { shape: declaration.shape } : {},
+			...declaration.textBox ? { textBox: declaration.textBox } : {}
 		};
 		elements.set(kind, definition);
 		elementsByType.set(type, kind);
@@ -301,7 +303,8 @@ function extendMetamodel(base, extension) {
 			...declaration.rules ? { rules: declaration.rules } : {},
 			...declaration.check ? { check: declaration.check } : {},
 			pistarType: type,
-			extension: extension.name
+			extension: extension.name,
+			...declaration.line ? { line: declaration.line } : {}
 		};
 		links.set(kind, definition);
 		linksByType.set(type, kind);
@@ -392,10 +395,27 @@ function withMetamodel(model, metamodel) {
 	else metamodels.set(model, metamodel);
 	return model;
 }
+/**
+* For models whose file declares part of their metamodel (see `withFileMetamodel`): the
+* metamodel the host supplied, without the file's kinds.
+*/
+const hostMetamodels = /* @__PURE__ */ new WeakMap();
+/** @internal Records the host part of a model's metamodel (used by serialization). */
+function setHostMetamodel(model, metamodel) {
+	if (metamodel) hostMetamodels.set(model, metamodel);
+	else hostMetamodels.delete(model);
+}
+/** @internal The host part of a model's metamodel, if the file declares the rest. */
+function hostMetamodelOf(model) {
+	return hostMetamodels.get(model);
+}
 /** Gives `to` the metamodel of `from` (used for every model an operation derives). */
 function inheritMetamodel(from, to) {
+	if (from === to) return to;
 	const metamodel = metamodels.get(from);
-	if (metamodel && from !== to) metamodels.set(to, metamodel);
+	if (metamodel) metamodels.set(to, metamodel);
+	const host = hostMetamodels.get(from);
+	if (host) hostMetamodels.set(to, host);
 	return to;
 }
 function createEmptyModel(diagram = DEFAULT_DIAGRAM, options = {}) {
@@ -467,7 +487,7 @@ function dependencyLinksOf(model, dependumId) {
 //#endregion
 //#region src/constraints.ts
 const OK = { ok: true };
-function fail(code, reason) {
+function fail$1(code, reason) {
 	return {
 		ok: false,
 		code,
@@ -488,10 +508,10 @@ function canLink(model, source, target, kind, options = {}) {
 	const metamodel = options.metamodel ?? metamodelOf(model);
 	const s = resolve(any, source);
 	const t = resolve(any, target);
-	if (!s) return fail("unknown-element", `unknown source element "${refId(source)}"`);
-	if (!t) return fail("unknown-element", `unknown target element "${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)}"`);
 	const definition = metamodel.links.get(kind);
-	if (!definition) return fail("unknown-link-kind", `unknown link kind "${String(kind)}"`);
+	if (!definition) return fail$1("unknown-link-kind", `unknown link kind "${String(kind)}"`);
 	return checkWith(new Graph(any, metamodel), definition, s, t);
 }
 /** Runs the rule a link kind resolves to, then every extra predicate along its chain. */
@@ -503,7 +523,7 @@ function checkWith(graph, definition, source, target) {
 	let result;
 	if (root.rules) result = declarativeCheck(graph, definition, root.rules, root.kind, source, target);
 	else if (builtIn) result = builtIn(graph, source, target);
-	else result = fail("unknown-link-kind", `link kind "${definition.kind}" has no rules`);
+	else result = fail$1("unknown-link-kind", `link kind "${definition.kind}" has no rules`);
 	if (!result.ok) return result;
 	const context = graph.context(definition.kind, source, target);
 	for (const step of chain.toReversed()) {
@@ -587,18 +607,18 @@ const is = (graph, element, ...shortNames) => {
 };
 const isDependum = (element) => element.isDependum === true;
 const isALink = (graph, source, target) => {
-	if (!is(graph, source, "Actor", "Role")) return fail("invalid-source", "the source of Is-A links must be a Role or a general Actor (iStar 2.0 Guide, Page 6).");
-	if (source.kind !== target.kind) return fail("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("invalid-target", "the target of Is-A links must be a Role or a general Actor (iStar 2.0 Guide, Page 6).");
-	if (source.id === target.id) return fail("self-link", "you cannot make Is-A links from an actor onto itself.");
-	if (graph.isThereLinkBetween(source, target)) return fail("duplicate-link", "there can only be one Actor link between the same two actors (iStar 2.0 Guide, Page 14).");
+	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 (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 (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("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("invalid-target", "the target of a Participates-In link must be some kind of actor (iStar 2.0 Guide, Page 6)");
-	if (source.id === target.id) return fail("self-link", "you cannot make a Participates-In link from an actor onto itself.");
-	if (graph.isThereLinkBetween(source, target)) return fail("duplicate-link", "there can only be one Actor link between the same two actors (iStar 2.0 Guide, Page 14).");
+	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 (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;
 };
 /** The actor an element belongs to: itself for actors, its parent for inner elements. */
@@ -606,56 +626,56 @@ function owningActorId(graph, element) {
 	return graph.isActor(element) ? element.id : element.parent;
 }
 const dependencyLink = (graph, source, target) => {
-	if (source.id === target.id) return fail("self-link", "a Dependency link cannot link an element onto itself");
-	if (isDependum(source)) return fail("dependum-endpoint", "a Dependency link cannot start from a dependum");
-	if (isDependum(target)) return fail("dependum-endpoint", "a Dependency link cannot end in a dependum");
-	if (owningActorId(graph, source) === owningActorId(graph, target)) return fail("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("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("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 (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 (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.");
 	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("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("invalid-target", `the target of an ${label}-refinement link must be a Goal or a Task (iStar 2.0 Guide, Table 1)`);
-		if (source.id === target.id) return fail("self-link", `you cannot make an ${label}-refinement link from an element onto itself`);
-		if (isDependum(source) || isDependum(target)) return fail("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("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("duplicate-link", "there can only be one refinement link between the same two elements");
-		if (graph.isSourceOfType(target, "istar.DependencyLink")) return fail("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("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 (!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 (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).");
 		return OK;
 	};
 }
 const neededByLink = (graph, source, target) => {
-	if (!is(graph, source, "Resource")) return fail("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("invalid-target", "the target of a Needed-By link must be a Task (iStar 2.0 Guide, Table 1)");
-	if (source.id === target.id) return fail("self-link", "you cannot make a Needed-By link from an element onto itself");
-	if (isDependum(source) || isDependum(target)) return fail("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("different-actors", "the source and target of a Needed-By link must pertain to the same actor (iStar 2.0 Guide, Page 14)");
-	if (graph.isThereLinkBetween(source, target)) return fail("duplicate-link", "there can only be one Needed-By link between the same two elements");
+	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 (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)");
+	if (graph.isThereLinkBetween(source, target)) return fail$1("duplicate-link", "there can only be one Needed-By link between the same two elements");
 	return OK;
 };
 const contributionLink = (graph, source, target) => {
-	if (!is(graph, source, "Goal", "Quality", "Task", "Resource")) return fail("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("invalid-target", "the target of a Contribution link must be a Quality (iStar 2.0 Guide, Table 1)");
-	if (source.id === target.id) return fail("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("dependum-endpoint", "you cannot make a Contribution link with a dependum (iStar 2.0 Guide, Page 14)");
-	if (source.parent !== target.parent) return fail("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("duplicate-link", "there can only be one Contribution link between the same two elements");
-	if (graph.isThereLinkBetween(source, target, "istar.QualificationLink")) return fail("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("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 (!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 (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.");
 	return OK;
 };
 const qualificationLink = (graph, source, target) => {
-	if (!is(graph, source, "Quality")) return fail("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("invalid-target", "the target of a Qualification link must be a Goal, a Task or a Resource (iStar 2.0 Guide, Table 1)");
-	if (source.id === target.id) return fail("self-link", "you cannot make a Qualification link from an element onto itself");
-	if (isDependum(source) || isDependum(target)) return fail("dependum-endpoint", "you cannot make a Qualification link with a dependum (iStar 2.0 Guide, Page 14)");
-	if (source.parent !== target.parent) return fail("different-actors", "the source and target of a Qualification link must pertain to the same actor (iStar 2.0 Guide, Page 14)");
-	if (graph.isThereLinkBetween(source, target, "istar.QualificationLink")) return fail("duplicate-link", "there can only be one Qualification link between the same two elements");
-	if (graph.isThereLinkBetween(source, target, "istar.ContributionLink")) return fail("contribution-and-qualification", "you cannot have Qualification and Contribution links between the same two elements (iStar 2.0 Guide, Page 15)");
+	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 (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)");
+	if (graph.isThereLinkBetween(source, target, "istar.QualificationLink")) return fail$1("duplicate-link", "there can only be one Qualification link between the same two elements");
+	if (graph.isThereLinkBetween(source, target, "istar.ContributionLink")) return fail$1("contribution-and-qualification", "you cannot have Qualification and Contribution links between the same two elements (iStar 2.0 Guide, Page 15)");
 	return OK;
 };
 /** The words used for a list of kind selectors in messages: "a Goal or a Task". */
@@ -683,15 +703,15 @@ 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("invalid-source", `the source of ${article} ${name} link must be ${describe(graph, rules.sources)}`);
-	if (!rules.targets.some((selector) => matchesSelector(graph, target, selector))) return fail("invalid-target", `the target of ${article} ${name} link must be ${describe(graph, rules.targets)}`);
-	if (!rules.allowSelf && source.id === target.id) return fail("self-link", `you cannot make ${article} ${name} link from an element onto itself`);
+	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.targets.some((selector) => matchesSelector(graph, target, selector))) return fail$1("invalid-target", `the target of ${article} ${name} link must be ${describe(graph, rules.targets)}`);
+	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") {
-		if (!rules.allowDependum && (isDependum(source) || isDependum(target))) return fail("dependum-endpoint", `you cannot make ${article} ${name} link with a dependum`);
-		if (rules.sameActor !== false && source.parent !== target.parent) return fail("different-actors", `the source and target of ${article} ${name} link must pertain to the same actor (iStar 2.0 Guide, Page 14)`);
+		if (!rules.allowDependum && (isDependum(source) || isDependum(target))) return fail$1("dependum-endpoint", `you cannot make ${article} ${name} link with a dependum`);
+		if (rules.sameActor !== false && source.parent !== target.parent) return fail$1("different-actors", `the source and target of ${article} ${name} link must pertain to the same actor (iStar 2.0 Guide, Page 14)`);
 	}
 	const unique = rules.unique ?? "kind";
-	if (unique === "any" && graph.isThereLinkBetween(source, target) || unique === "kind" && graph.isThereLinkOfKindBetween(source, target, definition.kind) || unique === "kind" && rulesKind !== definition.kind && graph.isThereLinkOfKindBetween(source, target, rulesKind)) return fail("duplicate-link", `there can only be one ${name} link between the same two elements`);
+	if (unique === "any" && graph.isThereLinkBetween(source, target) || unique === "kind" && graph.isThereLinkOfKindBetween(source, target, definition.kind) || unique === "kind" && rulesKind !== definition.kind && graph.isThereLinkOfKindBetween(source, target, rulesKind)) return fail$1("duplicate-link", `there can only be one ${name} link between the same two elements`);
 	return OK;
 }
 const CHECKS = {
@@ -750,6 +770,126 @@ function validateModel(model, options) {
 	return issues;
 }
 //#endregion
+//#region src/file-metamodel.ts
+/** The top-level key of the block in piStar JSON. */
+const FILE_METAMODEL_KEY = "metamodel";
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(path, message) {
+	throw new MetamodelError(`${path} ${message}`);
+}
+function optionalString(entry, key, path) {
+	if (entry[key] !== void 0 && typeof entry[key] !== "string") fail(`${path}.${key}`, "must be a string");
+}
+function optionalBoolean(entry, key, path) {
+	if (entry[key] !== void 0 && typeof entry[key] !== "boolean") fail(`${path}.${key}`, "must be true or false");
+}
+function checkSize(value, path) {
+	if (value === void 0) return;
+	if (!isObject(value)) fail(path, "must be an object { width, height }");
+	for (const key of ["width", "height"]) {
+		const n = value[key];
+		if (typeof n !== "number" || !Number.isFinite(n) || n <= 0) fail(`${path}.${key}`, "must be a positive number");
+	}
+}
+function checkShape(value, path) {
+	if (value === void 0) return;
+	if (!isObject(value)) fail(path, "must be an object { path, viewBox? }");
+	if (typeof value.path !== "string" || value.path.trim() === "") fail(`${path}.path`, "must be SVG path data");
+	optionalString(value, "viewBox", path);
+}
+function checkTextBox(value, path) {
+	if (value === void 0) return;
+	if (!isObject(value)) fail(path, "must be an object { top, right, bottom, left }");
+	for (const key of [
+		"top",
+		"right",
+		"bottom",
+		"left"
+	]) {
+		const n = value[key];
+		if (typeof n !== "number" || n < 0 || n >= 1) fail(`${path}.${key}`, "must be a fraction from 0 (inclusive) to 1 (exclusive)");
+	}
+}
+function checkLine(value, path) {
+	if (value === void 0) return;
+	if (!isObject(value)) fail(path, "must be an object { dash?, marker?, markerFilled? }");
+	optionalString(value, "dash", path);
+	if (value.marker !== void 0 && value.marker !== false && typeof value.marker !== "string") fail(`${path}.marker`, "must be SVG path data or false");
+	optionalBoolean(value, "markerFilled", path);
+}
+function checkStringList(value, path) {
+	if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string")) fail(path, "must be a non-empty list of kind names or categories");
+}
+function checkRules(value, path) {
+	if (!isObject(value)) fail(path, "must be an object { sources, targets, … }");
+	checkStringList(value.sources, `${path}.sources`);
+	checkStringList(value.targets, `${path}.targets`);
+	for (const key of [
+		"sameActor",
+		"allowDependum",
+		"allowSelf"
+	]) optionalBoolean(value, key, path);
+	if (value.unique !== void 0 && ![
+		"kind",
+		"any",
+		false
+	].includes(value.unique)) fail(`${path}.unique`, "must be \"kind\", \"any\" or false");
+}
+/**
+* Checks that `value` is a well-formed `"metamodel"` block and returns it typed. Throws
+* `MetamodelError` naming the offending path (`metamodel.elements[1].kind must be a string`).
+* Whether its kinds fit a given metamodel (namespacing, collisions, `behavesLike` targets) is
+* checked when it is applied, by `extendMetamodel`.
+*/
+function validateFileMetamodel(value, path = FILE_METAMODEL_KEY) {
+	if (!isObject(value)) fail(path, "must be an object { name, elements?, links? }");
+	if (typeof value.name !== "string" || value.name === "") fail(`${path}.name`, "must be a non-empty string");
+	for (const [listKey, kind] of [["elements", "element"], ["links", "link"]]) {
+		const list = value[listKey];
+		if (list === void 0) continue;
+		if (!Array.isArray(list)) fail(`${path}.${listKey}`, "must be a list");
+		list.forEach((entry, i) => {
+			const at = `${path}.${listKey}[${i}]`;
+			if (!isObject(entry)) fail(at, `must be an object describing a ${kind} kind`);
+			if (typeof entry.kind !== "string" || entry.kind === "") fail(`${at}.kind`, "must be a string");
+			optionalString(entry, "label", at);
+			optionalString(entry, "behavesLike", at);
+			optionalString(entry, "pistarType", at);
+			if (kind === "element") {
+				if (entry.category !== void 0 && entry.category !== "node" && entry.category !== "actor") fail(`${at}.category`, "must be \"node\" or \"actor\"");
+				checkSize(entry.size, `${at}.size`);
+				if (entry.info !== void 0) {
+					if (!isObject(entry.info)) fail(`${at}.info`, "must be an object");
+					for (const key of [
+						"canBeInnerElement",
+						"canBeDependum",
+						"canBeOnPaper"
+					]) optionalBoolean(entry.info, key, `${at}.info`);
+				}
+				checkShape(entry.shape, `${at}.shape`);
+				checkTextBox(entry.textBox, `${at}.textBox`);
+			} else {
+				if (entry.category !== void 0 && ![
+					"node",
+					"actor",
+					"dependency"
+				].includes(entry.category)) fail(`${at}.category`, "must be \"node\", \"actor\" or \"dependency\"");
+				if (entry.rules !== void 0) checkRules(entry.rules, `${at}.rules`);
+				if ("check" in entry) fail(`${at}.check`, "cannot be stored in a file (it is code)");
+				if (entry.info !== void 0 && !isObject(entry.info)) fail(`${at}.info`, "must be an object");
+				checkLine(entry.line, `${at}.line`);
+			}
+		});
+	}
+	return value;
+}
+/** The block as an extension `extendMetamodel` applies (it ignores the extra keys). */
+function fileMetamodelExtension(block) {
+	return block;
+}
+//#endregion
 //#region src/serialization.ts
 var PistarParseError = class extends Error {
 	name = "PistarParseError";
@@ -827,7 +967,7 @@ function asArray(value, where) {
 	return value;
 }
 function parsePistar(input, options = {}) {
-	const metamodel = options.metamodel ?? ISTAR_2_0;
+	let metamodel = options.metamodel ?? ISTAR_2_0;
 	const categoryOf = (kind) => metamodel.elements.get(kind)?.category;
 	let json;
 	if (typeof input === "string") try {
@@ -837,6 +977,12 @@ function parsePistar(input, options = {}) {
 	}
 	else json = structuredClone(input);
 	if (!isRecord(json)) throw new PistarParseError("a piStar model must be a JSON object");
+	let host;
+	if (options.fileMetamodel && json["metamodel"] !== void 0) {
+		const block = validateFileMetamodel(json[FILE_METAMODEL_KEY]);
+		host = metamodel;
+		metamodel = extendMetamodel(metamodel, fileMetamodelExtension(block));
+	}
 	const display = isRecord(json.display) ? json.display : {};
 	const usedDisplay = /* @__PURE__ */ new Set();
 	const elements = /* @__PURE__ */ new Map();
@@ -937,6 +1083,7 @@ function parsePistar(input, options = {}) {
 		keys: Object.keys(json),
 		display: Object.keys(display)
 	});
+	setHostMetamodel(model, host);
 	return withMetamodel(model, metamodel);
 }
 function optional(key, value) {
@@ -1063,6 +1210,44 @@ function toPistarObject(input, options = {}) {
 function toPistar(model, options) {
 	return JSON.stringify(toPistarObject(model, options), null, 2);
 }
+/**
+* The constructs the model's file declares in its `"metamodel"` block, when they were applied
+* (read with `fileMetamodel: true`, or set with `withFileMetamodel`); `undefined` otherwise.
+* Kinds the host supplied are never part of it.
+*/
+function fileMetamodelOf(model) {
+	if (!hostMetamodelOf(model)) return void 0;
+	return model.extra?.[FILE_METAMODEL_KEY];
+}
+/**
+* A copy of `model` whose file declares `block` (`null` removes the block): its metamodel is the
+* host's extended by `block`, and `toPistar` writes the block. This is how a tool's "Add new"
+* construct joins a model. Throws `MetamodelError` if the block is malformed, collides with the
+* host's kinds, or leaves out a kind the model still uses.
+*/
+function withFileMetamodel(model, block) {
+	const any = model;
+	const host = hostMetamodelOf(any) ?? metamodelOf(any);
+	let next = host;
+	if (block) {
+		validateFileMetamodel(block);
+		next = extendMetamodel(host, fileMetamodelExtension(block));
+	}
+	for (const element of any.elements.values()) if (!next.elements.has(element.kind)) throw new MetamodelError(`element "${element.id}" uses kind "${element.kind}", which the new metamodel lacks`);
+	for (const link of any.links.values()) if (!next.links.has(link.kind)) throw new MetamodelError(`link "${link.id}" uses kind "${link.kind}", which the new metamodel lacks`);
+	const { [FILE_METAMODEL_KEY]: _previous, ...others } = any.extra ?? {};
+	const extra = block ? {
+		...any.extra,
+		[FILE_METAMODEL_KEY]: structuredClone(block)
+	} : others;
+	const { extra: _extra, ...rest } = any;
+	const result = inheritSourceLayout(any, {
+		...rest,
+		...Object.keys(extra).length > 0 ? { extra } : {}
+	});
+	setHostMetamodel(result, block ? host : void 0);
+	return withMetamodel(result, next);
+}
 //#endregion
 //#region src/operations.ts
 var ModelOperationError = class extends Error {
@@ -1842,13 +2027,185 @@ function validateModelProperties(model, schemas) {
 	return issues;
 }
 //#endregion
+//#region src/diagnostics.ts
+/** Most severe first. */
+const DIAGNOSTIC_SEVERITIES = [
+	"error",
+	"warning",
+	"info",
+	"hint"
+];
+const RANK = {
+	error: 0,
+	warning: 1,
+	info: 2,
+	hint: 3
+};
+/** Negative when `a` is more severe than `b`. */
+function compareSeverity(a, b) {
+	return RANK[a] - RANK[b];
+}
+/** The most severe severity in a list (what a badge shows), or `undefined` if it is empty. */
+function worstDiagnosticSeverity(diagnostics) {
+	let worst;
+	for (const d of diagnostics ?? []) {
+		if (worst === void 0 || RANK[d.severity] < RANK[worst]) worst = d.severity;
+		if (worst === "error") break;
+	}
+	return worst;
+}
+function identity(d) {
+	return `${d.elementId}\u0000${d.key ?? ""}\u0000${d.message}`;
+}
+/**
+* The union of several lists, in order, without duplicates: diagnostics with the same
+* `(elementId, key, message)` count once, keeping the first one's position and the most severe
+* severity among them.
+*/
+function mergeDiagnostics(lists) {
+	const result = [];
+	const index = /* @__PURE__ */ new Map();
+	for (const list of lists) for (const d of list ?? []) {
+		const id = identity(d);
+		const at = index.get(id);
+		if (at === void 0) {
+			index.set(id, result.length);
+			result.push(d);
+		} else if (RANK[d.severity] < RANK[result[at].severity]) result[at] = {
+			...result[at],
+			severity: d.severity
+		};
+	}
+	return result;
+}
+/** Diagnostics by element (or link) id, each list in the input order. */
+function groupDiagnostics(diagnostics) {
+	const map = /* @__PURE__ */ new Map();
+	for (const d of diagnostics ?? []) {
+		const list = map.get(d.elementId);
+		if (list) list.push(d);
+		else map.set(d.elementId, [d]);
+	}
+	return map;
+}
+const NONE = [];
+function createDiagnosticsStore() {
+	const bySource = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	let merged = NONE;
+	const changed = () => {
+		merged = bySource.size === 0 ? NONE : mergeDiagnostics(bySource.values());
+		for (const listener of listeners) listener();
+	};
+	return {
+		publish(source, diagnostics) {
+			if (diagnostics.length === 0) {
+				if (bySource.delete(source)) changed();
+				return;
+			}
+			bySource.set(source, diagnostics.map((d) => d.source === void 0 ? {
+				...d,
+				source
+			} : d));
+			changed();
+		},
+		clear(source) {
+			if (source === void 0) {
+				if (bySource.size === 0) return;
+				bySource.clear();
+			} else if (!bySource.delete(source)) return;
+			changed();
+		},
+		sources: () => [...bySource.keys()],
+		get: (source) => bySource.get(source) ?? NONE,
+		getAll: () => merged,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+const LSP_SEVERITIES = [
+	"error",
+	"warning",
+	"info",
+	"hint"
+];
+function anchorOf(data) {
+	if (typeof data !== "object" || data === null) return {};
+	const record = data;
+	const elementId = typeof record.elementId === "string" ? record.elementId : typeof record.nodeId === "string" ? record.nodeId : void 0;
+	return {
+		...elementId ? { elementId } : {},
+		...typeof record.key === "string" ? { key: record.key } : {}
+	};
+}
+function convertLsp(d, options) {
+	const anchor = anchorOf(d.data);
+	const elementId = anchor.elementId ?? options.elementIdFor?.(d);
+	if (!elementId) return void 0;
+	const base = options.severityNumbering === "vscode" ? 0 : 1;
+	const severity = d.severity === void 0 ? "error" : LSP_SEVERITIES[d.severity - base] ?? "error";
+	const code = typeof d.code === "object" ? d.code.value : d.code;
+	return {
+		elementId,
+		...anchor.key !== void 0 ? { key: anchor.key } : {},
+		severity,
+		message: typeof d.message === "string" ? d.message : d.message.value,
+		...d.source !== void 0 ? { source: d.source } : {},
+		...d.range ? { range: d.range } : {},
+		...code !== void 0 ? { code: String(code) } : {},
+		...d.data !== void 0 ? { data: d.data } : {}
+	};
+}
+/**
+* One LSP diagnostic anchored by `data.elementId` (or `data.nodeId`), or `undefined` when it
+* names no element. For range-anchored diagnostics use `fromLspDiagnostics` with `elementIdFor`.
+*/
+function fromLspDiagnostic(diagnostic) {
+	return convertLsp(diagnostic, {});
+}
+/** LSP diagnostics as goal diagnostics; those that can't be anchored to an element are dropped. */
+function fromLspDiagnostics(diagnostics, options = {}) {
+	const result = [];
+	for (const d of diagnostics) {
+		const converted = convertLsp(d, options);
+		if (converted) result.push(converted);
+	}
+	return result;
+}
+/** One `{ nodeId, severity, message }` diagnostic, or `undefined` without a `nodeId`. */
+function fromNodeIdDiagnostic(diagnostic) {
+	const { nodeId, severity, ...rest } = diagnostic;
+	if (!nodeId) return void 0;
+	return {
+		...rest,
+		elementId: nodeId,
+		severity: Object.hasOwn(RANK, severity) ? severity : "info"
+	};
+}
+/**
+* `{ nodeId, severity, message }` diagnostics (MutRoSe) as goal diagnostics, dropping those
+* without a node: `store.publish('mutrose', fromNodeIdDiagnostics(message.diagnostics))`.
+*/
+function fromNodeIdDiagnostics(diagnostics) {
+	const result = [];
+	for (const d of diagnostics) {
+		const converted = fromNodeIdDiagnostic(d);
+		if (converted) result.push(converted);
+	}
+	return result;
+}
+//#endregion
 exports.ACTOR_KINDS = ACTOR_KINDS;
 exports.ACTOR_LINK_KINDS = ACTOR_LINK_KINDS;
 exports.CONTRIBUTION_LABELS = CONTRIBUTION_LABELS;
 exports.DEFAULT_DIAGRAM = DEFAULT_DIAGRAM;
 exports.DEFAULT_ELEMENT_SIZE = DEFAULT_ELEMENT_SIZE;
 exports.DEPENDENCY_LINK_KINDS = DEPENDENCY_LINK_KINDS;
+exports.DIAGNOSTIC_SEVERITIES = DIAGNOSTIC_SEVERITIES;
 exports.ELEMENT_KINDS = ELEMENT_KINDS;
+exports.FILE_METAMODEL_KEY = FILE_METAMODEL_KEY;
 exports.ISTAR_2_0 = ISTAR_2_0;
 exports.ISTAR_PREFIX = ISTAR_PREFIX;
 exports.ISTAR_VERSION = ISTAR_VERSION;
@@ -1868,7 +2225,9 @@ exports.addElement = addElement;
 exports.boolean = boolean;
 exports.canLink = canLink;
 exports.childrenOf = childrenOf;
+exports.compareSeverity = compareSeverity;
 exports.connect = connect;
+exports.createDiagnosticsStore = createDiagnosticsStore;
 exports.createEmptyModel = createEmptyModel;
 exports.createModelStore = createModelStore;
 exports.defaultIdGenerator = defaultIdGenerator;
@@ -1883,7 +2242,15 @@ exports.elementBehavesLike = elementBehavesLike;
 exports.elementKindDefinition = elementKindDefinition;
 exports.enumOf = enumOf;
 exports.extendMetamodel = extendMetamodel;
+exports.fileMetamodelExtension = fileMetamodelExtension;
+exports.fileMetamodelOf = fileMetamodelOf;
+exports.fromLspDiagnostic = fromLspDiagnostic;
+exports.fromLspDiagnostics = fromLspDiagnostics;
+exports.fromNodeIdDiagnostic = fromNodeIdDiagnostic;
+exports.fromNodeIdDiagnostics = fromNodeIdDiagnostics;
 exports.getSourceLayout = getSourceLayout;
+exports.groupDiagnostics = groupDiagnostics;
+exports.hostMetamodelOf = hostMetamodelOf;
 exports.inheritMetamodel = inheritMetamodel;
 exports.inheritSourceLayout = inheritSourceLayout;
 exports.isActor = isActor;
@@ -1902,6 +2269,7 @@ exports.isNodeKindIn = isNodeKindIn;
 exports.isNodeLinkKind = isNodeLinkKind;
 exports.linkKindDefinition = linkKindDefinition;
 exports.linksOf = linksOf;
+exports.mergeDiagnostics = mergeDiagnostics;
 exports.metamodelOf = metamodelOf;
 exports.moveElement = moveElement;
 exports.nestElement = nestElement;
@@ -1910,6 +2278,7 @@ exports.parsePistar = parsePistar;
 exports.prop = prop;
 exports.removeElement = removeElement;
 exports.removeElements = removeElements;
+exports.setHostMetamodel = setHostMetamodel;
 exports.shortKindName = shortKindName;
 exports.string = string;
 exports.toPistar = toPistar;
@@ -1917,8 +2286,11 @@ exports.toPistarObject = toPistarObject;
 exports.updateDiagram = updateDiagram;
 exports.updateElement = updateElement;
 exports.updateLink = updateLink;
+exports.validateFileMetamodel = validateFileMetamodel;
 exports.validateModel = validateModel;
 exports.validateModelProperties = validateModelProperties;
+exports.withFileMetamodel = withFileMetamodel;
 exports.withMetamodel = withMetamodel;
+exports.worstDiagnosticSeverity = worstDiagnosticSeverity;
 
 //# sourceMappingURL=index.cjs.map