@istar-ts/core 0.11.0 → 0.13.0

package/dist/index.js

@@ -138,61 +138,6 @@ function shortKindName(kind) {
 }
 //#endregion
 //#region src/metamodels.ts
-function shortName(kind) {
-	const dot = kind.indexOf(".");
-	return dot === -1 ? kind : kind.slice(dot + 1);
-}
-function buildIstar() {
-	const elements = /* @__PURE__ */ new Map();
-	for (const kind of ACTOR_KINDS) elements.set(kind, {
-		kind,
-		category: "actor",
-		label: shortName(kind),
-		size: DEFAULT_ELEMENT_SIZE[kind],
-		pistarType: kind
-	});
-	for (const kind of NODE_KINDS) elements.set(kind, {
-		kind,
-		category: "node",
-		label: shortName(kind),
-		size: DEFAULT_ELEMENT_SIZE[kind],
-		info: NODE_KIND_INFO[kind],
-		pistarType: kind
-	});
-	const links = /* @__PURE__ */ new Map();
-	const labels = {
-		"istar.IsALink": "Is-A",
-		"istar.ParticipatesInLink": "Participates-In",
-		"istar.DependencyLink": "Dependency",
-		"istar.AndRefinementLink": "And-Refinement",
-		"istar.OrRefinementLink": "Or-Refinement",
-		"istar.NeededByLink": "Needed-By",
-		"istar.QualificationLink": "Qualification",
-		"istar.ContributionLink": "Contribution"
-	};
-	const add = (kinds, category) => {
-		for (const kind of kinds) links.set(kind, {
-			kind,
-			category,
-			label: labels[kind],
-			info: LINK_KIND_INFO[kind],
-			pistarType: kind
-		});
-	};
-	add(ACTOR_LINK_KINDS, "actor");
-	add(DEPENDENCY_LINK_KINDS, "dependency");
-	add(NODE_LINK_KINDS, "node");
-	return {
-		name: "istar-2.0",
-		extensions: [],
-		elements,
-		links,
-		elementsByPistarType: new Map([...elements.keys()].map((k) => [k, k])),
-		linksByPistarType: new Map([...links.keys()].map((k) => [k, k]))
-	};
-}
-/** iStar 2.0, as the piStar tool implements it. The default metamodel everywhere. */
-const ISTAR_2_0 = buildIstar();
 var MetamodelError = class extends Error {
 	name = "MetamodelError";
 };
@@ -204,117 +149,337 @@ function defineMetamodelExtension(extension) {
 	return extension;
 }
 const KIND_NAME = /^[A-Za-z_][\w-]*\.[A-Za-z_][\w-]*$/;
+const PREFIX_NAME = /^[A-Za-z_][\w-]*$/;
 const CATEGORY_SELECTORS = /* @__PURE__ */ new Set([
 	"node",
 	"actor",
 	"*"
 ]);
