@istar-ts/actions 0.15.0-beta.1 → 0.15.0-beta.3

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AnyIstarModel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, FileMetamodel, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
+import { AnyIstarModel, AnyMetamodel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, FileMetamodel, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
 //#region src/actions.d.ts
 /** GLSP's custom arguments: a flat map of primitives. */
 export type Args = Readonly<Record<string, string | number | boolean>>;
@@ -281,6 +281,11 @@ export interface ModelSourceChangedAction extends Action {
    * created with `sendModel`). An iStar extra; a mirror uses this to know the exact state.
    */
   readonly canRedo?: boolean;
+  /**
+   * The `origin` the causing `dispatch` was given, echoed back; absent for a change with none
+   * (a host's direct `store.load`, for instance). See `ActionDispatcher.dispatch`.
+   */
+  readonly origin?: string;
 }
 /** Saves the model through the host's `save` callback. */
 export interface SaveModelAction extends Action {
@@ -293,6 +298,8 @@ export interface SetDirtyStateAction extends Action {
   readonly kind: "setDirtyState";
   readonly isDirty: boolean;
   readonly reason?: DirtyStateChangeReason;
+  /** The `origin` of the dispatch that caused this dirty-state change, echoed back; see `ModelSourceChangedAction.origin`. */
+  readonly origin?: string;
 }
 export interface UndoAction extends Action {
   readonly kind: "glspUndo";
@@ -489,8 +496,31 @@ export type ActionListener<EK extends string = ElementKind, LK extends string =
  * Sends actions and hears what the other side sends back. Implemented in-process by
  * `createActionDispatcher`; a transport implements it over a message port.
  */
+/** `dispatch`'s second argument. */
+export interface DispatchOptions {
+  /**
+   * Echoed back as `origin` on every `ModelSourceChangedAction` and `SetDirtyStateAction` this
+   * dispatch causes (each change of a compound, both events of an undo or redo), so a listener
+   * can tell which surface or client made a change without tracking it itself. Carried through
+   * `createRemoteDispatcher`/`connectDispatcher` and by `createMirrorStore`'s dispatcher, so it
+   * survives a round trip to a remote host. Optional: a change with no origin (a host's direct
+   * `store.load`, for instance) has none.
+   */
+  readonly origin?: string;
+}
 export interface ActionDispatcher<EK extends string = ElementKind, LK extends string = LinkKind> {
-  dispatch<A extends IstarAction<EK, LK>>(action: A): Promise<ActionResult<ResponseFor<A>>>;
+  /**
+   * For a **local** dispatcher (`createActionDispatcher`), an operation, `glspUndo`/`glspRedo`,
+   * and the guards and postGuards around them, are applied to the store and every listener
+   * (`subscribe`, the store's own) is notified synchronously, before this call's promise is
+   * created to resolve — only `saveModel` awaits. Code that needs to see the result of an action
+   * before its own next statement (not just before `await dispatch(...)` resolves) can rely on
+   * this for a local dispatcher; it does **not** hold across a `createRemoteDispatcher`/
+   * `connectDispatcher` transport or a `createMirrorStore` mirror, where a change always arrives
+   * after a message round trip. Use `origin` ({@link DispatchOptions}) instead where that
+   * portability matters — it is carried through both.
+   */
+  dispatch<A extends IstarAction<EK, LK>>(action: A, options?: DispatchOptions): Promise<ActionResult<ResponseFor<A>>>;
   /**
    * Hears the actions the dispatcher sends: `ModelSourceChangedAction` after every model change,
    * `SetDirtyStateAction` when the dirty state flips, and the notifications dispatched to it.
@@ -518,8 +548,14 @@ export interface ActionDispatcherOptions<EK extends string = ElementKind, LK ext
   readonly guards?: readonly ActionGuard<EK, LK>[];
   /** Run after each operation is applied; see `ActionPostGuard`. */
   readonly postGuards?: readonly ActionPostGuard<EK, LK>[];
-  /** What `RequestContextActions` offers. Default: `DEFAULT_PALETTE` (iStar 2.0's). */
-  readonly palette?: AnyPaletteDescription;
+  /**
+   * What `RequestContextActions` offers: a fixed description, or a function evaluated on each
+   * request (so a host can track a registry or extensions that change after this dispatcher was
+   * created — a plain `AnyPaletteDescription` is read once, at creation). Default: derived from
+   * the model's current metamodel (`paletteFromMetamodel`), the same fallback `contributionFor`
+   * (`@istar-ts/glsp`) uses — not iStar 2.0's palette regardless of dialect.
+   */
+  readonly palette?: AnyPaletteDescription | (() => AnyPaletteDescription);
   /**
    * Property schemas an operation must not break: an operation that adds an issue
    * (`validateModelProperties`) is rejected. Their issues are also markers.
@@ -566,6 +602,15 @@ export declare function typeHintsFor<EK extends string, LK extends string>(metam
  * lacks are left out.
  */
 export declare function contextActionsFor<EK extends string, LK extends string>(palette: AnyPaletteDescription, metamodel: Metamodel<EK, LK>): Pick<SetContextActions, "actions" | "groups">;
+/**
+ * A minimal palette for a metamodel with none of its own: one toolbar entry per visible kind
+ * (declaration order, actors first), labelled from the kind's own `label`. Kinds generated for
+ * an n-ary link (a hub, leg or end — `role` set) are hidden, as a hand-written palette would
+ * hide them (`KAOS_PALETTE`'s `RefinementLinkHub: false`, for instance). The fallback
+ * `createActionDispatcher` and `contributionFor` (`@istar-ts/glsp`) both use when no palette
+ * was given.
+ */
+export declare function paletteFromMetamodel(metamodel: AnyMetamodel): AnyPaletteDescription;
 //#endregion
 //#region src/host.d.ts
 /** A host's knowledge for the model: a system-prompt section and/or an MCP resource. */
@@ -709,6 +754,8 @@ export interface JsonRpcRequest {
   readonly id: JsonRpcId;
   readonly method: string;
   readonly params?: unknown;
+  /** The dispatch's `origin` (`DispatchOptions.origin`), carried to the server's `dispatch`. */
+  readonly origin?: string;
 }
 /** A subscriber event, sent with no `id`: it expects no response. */
 export interface JsonRpcNotification {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AnyIstarModel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, FileMetamodel, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
+import { AnyIstarModel, AnyMetamodel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, FileMetamodel, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
 //#region src/actions.d.ts
 /** GLSP's custom arguments: a flat map of primitives. */
 export type Args = Readonly<Record<string, string | number | boolean>>;
@@ -281,6 +281,11 @@ export interface ModelSourceChangedAction extends Action {
    * created with `sendModel`). An iStar extra; a mirror uses this to know the exact state.
    */
   readonly canRedo?: boolean;
+  /**
+   * The `origin` the causing `dispatch` was given, echoed back; absent for a change with none
+   * (a host's direct `store.load`, for instance). See `ActionDispatcher.dispatch`.
+   */
+  readonly origin?: string;
 }
 /** Saves the model through the host's `save` callback. */
 export interface SaveModelAction extends Action {
@@ -293,6 +298,8 @@ export interface SetDirtyStateAction extends Action {
   readonly kind: "setDirtyState";
   readonly isDirty: boolean;
   readonly reason?: DirtyStateChangeReason;
+  /** The `origin` of the dispatch that caused this dirty-state change, echoed back; see `ModelSourceChangedAction.origin`. */
+  readonly origin?: string;
 }
 export interface UndoAction extends Action {
   readonly kind: "glspUndo";
@@ -489,8 +496,31 @@ export type ActionListener<EK extends string = ElementKind, LK extends string =
  * Sends actions and hears what the other side sends back. Implemented in-process by
  * `createActionDispatcher`; a transport implements it over a message port.
  */
+/** `dispatch`'s second argument. */
+export interface DispatchOptions {
+  /**
+   * Echoed back as `origin` on every `ModelSourceChangedAction` and `SetDirtyStateAction` this
+   * dispatch causes (each change of a compound, both events of an undo or redo), so a listener
+   * can tell which surface or client made a change without tracking it itself. Carried through
+   * `createRemoteDispatcher`/`connectDispatcher` and by `createMirrorStore`'s dispatcher, so it
+   * survives a round trip to a remote host. Optional: a change with no origin (a host's direct
+   * `store.load`, for instance) has none.
+   */
+  readonly origin?: string;
+}
 export interface ActionDispatcher<EK extends string = ElementKind, LK extends string = LinkKind> {
-  dispatch<A extends IstarAction<EK, LK>>(action: A): Promise<ActionResult<ResponseFor<A>>>;
+  /**
+   * For a **local** dispatcher (`createActionDispatcher`), an operation, `glspUndo`/`glspRedo`,
+   * and the guards and postGuards around them, are applied to the store and every listener
+   * (`subscribe`, the store's own) is notified synchronously, before this call's promise is
+   * created to resolve — only `saveModel` awaits. Code that needs to see the result of an action
+   * before its own next statement (not just before `await dispatch(...)` resolves) can rely on
+   * this for a local dispatcher; it does **not** hold across a `createRemoteDispatcher`/
+   * `connectDispatcher` transport or a `createMirrorStore` mirror, where a change always arrives
+   * after a message round trip. Use `origin` ({@link DispatchOptions}) instead where that
+   * portability matters — it is carried through both.
+   */
+  dispatch<A extends IstarAction<EK, LK>>(action: A, options?: DispatchOptions): Promise<ActionResult<ResponseFor<A>>>;
   /**
    * Hears the actions the dispatcher sends: `ModelSourceChangedAction` after every model change,
    * `SetDirtyStateAction` when the dirty state flips, and the notifications dispatched to it.
@@ -518,8 +548,14 @@ export interface ActionDispatcherOptions<EK extends string = ElementKind, LK ext
   readonly guards?: readonly ActionGuard<EK, LK>[];
   /** Run after each operation is applied; see `ActionPostGuard`. */
   readonly postGuards?: readonly ActionPostGuard<EK, LK>[];
-  /** What `RequestContextActions` offers. Default: `DEFAULT_PALETTE` (iStar 2.0's). */
-  readonly palette?: AnyPaletteDescription;
+  /**
+   * What `RequestContextActions` offers: a fixed description, or a function evaluated on each
+   * request (so a host can track a registry or extensions that change after this dispatcher was
+   * created — a plain `AnyPaletteDescription` is read once, at creation). Default: derived from
+   * the model's current metamodel (`paletteFromMetamodel`), the same fallback `contributionFor`
+   * (`@istar-ts/glsp`) uses — not iStar 2.0's palette regardless of dialect.
+   */
+  readonly palette?: AnyPaletteDescription | (() => AnyPaletteDescription);
   /**
    * Property schemas an operation must not break: an operation that adds an issue
    * (`validateModelProperties`) is rejected. Their issues are also markers.
@@ -566,6 +602,15 @@ export declare function typeHintsFor<EK extends string, LK extends string>(metam
  * lacks are left out.
  */
 export declare function contextActionsFor<EK extends string, LK extends string>(palette: AnyPaletteDescription, metamodel: Metamodel<EK, LK>): Pick<SetContextActions, "actions" | "groups">;
+/**
+ * A minimal palette for a metamodel with none of its own: one toolbar entry per visible kind
+ * (declaration order, actors first), labelled from the kind's own `label`. Kinds generated for
+ * an n-ary link (a hub, leg or end — `role` set) are hidden, as a hand-written palette would
+ * hide them (`KAOS_PALETTE`'s `RefinementLinkHub: false`, for instance). The fallback
+ * `createActionDispatcher` and `contributionFor` (`@istar-ts/glsp`) both use when no palette
+ * was given.
+ */
+export declare function paletteFromMetamodel(metamodel: AnyMetamodel): AnyPaletteDescription;
 //#endregion
 //#region src/host.d.ts
 /** A host's knowledge for the model: a system-prompt section and/or an MCP resource. */
@@ -709,6 +754,8 @@ export interface JsonRpcRequest {
   readonly id: JsonRpcId;
   readonly method: string;
   readonly params?: unknown;
+  /** The dispatch's `origin` (`DispatchOptions.origin`), carried to the server's `dispatch`. */
+  readonly origin?: string;
 }
 /** A subscriber event, sent with no `id`: it expects no response. */
 export interface JsonRpcNotification {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_PALETTE, DIAGNOSTIC_SEVERITIES, FILE_METAMODEL_KEY, LINK_SELECTOR, MetamodelError, ModelOperationError, canLink, connectResultToDiagnostic, createEmptyModel, dependencyEnds, effectiveLinkKind, elementBehavesLike, inheritMetamodel, inheritSourceLayout, linkBehavesLike, metamodelOf, parsePistar, toPistarObject, validateModel, validateModelProperties, withFileMetamodel } from "@istar-ts/core";
+import { DIAGNOSTIC_SEVERITIES, FILE_METAMODEL_KEY, LINK_SELECTOR, MetamodelError, ModelOperationError, canLink, connectResultToDiagnostic, createEmptyModel, dependencyEnds, effectiveLinkKind, elementBehavesLike, inheritMetamodel, inheritSourceLayout, linkBehavesLike, metamodelOf, parsePistar, toPistarObject, validateModel, validateModelProperties, withFileMetamodel } from "@istar-ts/core";
 //#region src/actions.ts
 const OPERATION_KIND_LIST = [
 	"createNode",
@@ -185,6 +185,36 @@ function contextActionsFor(palette, metamodel) {
 		groups: palette.groups
 	};
 }
+/**
+* A minimal palette for a metamodel with none of its own: one toolbar entry per visible kind
+* (declaration order, actors first), labelled from the kind's own `label`. Kinds generated for
+* an n-ary link (a hub, leg or end — `role` set) are hidden, as a hand-written palette would
+* hide them (`KAOS_PALETTE`'s `RefinementLinkHub: false`, for instance). The fallback
+* `createActionDispatcher` and `contributionFor` (`@istar-ts/glsp`) both use when no palette
+* was given.
+*/
+function paletteFromMetamodel(metamodel) {
+	const elements = {};
+	let order = 0;
+	for (const definition of metamodel.elements.values()) elements[definition.kind] = definition.role !== void 0 ? false : {
+		label: definition.label,
+		order: order++,
+		section: definition.category === "actor" ? "actors" : "elements",
+		...definition.category === "actor" ? { group: "actors" } : {}
+	};
+	const links = {};
+	order = 0;
+	for (const definition of metamodel.links.values()) links[definition.kind] = definition.role !== void 0 ? false : [{
+		label: definition.label,
+		order: order++,
+		section: "elements"
+	}];
+	return {
+		elements,
+		links,
+		groups: { actors: { label: "Actor" } }
+	};
+}
 //#endregion
 //#region src/markers.ts
 /** A `GoalDiagnostic` as a GLSP marker: `kind` is its severity, `label` its message. */
@@ -276,22 +306,34 @@ function createActionDispatcher(store, options = {}) {
 	const s = store;
 	const guards = options.guards ?? [];
 	const postGuards = options.postGuards ?? [];
-	const palette = options.palette ?? DEFAULT_PALETTE;
+	const resolvePalette = (meta) => {
+		const option = options.palette;
+		if (typeof option === "function") return option();
+		return option ?? paletteFromMetamodel(meta);
+	};
 	const sourceModelName = options.sourceModelName ?? "";
 	const listeners = /* @__PURE__ */ new Set();
 	let saved = s.getModel();
 	let dirty = false;
+	/**
+	* The origin of the dispatch currently applying synchronously (set by `dispatch`, around the
+	* synchronous part of `run`): what the store's subscription below echoes on
+	* `sourceModelChanged`/`setDirtyState`. `undefined` for a change not caused by a dispatch (a
+	* host's direct `store.load`) or once `run`'s synchronous part has returned.
+	*/
+	let currentOrigin;
 	const emit = (action) => {
 		for (const listener of listeners) listener(action);
 	};
-	const updateDirty = (reason) => {
+	const updateDirty = (reason, origin) => {
 		const next = s.getModel() !== saved;
 		if (next === dirty) return;
 		dirty = next;
 		emit({
 			kind: "setDirtyState",
 			isDirty: next,
-			reason
+			reason,
+			...origin === void 0 ? {} : { origin }
 		});
 	};
 	const REASONS = {
@@ -311,9 +353,10 @@ function createActionDispatcher(store, options = {}) {
 			...options.sendModel ? {
 				canUndo: s.canUndo(),
 				canRedo: s.canRedo()
-			} : {}
+			} : {},
+			...currentOrigin === void 0 ? {} : { origin: currentOrigin }
 		});
-		updateDirty(REASONS[event.source]);
+		updateDirty(REASONS[event.source], currentOrigin);
 	});
 	const requireElement = (id) => s.getModel().elements.get(id) ?? reject(`unknown element "${id}"`, id, "unknown-element");
 	const runGuards = (operation, warnings) => {
@@ -698,16 +741,19 @@ function createActionDispatcher(store, options = {}) {
 				...typeHintsFor(metaOf(model))
 			};
 			case "requestCheckEdge": return checkEdge(action);
-			case "requestContextActions": return {
-				kind: "setContextActions",
-				responseId: action.requestId,
-				...contextActionsFor(palette, metaOf(model))
-			};
+			case "requestContextActions": {
+				const meta = metaOf(model);
+				return {
+					kind: "setContextActions",
+					responseId: action.requestId,
+					...contextActionsFor(resolvePalette(meta), meta)
+				};
+			}
 			case "requestMarkers": return markers(action);
 			default: return;
 		}
 	};
-	const run = async (action) => {
+	const run = async (action, origin) => {
 		if (isOperation(action)) return runOperation(action);
 		if (isRequestAction(action)) return {
 			ok: true,
@@ -732,7 +778,7 @@ function createActionDispatcher(store, options = {}) {
 				const model = s.getModel();
 				await options.save(toPistarObject(model, { saveDate: /* @__PURE__ */ new Date() }), action);
 				saved = model;
-				updateDirty("save");
+				updateDirty("save", origin);
 				return {
 					ok: true,
 					createdIds: []
@@ -752,9 +798,17 @@ function createActionDispatcher(store, options = {}) {
 		}
 	};
 	return {
-		async dispatch(action) {
+		async dispatch(action, dispatchOptions) {
+			const origin = dispatchOptions?.origin;
+			currentOrigin = origin;
+			let pending;
+			try {
+				pending = run(action, origin);
+			} finally {
+				currentOrigin = void 0;
+			}
 			try {
-				return await run(action);
+				return await pending;
 			} catch (error) {
 				if (error instanceof Rejection) return {
 					ok: false,
@@ -978,8 +1032,8 @@ function createMirrorStore(remote, options = {}) {
 	return {
 		ready,
 		dispatcher: {
-			async dispatch(action) {
-				const result = await r.dispatch(action);
+			async dispatch(action, options) {
+				const result = await r.dispatch(action, options);
 				await tail;
 				return result;
 			},
@@ -1065,8 +1119,9 @@ function connectDispatcher(port, dispatcher) {
 	port.onmessage = (ev) => {
 		const message = ev.data;
 		if (!isRecord(message) || message.jsonrpc !== JSONRPC_VERSION) return;
-		const { id, method, params } = message;
+		const { id, method, params, origin } = message;
 		const hasId = isJsonRpcId(id);
+		const dispatchOptions = typeof origin === "string" ? { origin } : void 0;
 		if (typeof method !== "string" || method.length === 0) {
 			if (hasId) port.postMessage(errorMessage(id, -32601, "method not found"));
 			return;
@@ -1077,10 +1132,10 @@ function connectDispatcher(port, dispatcher) {
 		}
 		const action = params;
 		if (!hasId) {
-			dispatcher.dispatch(action);
+			dispatcher.dispatch(action, dispatchOptions);
 			return;
 		}
-		dispatcher.dispatch(action).then((result) => {
+		dispatcher.dispatch(action, dispatchOptions).then((result) => {
 			port.postMessage({
 				jsonrpc: JSONRPC_VERSION,
 				id,
@@ -1124,7 +1179,7 @@ function createRemoteDispatcher(port) {
 		}
 	};
 	return {
-		dispatch(action) {
+		dispatch(action, dispatchOptions) {
 			const id = nextId++;
 			return new Promise((resolve, reject) => {
 				pending.set(id, {
@@ -1135,7 +1190,8 @@ function createRemoteDispatcher(port) {
 					jsonrpc: JSONRPC_VERSION,
 					id,
 					method: action.kind,
-					params: action
+					params: action,
+					...dispatchOptions?.origin === void 0 ? {} : { origin: dispatchOptions.origin }
 				});
 			});
 		},
@@ -1150,6 +1206,6 @@ function createRemoteDispatcher(port) {
 /** 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 };
+export { ACTIONS_PROTOCOL_VERSION, HANDLED_ACTION_KINDS, connectDispatcher, contextActionsFor, contextText, createActionDispatcher, createMirrorStore, createRemoteDispatcher, diagnosticToMarker, hostToolContext, isOperation, isRequestAction, markerToDiagnostic, paletteFromMetamodel, readOnlyDispatcher, typeHintsFor };
 
 //# sourceMappingURL=index.js.map