@istar-ts/actions 0.0.0-stage → 0.15.0-beta.0

package/dist/index.js

@@ -0,0 +1,1103 @@
+import { DEFAULT_PALETTE, DIAGNOSTIC_SEVERITIES, FILE_METAMODEL_KEY, LINK_SELECTOR, ModelOperationError, canLink, connectResultToDiagnostic, createEmptyModel, dependencyEnds, effectiveLinkKind, elementBehavesLike, inheritMetamodel, inheritSourceLayout, linkBehavesLike, metamodelOf, parsePistar, toPistarObject, validateModel, validateModelProperties } from "@istar-ts/core";
+//#region src/actions.ts
+const OPERATION_KIND_LIST = [
+	"createNode",
+	"createEdge",
+	"deleteElement",
+	"changeBounds",
+	"changeContainer",
+	"reconnectEdge",
+	"applyLabelEdit",
+	"compound",
+	"istar.addLeg",
+	"istar.removeLeg",
+	"istar.setCollapsed",
+	"istar.updateDiagram",
+	"istar.updateProperties",
+	"istar.updateDisplay",
+	"istar.setLinkValue",
+	"istar.updateLinkDisplay"
+];
+const REQUEST_KIND_LIST = [
+	"requestModel",
+	"requestTypeHints",
+	"requestCheckEdge",
+	"requestContextActions",
+	"requestMarkers"
+];
+/**
+* The other actions the dispatcher accepts: `glspUndo`/`glspRedo`/`saveModel` (acted on), then
+* the notifications it only re-emits to subscribers (`IstarNotificationAction`'s kinds).
+*/
+const NOTIFICATION_KIND_LIST = [
+	"glspUndo",
+	"glspRedo",
+	"saveModel",
+	"sourceModelChanged",
+	"setDirtyState",
+	"triggerNodeCreation",
+	"triggerEdgeCreation",
+	"deleteMarkers"
+];
+const OPERATION_KINDS = new Set(OPERATION_KIND_LIST);
+const REQUEST_KINDS = new Set(REQUEST_KIND_LIST);
+/**
+* The action kinds `createActionDispatcher` accepts, grouped the way it treats them: `operations`
+* edit the model as one undo step, `requests` get a response action, `notifications` (plus
+* `glspUndo`/`glspRedo`/`saveModel`) are acted on or re-emitted as is. Derived from the same
+* lists `isOperation`/`isRequestAction` use, so it can't drift from the dispatcher.
+*/
+const HANDLED_ACTION_KINDS = {
+	operations: OPERATION_KIND_LIST,
+	requests: REQUEST_KIND_LIST,
+	notifications: NOTIFICATION_KIND_LIST
+};
+/** True for the operations (actions that edit the model). */
+function isOperation(action) {
+	return OPERATION_KINDS.has(action.kind);
+}
+/** True for the requests (actions answered with a response action). */
+function isRequestAction(action) {
+	return REQUEST_KINDS.has(action.kind);
+}
+//#endregion
+//#region src/hints.ts
+/**
+* What a client can know before it asks: type hints from the metamodel, and the palette as
+* GLSP context actions. Both are derived from data (`Metamodel`, `PaletteDescription`), so they
+* work for any root or extension.
+*/
+function isHub(definition) {
+	return definition.role === "hub";
+}
+/** Element kinds a rule selector matches, as `canLink` matches elements against it. */
+function matching(metamodel, selector) {
+	const kinds = [];
+	for (const definition of metamodel.elements.values()) if (isHub(definition) ? definition.kind === selector : selector === "*" || selector === definition.category || elementBehavesLike(metamodel, definition.kind, selector)) kinds.push(definition.kind);
+	if (selector === LINK_SELECTOR) kinds.push(...metamodel.links.keys());
+	else if (metamodel.links.has(selector)) {
+		for (const kind of metamodel.links.keys()) if (linkBehavesLike(metamodel, kind, selector)) kinds.push(kind);
+	}
+	return kinds;
+}
+function union(metamodel, selectors) {
+	return [...new Set(selectors.flatMap((selector) => matching(metamodel, selector)))];
+}
+/** Kinds of a category, without hubs. */
+function ofCategory(metamodel, category) {
+	return [...metamodel.elements.values()].filter((d) => !isHub(d) && (category === void 0 || d.category === category)).map((d) => d.kind);
+}
+/**
+* GLSP type hints of a metamodel. Shapes: every element kind (hubs can't be resized or
+* reparented; actors contain the node kinds that can be inner elements). Edges: every link kind,
+* its sources and targets from its rules, or by category for kinds with built-in rules (iStar
+* 2.0's), plus an n-ary kind's hub (`createEdge` onto a hub adds a leg to that link, #108). Edge
+* hints are `repositionable` (their ends can be reconnected) and `dynamic`: `canLink` checks more
+* than kinds.
+*/
+function typeHintsFor(metamodel) {
+	const meta = metamodel;
+	const inner = [...meta.elements.values()].filter((d) => d.category === "node" && !isHub(d) && d.info?.canBeInnerElement !== false).map((d) => d.kind);
+	return {
+		shapeHints: [...meta.elements.values()].map((d) => {
+			const hub = isHub(d);
+			return {
+				elementTypeId: d.kind,
+				repositionable: true,
+				deletable: true,
+				resizable: !hub,
+				reparentable: !hub && d.category === "node" && d.info?.canBeInnerElement !== false,
+				...d.category === "actor" ? { containableElementTypeIds: inner } : {}
+			};
+		}),
+		edgeHints: [...meta.links.values()].map((d) => {
+			const rules = meta.links.get(effectiveLinkKind(meta, d.kind))?.rules;
+			const builtIn = d.category === "dependency" ? ofCategory(meta) : ofCategory(meta, d.category);
+			const targets = rules ? union(meta, rules.targets) : builtIn;
+			const hub = d.parts?.hub;
+			return {
+				elementTypeId: d.kind,
+				repositionable: true,
+				deletable: true,
+				routable: true,
+				sourceElementTypeIds: rules ? union(meta, rules.sources) : builtIn,
+				targetElementTypeIds: hub === void 0 ? targets : [...targets, hub],
+				dynamic: true
+			};
+		})
+	};
+}
+function elementEntries(kind, value) {
+	return (Array.isArray(value) ? value : [value]).map((entry, i) => labeled(Array.isArray(value) ? `${kind}#${i}` : kind, entry, {
+		kind: "triggerNodeCreation",
+		elementTypeId: kind,
+		...entry.properties ? { args: { customProperties: entry.properties } } : {}
+	}));
+}
+function linkEntries(kind, list) {
+	return list.map((entry, i) => {
+		const args = {
+			...entry.value === void 0 ? {} : { value: entry.value },
+			...entry.dependum === void 0 ? {} : { dependum: { kind: entry.dependum } }
+		};
+		return labeled(`${kind}#${i}`, entry, {
+			kind: "triggerEdgeCreation",
+			elementTypeId: kind,
+			...Object.keys(args).length > 0 ? { args } : {}
+		});
+	});
+}
+function order(action) {
+	return action.order ?? Number.POSITIVE_INFINITY;
+}
+function labeled(id, entry, action) {
+	return {
+		id,
+		label: entry.label,
+		actions: [action],
+		...entry.group === void 0 ? {} : { group: entry.group },
+		...entry.section === void 0 ? {} : { section: entry.section },
+		...entry.order === void 0 ? {} : { order: entry.order }
+	};
+}
+/**
+* A palette as GLSP context actions: one `LabeledAction` per entry, triggering the client's
+* creation tool with the entry's presets, sorted by `order`. Only the metamodel's kinds are
+* offered, in the metamodel's order where orders tie; kinds the palette hides (`false`) or
+* lacks are left out.
+*/
+function contextActionsFor(palette, metamodel) {
+	const meta = metamodel;
+	const actions = [];
+	for (const kind of meta.elements.keys()) {
+		const value = palette.elements[kind];
+		if (value) actions.push(...elementEntries(kind, value));
+	}
+	for (const kind of meta.links.keys()) {
+		const list = palette.links[kind];
+		if (list) actions.push(...linkEntries(kind, list));
+	}
+	actions.sort((a, b) => order(a) === order(b) ? 0 : order(a) < order(b) ? -1 : 1);
+	return {
+		actions,
+		groups: palette.groups
+	};
+}
+//#endregion
+//#region src/markers.ts
+/** A `GoalDiagnostic` as a GLSP marker: `kind` is its severity, `label` its message. */
+function diagnosticToMarker(diagnostic) {
+	const { elementId, key, severity, message, source, code } = diagnostic;
+	return {
+		label: message,
+		description: source === void 0 ? message : `${message} (${source})`,
+		elementId,
+		kind: severity,
+		...key === void 0 ? {} : { key },
+		...source === void 0 ? {} : { source },
+		...code === void 0 ? {} : { code }
+	};
+}
+/**
+* A GLSP marker as a `GoalDiagnostic`. A `kind` that is no `DiagnosticSeverity` reads as
+* `info`; `range` and `data` are not carried by markers.
+*/
+function markerToDiagnostic(marker) {
+	const { elementId, kind, label, key, source, code } = marker;
+	return {
+		elementId,
+		severity: DIAGNOSTIC_SEVERITIES.includes(kind) ? kind : "info",
+		message: label,
+		...key === void 0 ? {} : { key },
+		...source === void 0 ? {} : { source },
+		...code === void 0 ? {} : { code }
+	};
+}
+//#endregion
+//#region src/dispatcher.ts
+/**
+* The dispatcher: the server side of the protocol over a `ModelStore`. Operations run as one
+* store transaction each and are rejected, model untouched, with `GoalDiagnostic`s; requests
+* are answered from the model, its metamodel and the palette; store changes reach subscribers
+* as `ModelSourceChangedAction`s, whoever made them.
+*/
+/** Thrown inside a transaction to roll it back and reject the action. */
+var Rejection = class extends Error {
+	diagnostics;
+	constructor(diagnostics) {
+		super(diagnostics.map((d) => d.message).join("; "));
+		this.diagnostics = diagnostics;
+	}
+};
+function reject(message, elementId = "", code) {
+	throw new Rejection([{
+		elementId,
+		severity: "error",
+		message,
+		...code === void 0 ? {} : { code }
+	}]);
+}
+function rejectCheck(check, endpoints) {
+	throw new Rejection([connectResultToDiagnostic(check, endpoints)]);
+}
+function metaOf(model) {
+	return metamodelOf(model);
+}
+/** A model with `links` changed, as the core operations derive one. */
+function withLinks(model, links) {
+	return inheritMetamodel(model, inheritSourceLayout(model, {
+		...model,
+		links
+	}));
+}
+function createdIds(before, after) {
+	const ids = [];
+	for (const id of after.elements.keys()) if (!before.elements.has(id)) ids.push(id);
+	for (const id of after.links.keys()) if (!before.links.has(id)) ids.push(id);
+	return ids;
+}
+function issueKey(d) {
+	return `${d.id}\u0000${d.key}\u0000${d.message}`;
+}
+function linkIssueDiagnostics(model) {
+	return validateModel(model).map((issue) => ({
+		elementId: issue.linkId,
+		severity: "error",
+		message: issue.message,
+		code: issue.code
+	}));
+}
+/**
+* A dispatcher over `store`, in-process. Hand it to a transport to serve remote clients.
+*/
+function createActionDispatcher(store, options = {}) {
+	const s = store;
+	const guards = options.guards ?? [];
+	const palette = options.palette ?? DEFAULT_PALETTE;
+	const sourceModelName = options.sourceModelName ?? "";
+	const listeners = /* @__PURE__ */ new Set();
+	let saved = s.getModel();
+	let dirty = false;
+	const emit = (action) => {
+		for (const listener of listeners) listener(action);
+	};
+	const updateDirty = (reason) => {
+		const next = s.getModel() !== saved;
+		if (next === dirty) return;
+		dirty = next;
+		emit({
+			kind: "setDirtyState",
+			isDirty: next,
+			reason
+		});
+	};
+	const REASONS = {
+		edit: "operation",
+		undo: "undo",
+		redo: "redo",
+		load: "external"
+	};
+	const unsubscribe = s.subscribe((event) => {
+		if (event.source === "load") saved = event.model;
+		emit({
+			kind: "sourceModelChanged",
+			sourceModelName,
+			source: event.source,
+			changes: event.changes,
+			...options.sendModel ? { newRoot: toPistarObject(event.model) } : {},
+			...options.sendModel ? {
+				canUndo: s.canUndo(),
+				canRedo: s.canRedo()
+			} : {}
+		});
+		updateDirty(REASONS[event.source]);
+	});
+	const requireElement = (id) => s.getModel().elements.get(id) ?? reject(`unknown element "${id}"`, id, "unknown-element");
+	const runGuards = (operation, warnings) => {
+		const errors = [];
+		for (const guard of guards) for (const d of guard(operation, s.getModel()) ?? []) (d.severity === "error" ? errors : warnings).push(d);
+		if (errors.length > 0) throw new Rejection(errors);
+	};
+	const apply = (operation, warnings) => {
+		runGuards(operation, warnings);
+		const model = s.getModel();
+		const meta = metaOf(model);
+		switch (operation.kind) {
+			case "createNode": {
+				const { elementTypeId: kind, containerId, args = {} } = operation;
+				const definition = meta.elements.get(kind) ?? reject(`unknown element kind "${kind}" in ${meta.name}`, "", "unknown-kind");
+				if (definition.role === "hub") reject(`a ${definition.label} is created with its link (createEdge)`, "", "hub-kind");
+				const container = containerId === void 0 ? void 0 : requireElement(containerId);
+				if (definition.category === "node") {
+					if (container && definition.info?.canBeInnerElement === false) reject(`a ${definition.label} cannot be inside an actor`, containerId, "container");
+					if (!container && definition.info?.canBeOnPaper === false) reject(`a ${definition.label} must be created inside an actor`, "", "container");
+				}
+				const location = operation.location ?? container ?? {
+					x: 0,
+					y: 0
+				};
+				s.addElement({
+					kind,
+					x: location.x,
+					y: location.y,
+					...containerId === void 0 ? {} : { parent: containerId },
+					...args.id === void 0 ? {} : { id: args.id },
+					...args.name === void 0 ? {} : { name: args.name },
+					...args.customProperties ? { customProperties: args.customProperties } : {}
+				});
+				return;
+			}
+			case "createEdge": {
+				const { elementTypeId: kind, sourceElementId: source, targetElementId: target } = operation;
+				const args = operation.args ?? {};
+				const definition = meta.links.get(kind) ?? reject(`unknown link kind "${kind}" in ${meta.name}`, "", "unknown-kind");
+				if (definition.category === "dependency") {
+					const dependum = args.dependum ?? {};
+					const dependumKind = dependum.kind ?? [...meta.elements.values()].find((d) => d.category === "node" && d.role !== "hub" && d.info?.canBeDependum !== false)?.kind ?? reject(`${meta.name} has no kind that can be a dependum`, "", "unknown-kind");
+					const result = s.addDependency({
+						depender: source,
+						dependee: target,
+						linkKind: kind,
+						dependum: {
+							kind: dependumKind,
+							...dependum.id === void 0 ? {} : { id: dependum.id },
+							...dependum.name === void 0 ? {} : { name: dependum.name },
+							...dependum.location ? {
+								x: dependum.location.x,
+								y: dependum.location.y
+							} : {},
+							...dependum.customProperties ? { customProperties: dependum.customProperties } : {}
+						},
+						...args.linkIds ? { linkIds: args.linkIds } : {}
+					});
+					if (!result.ok) rejectCheck(result, {
+						source,
+						target
+					});
+					return;
+				}
+				const values = definition.info.possibleLabels;
+				if (args.value !== void 0 && values && !values.includes(args.value)) reject(`"${args.value}" is not a value of a ${definition.label} link (${values.join(", ")})`, source, "invalid-value");
+				const result = s.connect({
+					kind,
+					source,
+					target,
+					...args.id === void 0 ? {} : { id: args.id },
+					...args.value === void 0 ? {} : { label: args.value },
+					...args.name === void 0 ? {} : { name: args.name },
+					...args.customProperties ? { customProperties: args.customProperties } : {},
+					...args.legId === void 0 ? {} : { legId: args.legId },
+					...args.endId === void 0 ? {} : { endId: args.endId }
+				});
+				if (!result.ok) rejectCheck(result, {
+					source,
+					target
+				});
+				return;
+			}
+			case "deleteElement": {
+				const elements = [];
+				const links = [];
+				for (const id of operation.elementIds) if (model.elements.has(id)) elements.push(id);
+				else if (model.links.has(id)) links.push(id);
+				else reject(`unknown element or link "${id}"`, id, "unknown-element");
+				if (elements.length > 0) s.removeElements(elements);
+				for (const id of links) if (s.getModel().links.has(id)) s.disconnect(id);
+				return;
+			}
+			case "changeBounds":
+				for (const { elementId, newPosition, newSize } of operation.newBounds) {
+					requireElement(elementId);
+					if (newPosition) s.moveElement(elementId, newPosition.x, newPosition.y);
+					if (newSize) s.updateElement(elementId, { display: {
+						width: newSize.width,
+						height: newSize.height
+					} });
+				}
+				return;
+			case "changeContainer": {
+				const { elementId, targetContainerId, location } = operation;
+				s.nestElement(elementId, targetContainerId);
+				if (location) s.moveElement(elementId, location.x, location.y);
+				return;
+			}
+			case "reconnectEdge":
+				reconnect(operation.edgeElementId, operation.sourceElementId, operation.targetElementId);
+				return;
+			case "applyLabelEdit": {
+				const hash = operation.labelId.indexOf("#");
+				const id = hash < 0 ? operation.labelId : operation.labelId.slice(0, hash);
+				const key = hash < 0 ? void 0 : operation.labelId.slice(hash + 1);
+				if (key === void 0) {
+					if (model.elements.has(id)) s.updateElement(id, { name: operation.text });
+					else if (model.links.has(id)) s.updateLink(id, { name: operation.text === "" ? null : operation.text });
+					else reject(`unknown element or link "${id}"`, id, "unknown-element");
+				} else setProperties(id, { [key]: operation.text });
+				return;
+			}
+			case "compound":
+				for (const child of operation.operationList) apply(child, warnings);
+				return;
+			case "istar.addLeg": {
+				const { hubId, sourceElementId: source } = operation;
+				const result = s.addLeg(hubId, source, operation.args?.id ? { id: operation.args.id } : {});
+				if (!result.ok) rejectCheck(result, {
+					source,
+					target: hubId
+				});
+				return;
+			}
+			case "istar.removeLeg":
+				s.removeLeg(operation.legId);
+				return;
+			case "istar.setCollapsed": {
+				const element = requireElement(operation.elementId);
+				if (meta.elements.get(element.kind)?.category !== "actor") reject(`"${element.id}" is not an actor`, element.id, "not-an-actor");
+				s.setCollapsed(element.id, operation.collapsed);
+				return;
+			}
+			case "istar.updateDiagram": {
+				const { name, width, height, customProperties } = operation.diagram;
+				s.updateDiagram({
+					...name === void 0 ? {} : { name },
+					...width === void 0 ? {} : { width },
+					...height === void 0 ? {} : { height },
+					...customProperties === void 0 ? {} : { customProperties }
+				});
+				return;
+			}
+			case "istar.updateProperties":
+				setProperties(operation.elementId, operation.properties);
+				return;
+			case "istar.updateDisplay":
+				requireElement(operation.elementId);
+				s.updateElement(operation.elementId, { display: operation.patch });
+				return;
+			case "istar.updateLinkDisplay":
+				if (!model.links.has(operation.linkId)) reject(`unknown link "${operation.linkId}"`, operation.linkId, "unknown-element");
+				s.updateLink(operation.linkId, { display: operation.patch });
+				return;
+			case "istar.setLinkValue": {
+				const { linkId, value } = operation;
+				const link = model.links.get(linkId) ?? reject(`unknown link "${linkId}"`, linkId, "unknown-element");
+				const definition = meta.links.get(link.kind);
+				const values = definition?.info.possibleLabels;
+				if (value !== null && values && !values.includes(value)) reject(`"${value}" is not a value of a ${definition.label} link (${values.join(", ")})`, linkId, "invalid-value");
+				s.updateLink(linkId, { label: value });
+				return;
+			}
+			default: reject(`unknown operation "${operation.kind}"`, "", "unknown-action");
+		}
+	};
+	/** Sets (or, with `null`, removes) custom properties of an element or link. */
+	const setProperties = (id, properties) => {
+		const model = s.getModel();
+		const owner = model.elements.get(id) ?? model.links.get(id);
+		if (!owner) reject(`unknown element or link "${id}"`, id, "unknown-element");
+		const next = { ...owner.customProperties };
+		for (const [key, value] of Object.entries(properties)) if (value === null) delete next[key];
+		else if (typeof value === "string") next[key] = value;
+		else reject(`the value of "${key}" must be a string or null`, id, "invalid-value");
+		const customProperties = Object.keys(next).length > 0 ? next : null;
+		if (model.elements.has(id)) s.updateElement(id, { customProperties });
+		else s.updateLink(id, { customProperties });
+	};
+	/**
+	* Gives a link new ends, checked with `canLink` against the model without it. The link keeps
+	* its place in the model (and the file), its id and everything else it carries.
+	*/
+	const reconnect = (id, source, target) => {
+		const model = s.getModel();
+		const meta = metaOf(model);
+		const link = model.links.get(id) ?? reject(`unknown link "${id}"`, id, "unknown-element");
+		if (link.source === source && link.target === target) return;
+		const definition = meta.links.get(link.kind);
+		const others = new Map(model.links);
+		others.delete(id);
+		const without = withLinks(model, others);
+		let check;
+		if (definition?.category === "dependency") {
+			const dependumAtTarget = model.elements.get(link.target)?.isDependum === true;
+			const dependumId = dependumAtTarget ? link.target : link.source;
+			if ((dependumAtTarget ? target : source) !== dependumId) reject("a dependency link keeps its dependum", id, "dependum-endpoint");
+			const ends = dependencyEnds(model, dependumId);
+			const depender = dependumAtTarget ? source : ends.depender;
+			const dependee = dependumAtTarget ? ends.dependee : target;
+			if (depender === void 0 || dependee === void 0) reject("the dependency is incomplete", id, "dependum-endpoint");
+			check = canLink(without, depender, dependee, link.kind);
+			if (!check.ok) rejectCheck(check, {
+				source: depender,
+				target: dependee
+			});
+		} else {
+			if (definition?.role === "end" && source !== link.source) reject("the end of an n-ary link stays on its hub", id, "hub-target");
+			if (definition?.role === "leg" && target !== link.target) {
+				if ([...model.links.values()].filter((l) => l.target === link.target && l.kind === link.kind).length === 1) reject("the last leg of an n-ary link cannot leave its hub", id, "hub-target");
+			}
+			check = canLink(without, source, target, link.kind);
+			if (!check.ok) rejectCheck(check, {
+				source,
+				target
+			});
+		}
+		s.replace(withLinks(model, new Map(model.links).set(id, {
+			...link,
+			source,
+			target
+		})));
+	};
+	const runOperation = (operation) => {
+		const before = s.getModel();
+		const warnings = [];
+		s.transaction(() => {
+			apply(operation, warnings);
+			const schemas = options.schemas;
+			if (!schemas || s.getModel() === before) return;
+			const known = new Set(validateModelProperties(before, schemas).map(issueKey));
+			const added = validateModelProperties(s.getModel(), schemas).filter((issue) => !known.has(issueKey(issue)));
+			if (added.length > 0) throw new Rejection(added.map((issue) => ({
+				elementId: issue.id,
+				key: issue.key,
+				severity: "error",
+				message: issue.message,
+				code: "invalid-property"
+			})));
+		});
+		return {
+			ok: true,
+			createdIds: createdIds(before, s.getModel()),
+			...warnings.length > 0 ? { diagnostics: warnings } : {}
+		};
+	};
+	const checkEdge = (action) => {
+		const { edgeType, sourceElementId: source, targetElementId: target } = action;
+		const model = s.getModel();
+		const meta = metaOf(model);
+		const answer = (check) => ({
+			kind: "checkEdgeTargetResult",
+			responseId: action.requestId,
+			isValid: check.ok,
+			edgeType,
+			sourceElementId: source,
+			...target === void 0 ? {} : { targetElementId: target },
+			...check.ok ? {} : {
+				reason: check.reason,
+				code: check.code
+			}
+		});
+		if (target !== void 0) {
+			const check = canLink(model, source, target, edgeType);
+			if (!check.ok && meta.links.get(edgeType)?.info.tryReversedWhenAdding) {
+				const reversed = canLink(model, target, source, edgeType);
+				if (reversed.ok) return answer(reversed);
+			}
+			return answer(check);
+		}
+		const element = model.elements.get(source);
+		if (!element) return answer({
+			ok: false,
+			code: "unknown-element",
+			reason: `unknown source element "${source}"`
+		});
+		const hint = typeHintsFor(meta).edgeHints.find((h) => h.elementTypeId === edgeType);
+		if (!hint) return answer({
+			ok: false,
+			code: "unknown-link-kind",
+			reason: `unknown link kind "${edgeType}"`
+		});
+		if (hint.sourceElementTypeIds && !hint.sourceElementTypeIds.includes(element.kind)) return answer({
+			ok: false,
+			code: "invalid-source",
+			reason: `a ${meta.elements.get(element.kind)?.label ?? element.kind} cannot be the source of a ${meta.links.get(edgeType)?.label ?? edgeType} link`
+		});
+		return answer({ ok: true });
+	};
+	const markers = (action) => {
+		const model = s.getModel();
+		const diagnostics = linkIssueDiagnostics(model);
+		if (options.schemas) for (const issue of validateModelProperties(model, options.schemas)) diagnostics.push({
+			elementId: issue.id,
+			key: issue.key,
+			severity: "error",
+			message: issue.message,
+			code: "invalid-property"
+		});
+		diagnostics.push(...options.diagnostics?.() ?? []);
+		const ids = action.elementsIDs.filter((id) => model.elements.has(id) || model.links.has(id));
+		const wanted = new Set(ids);
+		return {
+			kind: "setMarkers",
+			responseId: action.requestId,
+			markers: diagnostics.filter((d) => wanted.size === 0 || wanted.has(d.elementId)).map(diagnosticToMarker),
+			...action.reason === void 0 ? {} : { reason: action.reason }
+		};
+	};
+	const respond = (action) => {
+		const model = s.getModel();
+		switch (action.kind) {
+			case "requestModel": return {
+				kind: "setModel",
+				responseId: action.requestId,
+				newRoot: toPistarObject(model)
+			};
+			case "requestTypeHints": return {
+				kind: "setTypeHints",
+				responseId: action.requestId,
+				...typeHintsFor(metaOf(model))
+			};
+			case "requestCheckEdge": return checkEdge(action);
+			case "requestContextActions": return {
+				kind: "setContextActions",
+				responseId: action.requestId,
+				...contextActionsFor(palette, metaOf(model))
+			};
+			case "requestMarkers": return markers(action);
+			default: return;
+		}
+	};
+	const run = async (action) => {
+		if (isOperation(action)) return runOperation(action);
+		if (isRequestAction(action)) return {
+			ok: true,
+			createdIds: [],
+			response: respond(action)
+		};
+		switch (action.kind) {
+			case "glspUndo":
+				s.undo();
+				return {
+					ok: true,
+					createdIds: []
+				};
+			case "glspRedo":
+				s.redo();
+				return {
+					ok: true,
+					createdIds: []
+				};
+			case "saveModel": {
+				if (!options.save) reject("this host does not save models", "", "no-save-handler");
+				const model = s.getModel();
+				await options.save(toPistarObject(model, { saveDate: /* @__PURE__ */ new Date() }), action);
+				saved = model;
+				updateDirty("save");
+				return {
+					ok: true,
+					createdIds: []
+				};
+			}
+			case "sourceModelChanged":
+			case "setDirtyState":
+			case "triggerNodeCreation":
+			case "triggerEdgeCreation":
+			case "deleteMarkers":
+				emit(action);
+				return {
+					ok: true,
+					createdIds: []
+				};
+			default: return reject(`"${action.kind}" is not an action this dispatcher handles`, "", "unknown-action");
+		}
+	};
+	return {
+		async dispatch(action) {
+			try {
+				return await run(action);
+			} catch (error) {
+				if (error instanceof Rejection) return {
+					ok: false,
+					diagnostics: error.diagnostics
+				};
+				if (error instanceof ModelOperationError) return {
+					ok: false,
+					diagnostics: [error.toDiagnostic()]
+				};
+				throw error;
+			}
+		},
+		subscribe(listener) {
+			const l = listener;
+			listeners.add(l);
+			return () => listeners.delete(l);
+		},
+		isDirty: () => s.getModel() !== saved,
+		dispose: unsubscribe
+	};
+}
+//#endregion
+//#region src/host.ts
+/** `dispatcher`, refusing anything but requests: what a read-only host tool is handed. */
+function readOnlyDispatcher(dispatcher, tool) {
+	return {
+		dispatch: (action) => isRequestAction(action) ? dispatcher.dispatch(action) : Promise.resolve({
+			ok: false,
+			diagnostics: [{
+				elementId: "",
+				severity: "error",
+				code: "read-only-tool",
+				message: `"${tool}" is read-only: it cannot dispatch ${action.kind}`
+			}]
+		}),
+		subscribe: (listener) => dispatcher.subscribe(listener)
+	};
+}
+/** The context a call of `tool` gets: `dispatcher` as is, or read-only for a read-only tool. */
+function hostToolContext(tool, dispatcher, getModel, signal) {
+	return {
+		getModel,
+		dispatcher: tool.readOnly ? readOnlyDispatcher(dispatcher, tool.name) : dispatcher,
+		...signal ? { signal } : {}
+	};
+}
+/** A provider's text for `model`. */
+function contextText(provider, model) {
+	const { text } = provider;
+	return Promise.resolve(typeof text === "string" ? text : text(model));
+}
+//#endregion
+//#region src/mirror.ts
+/**
+* A mirror store: a read-only `ModelStore` in this process whose model follows a dispatcher that
+* lives elsewhere (a worker, a server, the other end of a `createRemoteDispatcher` port), so a
+* canvas and an inspector written against `ModelStore` can render it. Edits never touch the
+* mirror: they are dispatched to the remote, and come back as the remote's `sourceModelChanged`.
+*
+* How the model travels: an initial `requestModel`, then one update per `sourceModelChanged`.
+* A notification that carries the new model (`newRoot`, a dispatcher created with `sendModel`)
+* is applied as it arrives; one without it is answered with a `requestModel`, in order. Either
+* way the update is a whole piStar file, re-parsed (2 ms for the largest fixture, 237 ids), and
+* then shared with the previous model: an element, link or diagram equal to the one it replaces
+* keeps the old object, so whatever is memoised on identity only redoes what changed.
+*/
+/** Deep equality of JSON values (what parsed models are made of). */
+function equal(a, b) {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	const ka = Object.keys(a);
+	const kb = Object.keys(b);
+	if (ka.length !== kb.length) return false;
+	for (const key of ka) if (!equal(a[key], b[key])) return false;
+	return true;
+}
+/**
+* `next`, with every element, link and the diagram that equals `previous`'s kept as
+* `previous`'s object; `previous` itself when nothing differs (in content, order or metamodel).
+*/
+function share(previous, next) {
+	let same = previous.elements.size === next.elements.size && previous.links.size === next.links.size && metamodelOf(previous) === metamodelOf(next);
+	const shareMap = (from, to) => {
+		const order = from.keys();
+		const out = /* @__PURE__ */ new Map();
+		for (const [id, value] of to) {
+			const old = from.get(id);
+			const keep = old !== void 0 && equal(old, value);
+			if (!keep || order.next().value !== id) same = false;
+			out.set(id, keep ? old : value);
+		}
+		return out;
+	};
+	const elements = shareMap(previous.elements, next.elements);
+	const links = shareMap(previous.links, next.links);
+	const diagram = equal(previous.diagram, next.diagram) ? previous.diagram : next.diagram;
+	const { elements: _e, links: _l, diagram: _d, ...rest } = next;
+	const { elements: _pe, links: _pl, diagram: _pd, ...previousRest } = previous;
+	if (same && equal(rest, previousRest)) return previous;
+	const shared = {
+		...rest,
+		elements,
+		links,
+		...diagram === void 0 ? {} : { diagram }
+	};
+	return inheritMetamodel(next, inheritSourceLayout(next, shared));
+}
+function readOnly() {
+	throw new ModelOperationError("a mirror store is read-only: dispatch the edit through its remote dispatcher");
+}
+const parseWith = parsePistar;
+/**
+* A mirror of `remote`'s model (see `MirrorStore`). Shows an empty model until `ready`.
+*
+* Order: changes are shown in the order the remote sends them, whoever made them, and a
+* `dispatch` through `mirror.dispatcher` resolves after its change is shown, so code that
+* selects a created id or rolls back a rejected one sees the model it expects. A rejected
+* action sends no notification: the mirror stays as it was.
+*/
+function createMirrorStore(remote, options = {}) {
+	const r = remote;
+	const metamodel = options.metamodel;
+	const limit = options.historyLimit ?? 100;
+	const onError = options.onError ?? (() => {});
+	const listeners = /* @__PURE__ */ new Set();
+	let model = metamodel ? createEmptyModel(void 0, { metamodel }) : createEmptyModel();
+	/** The last file's `"metamodel"` block, as JSON; `undefined` before the first file. */
+	let block;
+	let undoDepth = 0;
+	let redoDepth = 0;
+	/** How many pushed models (`newRoot`) were applied: a response asked for before one is stale. */
+	let pushed = 0;
+	let requests = 0;
+	let tail = Promise.resolve();
+	let disposed = false;
+	const parse = (file) => {
+		const nextBlock = JSON.stringify(file[FILE_METAMODEL_KEY] ?? null);
+		if (nextBlock === block) return inheritMetamodel(model, parseWith(file, { metamodel: metamodelOf(model) }));
+		const parsed = parseWith(file, {
+			...metamodel ? { metamodel } : {},
+			...options.fileMetamodel ? { fileMetamodel: true } : {}
+		});
+		block = nextBlock;
+		return parsed;
+	};
+	const apply = (file, source, changes) => {
+		const previous = model;
+		const next = share(previous, parse(file));
+		if (next === previous) return;
+		model = next;
+		const event = {
+			model,
+			previous,
+			changes,
+			source
+		};
+		for (const listener of listeners) listener(event);
+	};
+	/** Counts the remote's undo stack from what it reports (see `MirrorStore`). */
+	const track = (source, exact) => {
+		if (exact) {
+			undoDepth = exact.canUndo ? 1 : 0;
+			redoDepth = exact.canRedo ? 1 : 0;
+		} else if (source === "edit") {
+			undoDepth = Math.min(undoDepth + 1, limit);
+			redoDepth = 0;
+		} else if (source === "undo") {
+			undoDepth = Math.max(undoDepth - 1, 0);
+			redoDepth++;
+		} else if (source === "redo") {
+			undoDepth = Math.min(undoDepth + 1, limit);
+			redoDepth = Math.max(redoDepth - 1, 0);
+		} else {
+			undoDepth = 0;
+			redoDepth = 0;
+		}
+	};
+	/**
+	* Asks for the model now (so the remote answers in order) and shows it once every earlier
+	* update is shown. Dropped if a pushed model arrived meanwhile: that one is at least as new.
+	*/
+	const refresh = (source, changes) => {
+		const seen = pushed;
+		const sent = r.dispatch({
+			kind: "requestModel",
+			requestId: `mirror-${++requests}`
+		}).then((result) => ({ result })).catch((error) => ({ error }));
+		const step = tail.then(async () => {
+			const answer = await sent;
+			if (disposed || pushed !== seen) return;
+			if ("error" in answer) throw answer.error;
+			const { result } = answer;
+			if (!result.ok) throw new Error(result.diagnostics[0]?.message ?? "requestModel was rejected");
+			if (!result.response) throw new Error("requestModel was answered without a model");
+			apply(result.response.newRoot, source, changes);
+		});
+		tail = step.catch(onError);
+		return step;
+	};
+	const unsubscribe = r.subscribe((action) => {
+		if (disposed || action.kind !== "sourceModelChanged") return;
+		track(action.source, action.canUndo !== void 0 && action.canRedo !== void 0 ? {
+			canUndo: action.canUndo,
+			canRedo: action.canRedo
+		} : void 0);
+		if (action.newRoot) {
+			pushed++;
+			try {
+				apply(action.newRoot, action.source, action.changes);
+			} catch (error) {
+				onError(error);
+			}
+		} else refresh(action.source, action.changes).catch(() => {});
+	});
+	const ready = refresh("load", []);
+	ready.catch(() => {});
+	const send = (kind) => {
+		r.dispatch({ kind }).catch(onError);
+	};
+	return {
+		ready,
+		dispatcher: {
+			async dispatch(action) {
+				const result = await r.dispatch(action);
+				await tail;
+				return result;
+			},
+			subscribe: (listener) => r.subscribe(listener)
+		},
+		synced: () => tail,
+		dispose() {
+			disposed = true;
+			unsubscribe();
+		},
+		getModel: () => model,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		canLink: (source, target, kind) => canLink(model, source, target, kind),
+		addElement: readOnly,
+		updateElement: readOnly,
+		moveElement: readOnly,
+		nestElement: readOnly,
+		removeElement: readOnly,
+		removeElements: readOnly,
+		setCollapsed: readOnly,
+		connect: readOnly,
+		addDependency: readOnly,
+		addLeg: readOnly,
+		removeLeg: readOnly,
+		updateLink: readOnly,
+		disconnect: readOnly,
+		updateDiagram: readOnly,
+		replace: readOnly,
+		load: readOnly,
+		transaction: readOnly,
+		clearHistory: readOnly,
+		undo() {
+			if (undoDepth === 0) return false;
+			send("glspUndo");
+			return true;
+		},
+		redo() {
+			if (redoDepth === 0) return false;
+			send("glspRedo");
+			return true;
+		},
+		canUndo: () => undoDepth > 0,
+		canRedo: () => redoDepth > 0
+	};
+}
+//#endregion
+//#region src/transport.ts
+const JSONRPC_VERSION = "2.0";
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isJsonRpcId(value) {
+	return typeof value === "string" || typeof value === "number";
+}
+function errorMessage(id, code, message) {
+	return {
+		jsonrpc: JSONRPC_VERSION,
+		id,
+		error: {
+			code,
+			message
+		}
+	};
+}
+/**
+* Serves `dispatcher` on `port`: every well-formed request is answered with the
+* `ActionResult` as `result`; `dispatcher.subscribe` events are pushed as notifications.
+* A malformed request answers `-32600` (invalid request) or `-32601` (no usable `method`); an
+* exception `dispatch` itself doesn't catch answers `-32603` (internal error). Returns a
+* disposer that stops forwarding subscriber events and detaches the port's `onmessage`.
+*/
+function connectDispatcher(port, dispatcher) {
+	const unsubscribe = dispatcher.subscribe((action) => {
+		port.postMessage({
+			jsonrpc: JSONRPC_VERSION,
+			method: action.kind,
+			params: action
+		});
+	});
+	port.onmessage = (ev) => {
+		const message = ev.data;
+		if (!isRecord(message) || message.jsonrpc !== JSONRPC_VERSION) return;
+		const { id, method, params } = message;
+		const hasId = isJsonRpcId(id);
+		if (typeof method !== "string" || method.length === 0) {
+			if (hasId) port.postMessage(errorMessage(id, -32601, "method not found"));
+			return;
+		}
+		if (!isRecord(params) || params.kind !== method) {
+			if (hasId) port.postMessage(errorMessage(id, -32600, "invalid request"));
+			return;
+		}
+		const action = params;
+		if (!hasId) {
+			dispatcher.dispatch(action);
+			return;
+		}
+		dispatcher.dispatch(action).then((result) => {
+			port.postMessage({
+				jsonrpc: JSONRPC_VERSION,
+				id,
+				result
+			});
+		}, (error) => {
+			const text = error instanceof Error ? error.message : "internal error";
+			port.postMessage(errorMessage(id, -32603, text));
+		});
+	};
+	return () => {
+		unsubscribe();
+		port.onmessage = null;
+	};
+}
+/**
+* The `ActionDispatcher` for the other end of a `connectDispatcher` port: `dispatch` sends a
+* request and resolves with the `ActionResult` it is answered with (a JSON-RPC `error` rejects
+* the promise instead — a transport fault, not an `ActionResult`); `subscribe` hears the
+* notifications the server pushes.
+*/
+function createRemoteDispatcher(port) {
+	let nextId = 0;
+	const pending = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	port.onmessage = (ev) => {
+		const message = ev.data;
+		if (!isRecord(message) || message.jsonrpc !== JSONRPC_VERSION) return;
+		const { id, method, params, result, error } = message;
+		if (isJsonRpcId(id)) {
+			const waiting = pending.get(id);
+			if (!waiting) return;
+			pending.delete(id);
+			if (isRecord(error)) waiting.reject(/* @__PURE__ */ new Error(`JSON-RPC error ${String(error.code)}: ${String(error.message)}`));
+			else waiting.resolve(result);
+			return;
+		}
+		if (typeof method === "string" && isRecord(params)) {
+			const action = params;
+			for (const listener of listeners) listener(action);
+		}
+	};
+	return {
+		dispatch(action) {
+			const id = nextId++;
+			return new Promise((resolve, reject) => {
+				pending.set(id, {
+					resolve,
+					reject
+				});
+				port.postMessage({
+					jsonrpc: JSONRPC_VERSION,
+					id,
+					method: action.kind,
+					params: action
+				});
+			});
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/** Version of the action protocol this package speaks. */
+const ACTIONS_PROTOCOL_VERSION = "0.0.0";
+//#endregion
+export { ACTIONS_PROTOCOL_VERSION, HANDLED_ACTION_KINDS, connectDispatcher, contextActionsFor, contextText, createActionDispatcher, createMirrorStore, createRemoteDispatcher, diagnosticToMarker, hostToolContext, isOperation, isRequestAction, markerToDiagnostic, readOnlyDispatcher, typeHintsFor };
+
+//# sourceMappingURL=index.js.map