@istar-ts/core 0.10.0 → 0.11.0

package/dist/index.js

@@ -267,7 +267,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);
@@ -300,7 +302,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);
@@ -391,10 +394,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 = {}) {
@@ -466,7 +486,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,
@@ -487,10 +507,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. */
@@ -502,7 +522,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()) {
@@ -586,18 +606,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. */
@@ -605,56 +625,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". */
@@ -682,15 +702,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 = {
@@ -749,6 +769,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";
@@ -826,7 +966,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 {
@@ -836,6 +976,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();
@@ -936,6 +1082,7 @@ function parsePistar(input, options = {}) {
 		keys: Object.keys(json),
 		display: Object.keys(display)
 	});
+	setHostMetamodel(model, host);
 	return withMetamodel(model, metamodel);
 }
 function optional(key, value) {
@@ -1062,6 +1209,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 {
@@ -1841,6 +2026,6 @@ function validateModelProperties(model, schemas) {
 	return issues;
 }
 //#endregion
-export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, ELEMENT_KINDS, ISTAR_2_0, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, addDependency, addElement, boolean, canLink, childrenOf, connect, createEmptyModel, createModelStore, defaultIdGenerator, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementKindDefinition, enumOf, extendMetamodel, getSourceLayout, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isLinkKind, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkKindDefinition, linksOf, metamodelOf, moveElement, nestElement, number, parsePistar, prop, removeElement, removeElements, shortKindName, string, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateModel, validateModelProperties, withMetamodel };
+export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, ELEMENT_KINDS, FILE_METAMODEL_KEY, ISTAR_2_0, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, addDependency, addElement, boolean, canLink, childrenOf, connect, createEmptyModel, createModelStore, defaultIdGenerator, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, getSourceLayout, hostMetamodelOf, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isLinkKind, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkKindDefinition, linksOf, metamodelOf, moveElement, nestElement, number, parsePistar, prop, removeElement, removeElements, setHostMetamodel, shortKindName, string, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel };
 
 //# sourceMappingURL=index.js.map