+/** The `targets` selector for any link (see `LinkRules`). */
+const LINK_SELECTOR = "link";
+/** piStar-ext's defaults for an extension's new nodes (tool/language/metamodel.js). */
+const EXTENSION_NODE_INFO = {
+	canBeInnerElement: true,
+	canBeDependum: true,
+	canBeOnPaper: false
+};
+/** DSM3-goals' defaults for a root's nodes (istarcore metamodelManager). */
+/** A hub sits on the paper, outside any actor, and is never a dependum. */
+const HUB_INFO = {
+	canBeInnerElement: false,
+	canBeDependum: false,
+	canBeOnPaper: true
+};
+/** A circle filling the hub's box (DSM3-goals draws a circle of radius 10 in 20×20). */
+const HUB_SHAPE = {
+	path: "M 0 10 A 10 10 0 1 0 20 10 A 10 10 0 1 0 0 10 Z",
+	viewBox: "0 0 20 20"
+};
+const ROOT_NODE_INFO = {
+	canBeInnerElement: true,
+	canBeDependum: true,
+	canBeOnPaper: true
+};
+function shortName(kind) {
+	const dot = kind.indexOf(".");
+	return dot === -1 ? kind : kind.slice(dot + 1);
+}
+function claimName(table, kind, what) {
+	const { where } = table;
+	if (typeof kind !== "string" || !KIND_NAME.test(kind)) throw new MetamodelError(`${where}: ${what} kind ${JSON.stringify(kind)} must be namespaced, e.g. "${table.namespace}.Name"`);
+	if (table.reserved !== void 0 && kind.startsWith(`${table.reserved}.`)) throw new MetamodelError(`${where}: ${what} kind "${kind}" uses the reserved "${table.reserved}." prefix; name it "${table.namespace}.${shortName(kind)}" and set pistarType: "${kind}" to read files that use it`);
+	if (table.elements.has(kind) || table.links.has(kind)) throw new MetamodelError(`${where}: kind "${kind}" already exists`);
+}
+function claimType(table, type, kind) {
+	const { where } = table;
+	if (typeof type !== "string" || type === "") throw new MetamodelError(`${where}: kind "${kind}" has an empty pistarType`);
+	if (table.elementsByType.has(type) || table.linksByType.has(type) || table.elements.has(type) || table.links.has(type)) throw new MetamodelError(`${where}: pistarType "${type}" of kind "${kind}" is already used by another kind`);
+}
+function isCompleteNodeInfo(info) {
+	return info !== void 0 && typeof info.canBeInnerElement === "boolean" && typeof info.canBeDependum === "boolean" && typeof info.canBeOnPaper === "boolean";
+}
+function addElementKind(table, declaration) {
+	const { where } = table;
+	const { kind } = declaration;
+	claimName(table, kind, "element");
+	let parent;
+	if (declaration.behavesLike !== void 0) {
+		parent = table.elements.get(declaration.behavesLike);
+		if (!parent) throw new MetamodelError(`${where}: "${kind}" behaves like unknown element kind "${declaration.behavesLike}"`);
+	}
+	const category = declaration.category ?? parent?.category;
+	if (category !== "actor" && category !== "node") throw new MetamodelError(`${where}: element kind "${kind}" needs a category ("node" or "actor") or behavesLike`);
+	if (parent && parent.category !== category) throw new MetamodelError(`${where}: "${kind}" is a ${category} but behaves like "${parent.kind}", a ${parent.category}`);
+	const type = declaration.pistarType ?? kind;
+	claimType(table, type, kind);
+	const info = isCompleteNodeInfo(declaration.info) ? declaration.info : {
+		...parent?.info ?? (table.extension === void 0 ? ROOT_NODE_INFO : EXTENSION_NODE_INFO),
+		...declaration.info
+	};
+	const definition = {
+		kind,
+		category,
+		label: declaration.label ?? shortName(kind),
+		size: declaration.size ?? parent?.size ?? (category === "actor" ? {
+			width: 200,
+			height: 120
+		} : {
+			width: 90,
+			height: 55
+		}),
+		...category === "node" ? { info } : {},
+		...parent ? { behavesLike: parent.kind } : {},
+		pistarType: type,
+		...table.extension !== void 0 ? { extension: table.extension } : {},
+		...declaration.shape ? { shape: declaration.shape } : {},
+		...declaration.textBox ? { textBox: declaration.textBox } : {}
+	};
+	table.elements.set(kind, definition);
+	table.elementsByType.set(type, kind);
+}
+function addLinkKind(table, declaration) {
+	const { where } = table;
+	const { kind } = declaration;
+	claimName(table, kind, "link");
+	const isRoot = table.extension === void 0;
+	if (declaration.behavesLike !== void 0 && declaration.rules !== void 0) throw new MetamodelError(isRoot ? `${where}: link kind "${kind}" needs at most one of behavesLike or rules` : `${where}: link kind "${kind}" needs exactly one of behavesLike or rules`);
+	if (!isRoot && declaration.behavesLike === void 0 && declaration.rules === void 0) throw new MetamodelError(`${where}: link kind "${kind}" needs exactly one of behavesLike or rules`);
+	let parent;
+	if (declaration.behavesLike !== void 0) {
+		parent = table.links.get(declaration.behavesLike);
+		if (!parent) throw new MetamodelError(`${where}: "${kind}" behaves like unknown link kind "${declaration.behavesLike}"`);
+	}
+	const category = declaration.category ?? parent?.category ?? "node";
+	if (category !== "node" && category !== "actor" && category !== "dependency") throw new MetamodelError(`${where}: link kind "${kind}" has an unknown category "${category}"`);
+	if (declaration.arity !== void 0) {
+		if (declaration.arity !== "n") throw new MetamodelError(`${where}: link kind "${kind}" has an unknown arity ${JSON.stringify(declaration.arity)}`);
+		if (!declaration.rules || category !== "node") throw new MetamodelError(`${where}: n-ary link kind "${kind}" needs rules and the "node" category`);
+	}
+	if (parent && parent.category !== category) throw new MetamodelError(`${where}: "${kind}" is a ${category} link but behaves like "${parent.kind}", a ${parent.category} link`);
+	if (category === "dependency" && !parent && (!isRoot || declaration.rules !== void 0)) throw new MetamodelError(`${where}: dependency link kind "${kind}" must behave like a dependency link (its dependum makes declarative rules ambiguous)`);
+	if (declaration.rules) for (const [side, selectors] of [["sources", declaration.rules.sources], ["targets", declaration.rules.targets]]) {
+		if (!Array.isArray(selectors) || selectors.length === 0) throw new MetamodelError(`${where}: link kind "${kind}" needs at least one of ${side}`);
+		for (const selector of selectors) if (!(CATEGORY_SELECTORS.has(selector) || table.elements.has(selector) || side === "targets" && (selector === "link" || table.links.has(selector) || selector === kind))) throw new MetamodelError(`${where}: ${side} of "${kind}" names unknown element kind "${selector}"`);
+	}
+	const type = declaration.pistarType ?? kind;
+	claimType(table, type, kind);
+	const definition = {
+		kind,
+		category,
+		label: declaration.label ?? shortName(kind),
+		info: declaration.info ?? parent?.info ?? {},
+		...parent ? { behavesLike: parent.kind } : {},
+		...declaration.rules ? { rules: declaration.rules } : {},
+		...declaration.check ? { check: declaration.check } : {},
+		pistarType: type,
+		...table.extension !== void 0 ? { extension: table.extension } : {},
+		...declaration.line ? { line: declaration.line } : {}
+	};
+	if (declaration.arity !== "n") {
+		table.links.set(kind, definition);
+		table.linksByType.set(type, kind);
+		return;
+	}
+	const parts = {
+		hub: declaration.parts?.hub ?? `${kind}Hub`,
+		leg: declaration.parts?.leg ?? `${kind}Start`,
+		end: declaration.parts?.end ?? `${kind}End`
+	};
+	table.links.set(kind, {
+		...definition,
+		arity: "n",
+		parts
+	});
+	table.linksByType.set(type, kind);
+	addHubKinds(table, table.links.get(kind), parts, declaration.hubSize);
+}
+/**
+* Adds the kinds an n-ary link kind is made of, as DSM3-goals' `setupSplitLinks` generates them:
+* the hub (an element), the legs (each source → the hub, at most one per source) and the end
+* (the hub → the target).
+*/
+function addHubKinds(table, base, parts, hubSize) {
+	const rules = base.rules;
+	const claim = (kind, type, what) => {
+		try {
+			claimName(table, kind, what);
+			claimType(table, type, kind);
+		} catch (error) {
+			if (!(error instanceof MetamodelError)) throw error;
+			throw new MetamodelError(`${error.message} (generated for n-ary link kind "${base.kind}")`);
+		}
+	};
+	const owner = table.extension !== void 0 ? { extension: table.extension } : {};
+	claim(parts.hub, `${base.pistarType}Hub`, "element");
+	table.elements.set(parts.hub, {
+		kind: parts.hub,
+		category: "node",
+		label: `${base.label} hub`,
+		size: hubSize ?? {
+			width: 20,
+			height: 20
+		},
+		info: HUB_INFO,
+		pistarType: `${base.pistarType}Hub`,
+		...owner,
+		shape: HUB_SHAPE,
+		role: "hub",
+		of: base.kind
+	});
+	table.elementsByType.set(`${base.pistarType}Hub`, parts.hub);
+	const common = {
+		category: "node",
+		...owner,
+		of: base.kind
+	};
+	claim(parts.leg, `${base.pistarType}Start`, "link");
+	table.links.set(parts.leg, {
+		...common,
+		kind: parts.leg,
+		label: `${base.label} leg`,
+		info: {},
+		rules: {
+			sources: rules.sources,
+			targets: [parts.hub],
+			sameActor: false,
+			...rules.allowDependum !== void 0 ? { allowDependum: rules.allowDependum } : {},
+			unique: "kind"
+		},
+		pistarType: `${base.pistarType}Start`,
+		role: "leg"
+	});
+	table.linksByType.set(`${base.pistarType}Start`, parts.leg);
+	claim(parts.end, `${base.pistarType}End`, "link");
+	table.links.set(parts.end, {
+		...common,
+		kind: parts.end,
+		label: `${base.label} end`,
+		info: base.info,
+		rules: {
+			sources: [parts.hub],
+			targets: rules.targets,
+			sameActor: false,
+			...rules.allowDependum !== void 0 ? { allowDependum: rules.allowDependum } : {},
+			unique: "kind"
+		},
+		pistarType: `${base.pistarType}End`,
+		...base.line ? { line: base.line } : {},
+		role: "end"
+	});
+	table.linksByType.set(`${base.pistarType}End`, parts.end);
+}
+/**
+* Builds a root metamodel: a modelling language of its own, such as iStar 2.0, KAOS or NFR.
+* Kinds are namespaced (any namespace; usually `prefix`), declared in order: `behavesLike` and
+* link rules refer to kinds declared before them. Extensions of the result may not use `prefix`.
+*
+* Throws `MetamodelError` on the same declaration errors as `extendMetamodel`.
+*/
+function defineMetamodel(declaration) {
+	const { name, prefix } = declaration;
+	if (!name || typeof name !== "string") throw new MetamodelError("a root metamodel needs a name");
+	const where = `metamodel "${name}"`;
+	if (typeof prefix !== "string" || !PREFIX_NAME.test(prefix)) throw new MetamodelError(`${where}: prefix ${JSON.stringify(prefix)} must be a name without dots, e.g. "istar"`);
+	const table = {
+		where,
+		namespace: prefix,
+		elements: /* @__PURE__ */ new Map(),
+		links: /* @__PURE__ */ new Map(),
+		elementsByType: /* @__PURE__ */ new Map(),
+		linksByType: /* @__PURE__ */ new Map()
+	};
+	for (const element of declaration.elements) addElementKind(table, element);
+	for (const link of declaration.links) addLinkKind(table, link);
+	return {
+		name,
+		framework: name,
+		prefix,
+		file: declaration.file ?? {},
+		extensions: [],
+		elements: table.elements,
+		links: table.links,
+		elementsByPistarType: table.elementsByType,
+		linksByPistarType: table.linksByType
+	};
+}
+const ISTAR_LINK_LABELS = {
+	"istar.IsALink": "Is-A",
+	"istar.ParticipatesInLink": "Participates-In",
+	"istar.DependencyLink": "Dependency",
+	"istar.AndRefinementLink": "And-Refinement",
+	"istar.OrRefinementLink": "Or-Refinement",
+	"istar.NeededByLink": "Needed-By",
+	"istar.QualificationLink": "Qualification",
+	"istar.ContributionLink": "Contribution"
+};
+function istarLinks(kinds, category) {
+	return kinds.map((kind) => ({
+		kind,
+		category,
+		label: ISTAR_LINK_LABELS[kind],
+		info: LINK_KIND_INFO[kind]
+	}));
+}
+/** iStar 2.0's declaration, built from the constants in `metamodel.ts`. */
+const ISTAR_2_0_DECLARATION = {
+	name: "istar-2.0",
+	prefix: ISTAR_PREFIX,
+	elements: [...ACTOR_KINDS.map((kind) => ({
+		kind,
+		category: "actor",
+		size: DEFAULT_ELEMENT_SIZE[kind]
+	})), ...NODE_KINDS.map((kind) => ({
+		kind,
+		category: "node",
+		size: DEFAULT_ELEMENT_SIZE[kind],
+		info: NODE_KIND_INFO[kind]
+	}))],
+	links: [
+		...istarLinks(ACTOR_LINK_KINDS, "actor"),
+		...istarLinks(DEPENDENCY_LINK_KINDS, "dependency"),
+		...istarLinks(NODE_LINK_KINDS, "node")
+	],
+	file: {
+		tool: "pistar.2.1.0",
+		istar: "2.0"
+	}
+};
+/** iStar 2.0, as the piStar tool implements it. The default metamodel everywhere. */
+const ISTAR_2_0 = defineMetamodel(ISTAR_2_0_DECLARATION);
 /**
-* Returns a new metamodel with the extension's kinds added. `base` is not modified.
+* Returns a new metamodel with the extension's kinds added. `base` is not modified. The result
+* keeps `base`'s `framework`, `prefix` and `file`.
 *
-* Throws `MetamodelError` when a kind name isn't namespaced, uses the reserved `istar.`
-* prefix, collides with an existing kind or piStar type, or refers to an unknown kind.
+* Throws `MetamodelError` when a kind name isn't namespaced, uses the root's reserved prefix
+* (`istar.` for iStar 2.0), collides with an existing kind or piStar type, or refers to an
+* unknown kind.
 */
 function extendMetamodel(base, extension) {
-	const where = `extension "${extension.name}"`;
 	if (!extension.name || typeof extension.name !== "string") throw new MetamodelError("an extension needs a name");
+	const where = `extension "${extension.name}"`;
 	if (base.extensions.includes(extension.name)) throw new MetamodelError(`${where} is already applied`);
-	const elements = new Map(base.elements);
-	const links = new Map(base.links);
-	const elementsByType = new Map(base.elementsByPistarType);
-	const linksByType = new Map(base.linksByPistarType);
-	const claimName = (kind, what) => {
-		if (typeof kind !== "string" || !KIND_NAME.test(kind)) throw new MetamodelError(`${where}: ${what} kind ${JSON.stringify(kind)} must be namespaced, e.g. "${extension.name}.Name"`);
-		if (kind.startsWith(`istar.`)) throw new MetamodelError(`${where}: ${what} kind "${kind}" uses the reserved "${ISTAR_PREFIX}." prefix; name it "${extension.name}.${shortName(kind)}" and set pistarType: "${kind}" to read files that use it`);
-		if (elements.has(kind) || links.has(kind)) throw new MetamodelError(`${where}: kind "${kind}" already exists`);
-	};
-	const claimType = (type, kind) => {
-		if (typeof type !== "string" || type === "") throw new MetamodelError(`${where}: kind "${kind}" has an empty pistarType`);
-		if (elementsByType.has(type) || linksByType.has(type) || elements.has(type) || links.has(type)) throw new MetamodelError(`${where}: pistarType "${type}" of kind "${kind}" is already used by another kind`);
+	const table = {
+		where,
+		namespace: extension.name,
+		reserved: base.prefix,
+		extension: extension.name,
+		elements: new Map(base.elements),
+		links: new Map(base.links),
+		elementsByType: new Map(base.elementsByPistarType),
+		linksByType: new Map(base.linksByPistarType)
 	};
-	for (const declaration of extension.elements ?? []) {
-		const { kind } = declaration;
-		claimName(kind, "element");
-		let parent;
-		if (declaration.behavesLike !== void 0) {
-			parent = elements.get(declaration.behavesLike);
-			if (!parent) throw new MetamodelError(`${where}: "${kind}" behaves like unknown element kind "${declaration.behavesLike}"`);
-		}
-		const category = declaration.category ?? parent?.category;
-		if (category !== "actor" && category !== "node") throw new MetamodelError(`${where}: element kind "${kind}" needs a category ("node" or "actor") or behavesLike`);
-		if (parent && parent.category !== category) throw new MetamodelError(`${where}: "${kind}" is a ${category} but behaves like "${parent.kind}", a ${parent.category}`);
-		const type = declaration.pistarType ?? kind;
-		claimType(type, kind);
-		const baseInfo = parent?.info ?? {
-			canBeInnerElement: true,
-			canBeDependum: true,
-			canBeOnPaper: false
-		};
-		const definition = {
-			kind,
-			category,
-			label: declaration.label ?? shortName(kind),
-			size: declaration.size ?? parent?.size ?? (category === "actor" ? {
-				width: 200,
-				height: 120
-			} : {
-				width: 90,
-				height: 55
-			}),
-			...category === "node" ? { info: {
-				...baseInfo,
-				...declaration.info
-			} } : {},
-			...parent ? { behavesLike: parent.kind } : {},
-			pistarType: type,
-			extension: extension.name,
-			...declaration.shape ? { shape: declaration.shape } : {},
-			...declaration.textBox ? { textBox: declaration.textBox } : {}
-		};
-		elements.set(kind, definition);
-		elementsByType.set(type, kind);
-	}
-	for (const declaration of extension.links ?? []) {
-		const { kind } = declaration;
-		claimName(kind, "link");
-		if (declaration.behavesLike === void 0 === (declaration.rules === void 0)) throw new MetamodelError(`${where}: link kind "${kind}" needs exactly one of behavesLike or rules`);
-		let parent;
-		if (declaration.behavesLike !== void 0) {
-			parent = links.get(declaration.behavesLike);
-			if (!parent) throw new MetamodelError(`${where}: "${kind}" behaves like unknown link kind "${declaration.behavesLike}"`);
-		}
-		const category = declaration.category ?? parent?.category ?? "node";
-		if (category !== "node" && category !== "actor" && category !== "dependency") throw new MetamodelError(`${where}: link kind "${kind}" has an unknown category "${category}"`);
-		if (parent && parent.category !== category) throw new MetamodelError(`${where}: "${kind}" is a ${category} link but behaves like "${parent.kind}", a ${parent.category} link`);
-		if (category === "dependency" && !parent) throw new MetamodelError(`${where}: dependency link kind "${kind}" must behave like a dependency link (its dependum makes declarative rules ambiguous)`);
-		if (declaration.rules) for (const [side, selectors] of [["sources", declaration.rules.sources], ["targets", declaration.rules.targets]]) {
-			if (!Array.isArray(selectors) || selectors.length === 0) throw new MetamodelError(`${where}: link kind "${kind}" needs at least one of ${side}`);
-			for (const selector of selectors) if (!CATEGORY_SELECTORS.has(selector) && !elements.has(selector)) throw new MetamodelError(`${where}: ${side} of "${kind}" names unknown element kind "${selector}"`);
-		}
-		const type = declaration.pistarType ?? kind;
-		claimType(type, kind);
-		const definition = {
-			kind,
-			category,
-			label: declaration.label ?? shortName(kind),
-			info: declaration.info ?? parent?.info ?? {},
-			...parent ? { behavesLike: parent.kind } : {},
-			...declaration.rules ? { rules: declaration.rules } : {},
-			...declaration.check ? { check: declaration.check } : {},
-			pistarType: type,
-			extension: extension.name,
-			...declaration.line ? { line: declaration.line } : {}
-		};
-		links.set(kind, definition);
-		linksByType.set(type, kind);
-	}
+	for (const element of extension.elements ?? []) addElementKind(table, element);
+	for (const link of extension.links ?? []) addLinkKind(table, link);
 	return {
 		name: `${base.name}+${extension.name}`,
+		framework: base.framework,
+		prefix: base.prefix,
+		file: base.file,
 		extensions: [...base.extensions, extension.name],
-		elements,
-		links,
-		elementsByPistarType: elementsByType,
-		linksByPistarType: linksByType
+		elements: table.elements,
+		links: table.links,
+		elementsByPistarType: table.elementsByType,
+		linksByPistarType: table.linksByType
 	};
 }
 function elementKindDefinition(metamodel, kind) {
@@ -358,6 +523,21 @@ function effectiveLinkKind(metamodel, kind) {
 	}
 	return current?.kind ?? kind;
 }
+/** True when link `kind` is `ancestor` or (transitively) behaves like it. */
+function linkBehavesLike(metamodel, kind, ancestor) {
+	let current = kind;
+	const seen = /* @__PURE__ */ new Set();
+	while (current !== void 0 && !seen.has(current)) {
+		if (current === ancestor) return true;
+		seen.add(current);
+		current = metamodel.links.get(current)?.behavesLike;
+	}
+	return false;
+}
+/** True when a link kind's rules let it target links (`link` or a link kind in `targets`). */
+function targetsLinks(metamodel, kind) {
+	return metamodel.links.get(effectiveLinkKind(metamodel, kind))?.rules?.targets.some((selector) => selector === "link" || metamodel.links.has(selector)) ?? false;
+}
 /** True when `kind` is `ancestor` or (transitively) behaves like it. */
 function elementBehavesLike(metamodel, kind, ancestor) {
 	let current = kind;
@@ -374,6 +554,23 @@ function elementBehavesLike(metamodel, kind, ancestor) {
 /** Tool identifier written by piStar 2.1.0, whose file format this library emulates. */
 const PISTAR_TOOL = "pistar.2.1.0";
 const ISTAR_VERSION = "2.0";
+/**
+* DSM3-goals' file conventions, shared by its languages (KAOS, NFR; see `@istar-ts/dsm3-kaos`
+* and `@istar-ts/dsm3-nfr`): the `tool` its editors write, and the order of their top-level keys
+* (`fileManager.js`). Use them as a root's `file.tool` and `file.keys`.
+*/
+const DSM3_TOOL = "dsm3-goals";
+const DSM3_FILE_KEYS = [
+	"actors",
+	"orphans",
+	"dependencies",
+	"links",
+	"display",
+	"tool",
+	"metamodelVersion",
+	"saveDate",
+	"diagram"
+];
 const DEFAULT_DIAGRAM = {
 	width: 2e3,
 	height: 1300
@@ -418,12 +615,14 @@ function inheritMetamodel(from, to) {
 	return to;
 }
 function createEmptyModel(diagram = DEFAULT_DIAGRAM, options = {}) {
+	const { file } = options.metamodel ?? ISTAR_2_0;
 	const model = {
 		elements: /* @__PURE__ */ new Map(),
 		links: /* @__PURE__ */ new Map(),
 		diagram,
-		tool: PISTAR_TOOL,
-		istar: "2.0"
+		tool: file.tool ?? "pistar.2.1.0",
+		...file.istar !== void 0 ? { istar: file.istar } : {},
+		...file.extra !== void 0 ? { extra: { ...file.extra } } : {}
 	};
 	return options.metamodel ? withMetamodel(model, options.metamodel) : model;
 }
@@ -462,7 +661,10 @@ function childrenOf(model, actorId) {
 	for (const element of model.elements.values()) if (element.parent === actorId) result.push(element);
 	return result;
 }
-/** Links that have the element as source or target. */
+/**
+* Links that have the element as source or target. Given a link id, the links that target that
+* link (see `LinkRules`).
+*/
 function linksOf(model, elementId) {
 	const result = [];
 	for (const link of model.links.values()) if (link.source === elementId || link.target === elementId) result.push(link);
@@ -483,6 +685,63 @@ function dependencyLinksOf(model, dependumId) {
 		outbound
 	};
 }
+/** What a link points at: an element, or a link for kinds whose rules target links. */
+function linkTargetOf(model, link) {
+	return model.elements.get(link.target) ?? model.links.get(link.target);
+}
+/** True when `element` is the hub of an n-ary link. */
+function isHubElement(metamodel, element) {
+	return element !== void 0 && metamodel.elements.get(element.kind)?.role === "hub";
+}
+/** The n-ary link whose hub is `hubId`; `undefined` when it isn't a hub. */
+function hubLinkOf(model, hubId) {
+	const metamodel = metamodelOf(model);
+	const hub = model.elements.get(hubId);
+	if (!hub || !isHubElement(metamodel, hub)) return void 0;
+	const legs = [];
+	let end;
+	for (const link of model.links.values()) {
+		const role = metamodel.links.get(link.kind)?.role;
+		if (role === "leg" && link.target === hubId) legs.push(link);
+		else if (role === "end" && link.source === hubId) end ??= link;
+	}
+	return {
+		hub,
+		legs,
+		...end ? { end } : {}
+	};
+}
+/** The hub a leg or end link belongs to. */
+function hubOfLink(model, linkId) {
+	const metamodel = metamodelOf(model);
+	const link = model.links.get(linkId);
+	const role = link && metamodel.links.get(link.kind)?.role;
+	if (!link || !role) return void 0;
+	const hub = model.elements.get(role === "leg" ? link.target : link.source);
+	return isHubElement(metamodel, hub) ? hub : void 0;
+}
+/** The centre of an element's box: its display size, else its kind's default size. */
+function elementCenter(model, element) {
+	const size = metamodelOf(model).elements.get(element.kind)?.size;
+	const width = element.display?.width ?? size?.width ?? 0;
+	const height = element.display?.height ?? size?.height ?? 0;
+	return {
+		x: element.x + width / 2,
+		y: element.y + height / 2
+	};
+}
+/**
+* Where a new hub goes: centred between the source and the target, as DSM3-goals places it.
+* Returns its top-left corner for a hub of `size`.
+*/
+function defaultHubPosition(model, source, target, size) {
+	const a = elementCenter(model, source);
+	const b = elementCenter(model, target);
+	return {
+		x: (a.x + b.x) / 2 - size.width / 2,
+		y: (a.y + b.y) / 2 - size.height / 2
+	};
+}
 //#endregion
 //#region src/constraints.ts
 const OK = { ok: true };
@@ -494,6 +753,14 @@ function fail$1(code, reason) {
 	};
 }
 /**
+* True for a link, as opposed to an element: the target of a link kind whose rules target links
+* (see `LinkRules`) may be either.
+*/
+function isLinkRef(value) {
+	const candidate = value;
+	return typeof candidate.source === "string" && typeof candidate.target === "string";
+}
+/**
 * Checks whether a link of `kind` may be added from `source` to `target` in `model`.
 *
 * For dependency links, `source` is the depender and `target` the dependee (an actor or one of
@@ -501,16 +768,22 @@ function fail$1(code, reason) {
 *
 * Extended kinds (see `extendMetamodel`) are checked with the rules of the kind they behave
 * like, or with their declarative rules, then with their extra predicate.
+*
+* `target` may be a link (or a link id) for kinds whose rules target links (`LinkRules`).
+*
+* For an n-ary kind (`arity: 'n'`), a `target` that is one of its hubs is checked as a new leg
+* of that hub; any other target, as a new link from `source` to `target`.
 */
 function canLink(model, source, target, kind, options = {}) {
 	const any = model;
 	const metamodel = options.metamodel ?? metamodelOf(model);
 	const s = resolve(any, source);
-	const t = resolve(any, target);
+	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)}"`);
-	const definition = metamodel.links.get(kind);
+	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;
 	return checkWith(new Graph(any, metamodel), definition, s, t);
 }
 /** Runs the rule a link kind resolves to, then every extra predicate along its chain. */
@@ -521,9 +794,14 @@ function checkWith(graph, definition, source, target) {
 	const builtIn = CHECKS[root.kind];
 	let result;
 	if (root.rules) result = declarativeCheck(graph, definition, root.rules, root.kind, source, target);
+	else if (isLinkRef(target)) result = elementTargetOnly(definition);
 	else if (builtIn) result = builtIn(graph, source, target);
 	else result = fail$1("unknown-link-kind", `link kind "${definition.kind}" has no rules`);
 	if (!result.ok) return result;
+	if (definition.role !== void 0 && !isLinkRef(target)) {
+		const hubResult = hubCheck(graph, definition, source, target);
+		if (!hubResult.ok) return hubResult;
+	}
 	const context = graph.context(definition.kind, source, target);
 	for (const step of chain.toReversed()) {
 		if (!step.check) continue;
@@ -532,6 +810,29 @@ function checkWith(graph, definition, source, target) {
 	}
 	return OK;
 }
+/**
+* What a leg or end must also respect: an n-ary link has one end, and the base kind's same-actor
+* rule holds between each leg's source and the end's target (the hub belongs to no actor).
+*/
+function hubCheck(graph, definition, source, target) {
+	const base = definition.of === void 0 ? void 0 : graph.metamodel.links.get(definition.of);
+	if (!base) return OK;
+	const roleOf = (link) => graph.metamodel.links.get(link.kind)?.role;
+	if (definition.role === "end") {
+		for (const link of graph.model.links.values()) if (link.source === source.id && roleOf(link) === "end") return fail$1("duplicate-link", `the hub of a ${base.label} link has only one end`);
+		return OK;
+	}
+	if (base.rules?.sameActor === false) return OK;
+	for (const link of graph.model.links.values()) {
+		if (link.source !== target.id || roleOf(link) !== "end") continue;
+		if (graph.model.elements.get(link.target)?.parent !== source.parent) return fail$1("different-actors", `the sources and target of a ${base.label} link must pertain to the same actor`);
+	}
+	return OK;
+}
+/** 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`);
+}
 function refId(ref) {
 	return typeof ref === "string" ? ref : ref.id;
 }
@@ -683,12 +984,18 @@ function describe(graph, selectors) {
 		if (selector === "*") return "any element";
 		if (selector === "node") return "an intentional element";
 		if (selector === "actor") return "an actor";
+		if (selector === "link") return "a link";
+		const linkLabel = graph.metamodel.links.get(selector)?.label;
+		if (linkLabel !== void 0) return /^[aeiou]/i.test(linkLabel) ? `an ${linkLabel} link` : `a ${linkLabel} link`;
 		const label = graph.metamodel.elements.get(selector)?.label ?? selector;
 		return /^[aeiou]/i.test(label) ? `an ${label}` : `a ${label}`;
 	});
 	return names.length <= 2 ? names.join(" or ") : `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}`;
 }
 function matchesSelector(graph, element, selector) {
+	if (isLinkRef(element)) return selector === "link" || linkBehavesLike(graph.metamodel, element.kind, selector);
+	if (selector === "link") return false;
+	if (graph.metamodel.elements.get(element.kind)?.role === "hub") return element.kind === selector;
 	if (selector === "*") return true;
 	const category = graph.metamodel.elements.get(element.kind)?.category;
 	if (selector === "node" || selector === "actor") return category === selector;
@@ -697,15 +1004,21 @@ function matchesSelector(graph, element, selector) {
 /**
 * Declarative rules of an extension link kind, checked in the order of the iStar 2.0 node-link
 * rules (and of piStar-ext's generated `isValid`): source kind, target kind, self link,
-* dependum, same actor, duplicates.
+* dependum, same actor, duplicates. A link target skips the self, dependum and same-actor rules,
+* which are about elements.
 */
 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.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.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 (!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 (definition.category === "node" && !isLinkRef(target)) {
 		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)`);
 	}
@@ -756,9 +1069,10 @@ function validateModel(model, options) {
 		if (inbound) accepted.set(inbound.id, inbound);
 		if (outbound) accepted.set(outbound.id, outbound);
 	}
-	for (const link of any.links.values()) {
-		if (isDependency(link)) continue;
-		if (any.elements.has(link.source) && any.elements.has(link.target)) report(link.id, link.kind, link.source, link.target, check(link.source, link.target, link.kind));
+	const rest = [...any.links.values()].filter((link) => !isDependency(link));
+	const targetsLink = (link) => !any.elements.has(link.target) && any.links.has(link.target);
+	for (const link of [...rest.filter((l) => !targetsLink(l)), ...rest.filter((l) => targetsLink(l))]) {
+		if (any.elements.has(link.source) && (any.elements.has(link.target) || targetsLink(link))) report(link.id, link.kind, link.source, link.target, check(link.source, link.target, link.kind));
 		else report(link.id, link.kind, link.source, link.target, {
 			ok: false,
 			code: "unknown-element",
@@ -766,6 +1080,24 @@ function validateModel(model, options) {
 		});
 		accepted.set(link.id, link);
 	}
+	for (const hub of any.elements.values()) {
+		const hubKind = metamodel.elements.get(hub.kind);
+		if (hubKind?.role !== "hub" || hubKind.of === void 0) continue;
+		const base = metamodel.links.get(hubKind.of);
+		const roleOf = (link) => metamodel.links.get(link.kind)?.role;
+		const legs = rest.filter((l) => l.target === hub.id && roleOf(l) === "leg");
+		const end = rest.find((l) => l.source === hub.id && roleOf(l) === "end");
+		if (legs.length > 0 && end) continue;
+		const label = base?.label ?? hubKind.of;
+		issues.push({
+			linkId: hub.id,
+			kind: hubKind.of,
+			source: legs[0]?.source ?? hub.id,
+			target: end?.target ?? hub.id,
+			code: "incomplete-hub",
+			message: end ? `the hub of a ${label} link needs at least one leg` : `the hub of a ${label} link needs an end`
+		});
+	}
 	return issues;
 }
 //#endregion
@@ -890,6 +1222,11 @@ function fileMetamodelExtension(block) {
 }
 //#endregion
 //#region src/serialization.ts
+/**
+* Key of a hub element's `extra` that holds its entry's unknown keys (those beside `hub`,
+* `starts` and `end`), so they are written back on the entry.
+*/
+const HUB_ENTRY_KEY = "__hubEntry";
 var PistarParseError = class extends Error {
 	name = "PistarParseError";
 };
@@ -934,6 +1271,18 @@ const LINK_KEYS = /* @__PURE__ */ new Set([
 	"customProperties",
 	"label"
 ]);
+const HUB_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"type",
+	"x",
+	"y",
+	"customProperties"
+]);
+const HUB_ENTRY_KEYS = /* @__PURE__ */ new Set([
+	"hub",
+	"starts",
+	"end"
+]);
 const DIAGRAM_KEYS = /* @__PURE__ */ new Set([
 	"width",
 	"height",
@@ -1035,15 +1384,15 @@ function parsePistar(input, options = {}) {
 			...dependency
 		});
 	});
-	asArray(json.links, "links").forEach((raw, i) => {
-		if (!isRecord(raw)) throw new PistarParseError(`links[${i}]: expected an object`);
+	const readLink = (raw, where) => {
+		if (!isRecord(raw)) throw new PistarParseError(`${where}: expected an object`);
 		const { id, type, source, target } = raw;
-		if (typeof id !== "string" || id === "") throw new PistarParseError(`links[${i}]: missing "id"`);
+		if (typeof id !== "string" || id === "") throw new PistarParseError(`${where}: missing "id"`);
 		const kind = typeof type === "string" ? metamodel.linksByPistarType.get(type) : void 0;
-		if (kind === void 0) throw new PistarParseError(`links[${i}] (${id}): unknown link type ${JSON.stringify(type)}`);
-		if (typeof source !== "string" || typeof target !== "string") throw new PistarParseError(`links[${i}] (${id}): missing "source" or "target"`);
-		if (elements.has(id) || links.has(id)) throw new PistarParseError(`links[${i}]: duplicated id "${id}"`);
-		links.set(id, {
+		if (kind === void 0) throw new PistarParseError(`${where} (${id}): unknown link type ${JSON.stringify(type)}`);
+		if (typeof source !== "string" || typeof target !== "string") throw new PistarParseError(`${where} (${id}): missing "source" or "target"`);
+		if (elements.has(id) || links.has(id)) throw new PistarParseError(`${where}: duplicated id "${id}"`);
+		const link = {
 			id,
 			kind,
 			source,
@@ -1053,7 +1402,38 @@ function parsePistar(input, options = {}) {
 			...optional("label", typeof raw.label === "string" ? raw.label : void 0),
 			...optional("display", displayFor(id)),
 			...optional("extra", extraOf(raw, LINK_KEYS))
+		};
+		links.set(id, link);
+		return link;
+	};
+	const readHubEntry = (raw, where) => {
+		const hub = readElement(raw.hub, `${where}.hub`, HUB_KEYS, {});
+		const hubKind = metamodel.elements.get(hub.kind);
+		if (hubKind?.role !== "hub") throw new PistarParseError(`${where}.hub (${hub.id}): ${hub.kind} is not a hub kind`);
+		const entryExtra = extraOf(raw, HUB_ENTRY_KEYS);
+		if (entryExtra) elements.set(hub.id, {
+			...hub,
+			extra: {
+				...hub.extra,
+				[HUB_ENTRY_KEY]: entryExtra
+			}
 		});
+		const roleOf = (link) => {
+			const definition = metamodel.links.get(link.kind);
+			return definition?.of === hubKind.of ? definition?.role : void 0;
+		};
+		asArray(raw.starts, `${where}.starts`).forEach((rawLeg, j) => {
+			const leg = readLink(rawLeg, `${where}.starts[${j}]`);
+			if (roleOf(leg) !== "leg" || leg.target !== hub.id) throw new PistarParseError(`${where}.starts[${j}] (${leg.id}): not a leg of the hub "${hub.id}"`);
+		});
+		if (raw.end !== void 0) {
+			const end = readLink(raw.end, `${where}.end`);
+			if (roleOf(end) !== "end" || end.source !== hub.id) throw new PistarParseError(`${where}.end (${end.id}): not the end of the hub "${hub.id}"`);
+		}
+	};
+	asArray(json.links, "links").forEach((raw, i) => {
+		if (isRecord(raw) && isRecord(raw.hub)) readHubEntry(raw, `links[${i}]`);
+		else readLink(raw, `links[${i}]`);
 	});
 	let extraDisplay;
 	for (const [id, value] of Object.entries(display)) if (!usedDisplay.has(id)) (extraDisplay ??= {})[id] = value;
@@ -1085,6 +1465,64 @@ function parsePistar(input, options = {}) {
 	setHostMetamodel(model, host);
 	return withMetamodel(model, metamodel);
 }
+function parseJson(json) {
+	if (typeof json !== "string") return json;
+	let value;
+	try {
+		value = JSON.parse(json);
+	} catch (error) {
+		throw new PistarParseError(`invalid JSON: ${error.message}`, { cause: error });
+	}
+	if (!isRecord(value)) throw new PistarParseError("a piStar model must be a JSON object");
+	return value;
+}
+/** `kaos` for an object whose `type` is `kaos.Softgoal`. */
+function prefixOf(value) {
+	const type = isRecord(value) ? value.type : void 0;
+	const dot = typeof type === "string" ? type.indexOf(".") : -1;
+	return dot > 0 ? type.slice(0, dot) : void 0;
+}
+function arrayOf(value) {
+	return Array.isArray(value) ? value : [];
+}
+/**
+* The namespace of the first `type` in a file (`kaos` for `kaos.Softgoal`), looking at actors and
+* their nodes, orphans, dependencies, then links (hub entries included). `undefined` when no
+* element or link has a namespaced type. Throws `PistarParseError` for a string that isn't JSON.
+*/
+function detectPrefix(json) {
+	const file = parseJson(json);
+	const candidates = function* () {
+		for (const actor of arrayOf(file.actors)) {
+			yield actor;
+			if (isRecord(actor)) yield* arrayOf(actor.nodes);
+		}
+		yield* arrayOf(file.orphans);
+		yield* arrayOf(file.dependencies);
+		for (const link of arrayOf(file.links)) if (isRecord(link) && isRecord(link.hub)) {
+			yield link.hub;
+			yield* arrayOf(link.starts);
+			yield link.end;
+		} else yield link;
+	};
+	for (const candidate of candidates()) {
+		const prefix = prefixOf(candidate);
+		if (prefix !== void 0) return prefix;
+	}
+}
+/**
+* Which of `roots` a file is written in: the one whose `prefix` is the file's (`detectPrefix`);
+* for a file without types, the only one whose `file.tool` is the file's `tool`; otherwise
+* `undefined`. Pass the result to `parsePistar(json, { metamodel })`.
+*/
+function detectFramework(json, roots) {
+	const file = parseJson(json);
+	const prefix = detectPrefix(file);
+	if (prefix !== void 0) return roots.find((root) => root.prefix === prefix);
+	if (typeof file.tool !== "string") return void 0;
+	const byTool = roots.filter((root) => root.file.tool === file.tool);
+	return byTool.length === 1 ? byTool[0] : void 0;
+}
 function optional(key, value) {
 	return value === void 0 ? {} : { [key]: value };
 }
@@ -1110,37 +1548,43 @@ function toPistarObject(input, options = {}) {
 	const model = input;
 	const metamodel = options.metamodel ?? metamodelOf(input);
 	const isActorKind = (kind) => metamodel.elements.get(kind)?.category === "actor";
+	const isHub = (element) => metamodel.elements.get(element.kind)?.role === "hub";
 	const actors = [];
 	const orphans = [];
 	const dependencies = [];
 	const children = /* @__PURE__ */ new Map();
-	for (const element of model.elements.values()) if (element.parent !== void 0 && !isActorKind(element.kind)) {
-		let list = children.get(element.parent);
-		if (!list) children.set(element.parent, list = []);
-		list.push({
+	for (const element of model.elements.values()) {
+		if (isHub(element)) continue;
+		if (element.parent !== void 0 && !isActorKind(element.kind)) {
+			let list = children.get(element.parent);
+			if (!list) children.set(element.parent, list = []);
+			list.push({
+				...elementJson(element, metamodel),
+				...element.extra
+			});
+		}
+	}
+	for (const element of model.elements.values()) {
+		if (isHub(element)) continue;
+		if (isActorKind(element.kind)) actors.push({
 			...elementJson(element, metamodel),
+			nodes: children.get(element.id) ?? [],
 			...element.extra
 		});
-	}
-	for (const element of model.elements.values()) if (isActorKind(element.kind)) actors.push({
-		...elementJson(element, metamodel),
-		nodes: children.get(element.id) ?? [],
-		...element.extra
-	});
-	else if (element.isDependum) {
-		const { inbound, outbound } = dependencyLinksOf(model, element.id);
-		dependencies.push({
+		else if (element.isDependum) {
+			const { inbound, outbound } = dependencyLinksOf(model, element.id);
+			dependencies.push({
+				...elementJson(element, metamodel),
+				source: inbound?.source ?? element.dependency?.source ?? "",
+				target: outbound?.target ?? element.dependency?.target ?? "",
+				...element.extra
+			});
+		} else if (element.parent === void 0 || !model.elements.has(element.parent)) orphans.push({
 			...elementJson(element, metamodel),
-			source: inbound?.source ?? element.dependency?.source ?? "",
-			target: outbound?.target ?? element.dependency?.target ?? "",
 			...element.extra
 		});
-	} else if (element.parent === void 0 || !model.elements.has(element.parent)) orphans.push({
-		...elementJson(element, metamodel),
-		...element.extra
-	});
-	const links = [];
-	for (const link of model.links.values()) links.push({
+	}
+	const linkJson = (link) => ({
 		id: link.id,
 		type: pistarTypeOf(metamodel.links.get(link.kind)?.pistarType, link.kind, metamodel),
 		source: link.source,
@@ -1150,6 +1594,54 @@ function toPistarObject(input, options = {}) {
 		...link.label !== void 0 ? { label: link.label } : {},
 		...link.extra
 	});
+	const hubs = /* @__PURE__ */ new Map();
+	const partsOf = (hubId) => {
+		let parts = hubs.get(hubId);
+		if (!parts) hubs.set(hubId, parts = { legs: [] });
+		return parts;
+	};
+	const hubOf = (link) => {
+		const role = metamodel.links.get(link.kind)?.role;
+		const id = role === "leg" ? link.target : role === "end" ? link.source : void 0;
+		const hub = id === void 0 ? void 0 : model.elements.get(id);
+		return hub && isHub(hub) ? hub.id : void 0;
+	};
+	for (const link of model.links.values()) {
+		const hubId = hubOf(link);
+		if (hubId === void 0) continue;
+		const parts = partsOf(hubId);
+		if (metamodel.links.get(link.kind)?.role === "leg") parts.legs.push(link);
+		else parts.end ??= link;
+	}
+	const hubEntry = (hub) => {
+		const parts = hubs.get(hub.id) ?? { legs: [] };
+		const { [HUB_ENTRY_KEY]: entryExtra, ...hubExtra } = hub.extra ?? {};
+		return {
+			hub: {
+				id: hub.id,
+				type: pistarTypeOf(metamodel.elements.get(hub.kind)?.pistarType, hub.kind, metamodel),
+				x: hub.x,
+				y: hub.y,
+				...hub.customProperties ? { customProperties: { ...hub.customProperties } } : {},
+				...hubExtra
+			},
+			starts: parts.legs.map(linkJson),
+			...parts.end ? { end: linkJson(parts.end) } : {},
+			...isRecord(entryExtra) ? entryExtra : {}
+		};
+	};
+	const links = [];
+	const written = /* @__PURE__ */ new Set();
+	for (const link of model.links.values()) {
+		const hubId = hubOf(link);
+		const parts = hubId === void 0 ? void 0 : hubs.get(hubId);
+		if (hubId === void 0 || !parts || !parts.legs.includes(link) && parts.end !== link) links.push(linkJson(link));
+		else if (!written.has(hubId)) {
+			written.add(hubId);
+			links.push(hubEntry(model.elements.get(hubId)));
+		}
+	}
+	for (const element of model.elements.values()) if (isHub(element) && !written.has(element.id)) links.push(hubEntry(element));
 	const layout = layouts.get(model);
 	const display = {};
 	const displayOf = (id) => {
@@ -1197,7 +1689,7 @@ function toPistarObject(input, options = {}) {
 		if ((Array.isArray(value) ? value.length === 0 : Object.keys(value).length === 0) && !layout.keys.includes(key)) values[key] = void 0;
 	}
 	const order = [
-		...layout?.keys ?? [],
+		...layout?.keys ?? metamodel.file.keys ?? [],
 		...TOP_LEVEL_KEYS,
 		...Object.keys(model.extra ?? {})
 	];
@@ -1386,7 +1878,8 @@ function nestElement(model, id, parent) {
 }
 /**
 * Removes elements and everything that depends on them: inner elements of removed actors,
-* links touching removed elements, and the rest of any dependency that loses a part.
+* links touching removed elements (and links targeting removed links), and the rest of any
+* dependency that loses a part.
 */
 function removeElements(model, ids) {
 	return typed(removeCascade(any(model), new Set(ids), /* @__PURE__ */ new Set()));
@@ -1410,11 +1903,28 @@ function removeCascade(model, elementIds, linkIds) {
 		}
 		for (const link of model.links.values()) {
 			if (linkIds.has(link.id)) continue;
-			if (elementIds.has(link.source) || elementIds.has(link.target)) {
+			if (elementIds.has(link.source) || elementIds.has(link.target) || linkIds.has(link.target)) {
 				linkIds.add(link.id);
 				changed = true;
 			}
 		}
+		for (const element of model.elements.values()) {
+			if (elementIds.has(element.id) || metamodel.elements.get(element.kind)?.role !== "hub") continue;
+			let legs = 0;
+			let removedLegs = 0;
+			let endRemoved = false;
+			for (const link of model.links.values()) {
+				const role = metamodel.links.get(link.kind)?.role;
+				if (role === "leg" && link.target === element.id) {
+					legs++;
+					if (linkIds.has(link.id)) removedLegs++;
+				} else if (role === "end" && link.source === element.id && linkIds.has(link.id)) endRemoved = true;
+			}
+			if (endRemoved || legs > 0 && removedLegs === legs) {
+				elementIds.add(element.id);
+				changed = true;
+			}
+		}
 		for (const link of model.links.values()) {
 			if (!linkIds.has(link.id) || !isDependencyHalf(link)) continue;
 			for (const end of [link.source, link.target]) if (model.elements.get(end)?.isDependum && !elementIds.has(end)) {
@@ -1433,13 +1943,21 @@ function removeCascade(model, elementIds, linkIds) {
 		links
 	});
 }
-/** Adds a link between two elements if the iStar constraints allow it. */
+/**
+* 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.
+*/
 function connect(model, input, options = {}) {
 	const m = any(model);
 	const metamodel = metaOf(m);
 	const kind = input.kind;
 	const definition = metamodel.links.get(kind);
 	if (definition?.category === "dependency") throw new ModelOperationError("use addDependency to create dependencies");
+	if (definition?.parts) return connectHub(m, definition, input, options);
 	let { source, target } = input;
 	let reversed = false;
 	if (!options.force) {
@@ -1457,7 +1975,7 @@ function connect(model, input, options = {}) {
 	} else {
 		if (!definition) throw new ModelOperationError(`unknown link kind "${kind}" in ${metamodel.name}`);
 		requireElement(m, source);
-		requireElement(m, target);
+		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`);
@@ -1477,6 +1995,113 @@ function connect(model, input, options = {}) {
 		reversed
 	};
 }
+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 (!options.force) {
+		const check = canLink(m, source, target, definition.kind);
+		if (!check.ok) return check;
+	}
+	const from = requireElement(m, source);
+	const to = requireElement(m, target);
+	const createId = options.createId ?? defaultIdGenerator;
+	const hubId = input.id ?? createId();
+	const legId = createId();
+	const endId = createId();
+	for (const [i, id] of [
+		hubId,
+		legId,
+		endId
+	].entries()) if (m.elements.has(id) || m.links.has(id) || [
+		hubId,
+		legId,
+		endId
+	].indexOf(id) !== i) throw new ModelOperationError(`id "${id}" is already in use`);
+	const position = defaultHubPosition(m, from, to, metamodel.elements.get(parts.hub)?.size ?? {
+		width: 20,
+		height: 20
+	});
+	const hub = withoutUndefined({
+		id: hubId,
+		kind: parts.hub,
+		name: "",
+		x: position.x,
+		y: position.y,
+		customProperties: input.customProperties
+	});
+	const leg = {
+		id: legId,
+		kind: parts.leg,
+		source,
+		target: hubId
+	};
+	const end = withoutUndefined({
+		id: endId,
+		kind: parts.end,
+		source: hubId,
+		target,
+		label: input.label,
+		name: input.name
+	});
+	return {
+		ok: true,
+		model: typed(derive(m, {
+			elements: new Map(m.elements).set(hubId, hub),
+			links: new Map(m.links).set(legId, leg).set(endId, end)
+		})),
+		link: end,
+		reversed: false,
+		hub: {
+			hub,
+			legs: [leg],
+			end
+		}
+	};
+}
+/**
+* Adds a leg from `source` to the hub `hubId` of an n-ary link (one more source for it), if the
+* kind's rules allow it. `options.id` is the leg's id.
+*/
+function addLeg(model, hubId, source, options = {}) {
+	const m = any(model);
+	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`);
+	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`);
+	const leg = {
+		id,
+		kind,
+		source,
+		target: hubId
+	};
+	const next = derive(m, { links: new Map(m.links).set(id, leg) });
+	return {
+		ok: true,
+		model: typed(next),
+		link: leg,
+		reversed: false,
+		hub: hubLinkOf(typed(next), hubId)
+	};
+}
+/**
+* Removes one leg of an n-ary link. Removing its last leg removes the whole link (hub and end),
+* as `disconnect` does.
+*/
+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`);
+	return disconnect(model, legId);
+}
 /** Adds depender → dependum → dependee. */
 function addDependency(model, input, options = {}) {
 	const m = any(model);
@@ -1529,7 +2154,10 @@ function addDependency(model, input, options = {}) {
 		links: [first, second]
 	};
 }
-/** Removes a link. Removing either half of a dependency removes the whole dependency. */
+/**
+* Removes a link, and the links that target it. Removing either half of a dependency removes
+* the whole dependency.
+*/
 function disconnect(model, id) {
 	const m = any(model);
 	requireLink(m, id);
@@ -1664,10 +2292,29 @@ function createModelStore(initial, options = {}) {
 			});
 			if (result.ok) commit(result.model, {
 				type: "connect",
-				id: result.link.id
+				id: result.link.id,
+				...result.hub ? { hubId: result.hub.hub.id } : {}
 			});
 			return result;
 		},
+		addLeg(hubId, source, legOptions) {
+			const result = addLeg(model, hubId, source, {
+				...legOptions,
+				...ctx
+			});
+			if (result.ok) commit(result.model, {
+				type: "connect",
+				id: result.link.id,
+				hubId
+			});
+			return result;
+		},
+		removeLeg(id) {
+			commit(removeLeg(model, id), {
+				type: "removeLeg",
+				id
+			});
+		},
 		addDependency(input, dependencyOptions) {
 			const result = addDependency(model, input, {
 				...dependencyOptions,
@@ -1896,7 +2543,7 @@ const prop = {
 function isCustomPropertiesRecord(source) {
 	if ("customProperties" in source) return false;
 	const owner = source;
-	return !(typeof owner.kind === "string" && owner.kind.startsWith("istar.") && (typeof owner.x === "number" || owner.source !== void 0 && owner.target !== void 0));
+	return !(typeof owner.kind === "string" && owner.kind.includes(".") && (typeof owner.x === "number" || typeof owner.source === "string" && typeof owner.target === "string"));
 }
 function resolveCustomProperties(source) {
 	if (source === void 0) return void 0;
@@ -2026,6 +2673,176 @@ 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, 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 };
+//#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
+export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, 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, 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, removeElement, removeElements, removeLeg, setHostMetamodel, shortKindName, string, targetsLinks, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
 
 //# sourceMappingURL=index.js.map