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

package/dist/index.d.cts

@@ -0,0 +1,741 @@
+import { AnyIstarModel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, 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>>;
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+export interface Dimension {
+  readonly width: number;
+  readonly height: number;
+}
+export interface Action {
+  readonly kind: string;
+}
+export interface RequestAction extends Action {
+  readonly requestId: string;
+  /** Milliseconds the sender is willing to wait (GLSP); the in-process dispatcher ignores it. */
+  readonly timeout?: number;
+}
+export interface ResponseAction extends Action {
+  /** The `requestId` of the request this answers. */
+  readonly responseId: string;
+}
+/** An action that edits the model, as one undo step. */
+export interface Operation extends Action {
+  /** GLSP's operation marker. Optional here: the dispatcher knows operations by `kind`. */
+  readonly isOperation?: true;
+}
+export interface CreateNodeArgs {
+  /** Default: the kind's label ("Goal"), as in piStar. */
+  readonly name?: string;
+  readonly customProperties?: CustomProperties;
+  /** The new element's id. Default: a fresh UUID. Lets a compound operation refer to it. */
+  readonly id?: string;
+}
+export interface CreateNodeOperation<EK extends string = ElementKind> extends Operation {
+  readonly kind: "createNode";
+  /** The element kind, e.g. `istar.Goal`. */
+  readonly elementTypeId: EK;
+  /** Default: the container's position, or the origin. */
+  readonly location?: Point;
+  /** The actor to create the element in. */
+  readonly containerId?: string;
+  readonly args?: CreateNodeArgs;
+}
+/** The dependum a dependency creates between its depender and dependee. */
+export interface DependumArgs<EK extends string = ElementKind> {
+  /** Default: the metamodel's first node kind that can be a dependum. */
+  readonly kind?: EK;
+  readonly name?: string;
+  readonly id?: string;
+  /** Default: midway between depender and dependee, as in piStar. */
+  readonly location?: Point;
+  readonly customProperties?: CustomProperties;
+}
+export interface CreateEdgeArgs<EK extends string = ElementKind> {
+  /** A contribution's value (the link's `label`), e.g. `help`. */
+  readonly value?: string;
+  readonly name?: string;
+  readonly customProperties?: CustomProperties;
+  /**
+   * The new link's id: for an n-ary kind whose target is not yet a hub, the new hub's; for an
+   * n-ary kind whose target already is a hub, the new leg's (same as `legId` there). Default: a
+   * fresh UUID.
+   */
+  readonly id?: string;
+  /** For a dependency kind: the dependum to create. */
+  readonly dependum?: DependumArgs<EK>;
+  /** For a dependency kind: the ids of its two links. */
+  readonly linkIds?: readonly [string, string];
+  /**
+   * The id of the leg it creates: for a target that is not yet a hub, the new leg from source;
+   * for a target that already is a hub, the new leg instead of `id`.
+   */
+  readonly legId?: string;
+  /** For an n-ary kind whose target is not yet a hub: the id of the end it creates. */
+  readonly endId?: string;
+}
+/**
+ * Adds a link. With a dependency kind, adds the dependum and its two links (as `addDependency`
+ * does), source being the depender and target the dependee. With an n-ary kind, adds a leg when
+ * the target is one of the kind's hubs, else a new hub with a leg and an end.
+ */
+export interface CreateEdgeOperation<EK extends string = ElementKind, LK extends string = LinkKind> extends Operation {
+  readonly kind: "createEdge";
+  /** The link kind, e.g. `istar.ContributionLink`. */
+  readonly elementTypeId: LK;
+  readonly sourceElementId: string;
+  readonly targetElementId: string;
+  readonly args?: CreateEdgeArgs<EK>;
+}
+/** Removes elements and links, with everything that depends on them (as the store does). */
+export interface DeleteElementOperation extends Operation {
+  readonly kind: "deleteElement";
+  /** Element and link ids. */
+  readonly elementIds: readonly string[];
+}
+export interface ElementAndBounds {
+  readonly elementId: string;
+  /** Moving an actor moves its inner elements with it. */
+  readonly newPosition?: Point;
+  /** Written to the element's `display` (`width`, `height`). */
+  readonly newSize?: Dimension;
+}
+export interface ChangeBoundsOperation extends Operation {
+  readonly kind: "changeBounds";
+  readonly newBounds: readonly ElementAndBounds[];
+}
+/** Moves an inner element into another actor, or out of any actor with `null` (`nestElement`). */
+export interface ChangeContainerOperation extends Operation {
+  readonly kind: "changeContainer";
+  readonly elementId: string;
+  readonly targetContainerId: string | null;
+  /** The element's new position, if it moves too. */
+  readonly location?: Point;
+}
+/**
+ * Gives a link new ends, keeping its id, kind and properties. A dependency's link keeps its
+ * dependum end; an n-ary link's leg keeps its hub (or moves to another hub of the kind), its end
+ * keeps the hub.
+ */
+export interface ReconnectEdgeOperation extends Operation {
+  readonly kind: "reconnectEdge";
+  readonly edgeElementId: string;
+  readonly sourceElementId: string;
+  readonly targetElementId: string;
+  readonly args?: Args;
+}
+/**
+ * Sets an element's or link's name (`labelId` = its id), or one of its custom properties
+ * (`labelId` = `"<id>#<key>"`). An element's name is written as-is (`text`, including `""`, as
+ * piStar always keeps the key); a link's name is removed from the file when `text` is `""`, as
+ * piStar does for a link whose name was cleared (`fileManager.js` only writes `name` when it is
+ * truthy).
+ */
+export interface ApplyLabelEditOperation extends Operation {
+  readonly kind: "applyLabelEdit";
+  readonly labelId: string;
+  readonly text: string;
+}
+/** Applies its operations in order, as one undo step; if one is rejected, none is applied. */
+export interface CompoundOperation<EK extends string = ElementKind, LK extends string = LinkKind> extends Operation {
+  readonly kind: "compound";
+  readonly operationList: readonly IstarOperation<EK, LK>[];
+}
+/** Adds a leg from `sourceElementId` to the hub of an n-ary link (`store.addLeg`). */
+export interface AddLegOperation extends Operation {
+  readonly kind: "istar.addLeg";
+  readonly hubId: string;
+  readonly sourceElementId: string;
+  readonly args?: {
+    readonly id?: string;
+  };
+}
+/** Removes a leg of an n-ary link; the last one takes the hub and end with it. */
+export interface RemoveLegOperation extends Operation {
+  readonly kind: "istar.removeLeg";
+  readonly legId: string;
+}
+export interface SetCollapsedOperation extends Operation {
+  readonly kind: "istar.setCollapsed";
+  /** An actor. */
+  readonly elementId: string;
+  readonly collapsed: boolean;
+}
+export interface DiagramPatch {
+  readonly name?: string;
+  readonly width?: number;
+  readonly height?: number;
+  /** Replaces the diagram's custom properties. */
+  readonly customProperties?: CustomProperties;
+}
+export interface UpdateDiagramOperation extends Operation {
+  readonly kind: "istar.updateDiagram";
+  readonly diagram: DiagramPatch;
+}
+/**
+ * Sets custom properties of an element or link: each key is set to its value, or removed when
+ * the value is `null`; other keys are kept. Values are strings, as piStar stores them.
+ */
+export interface UpdatePropertiesOperation extends Operation {
+  readonly kind: "istar.updateProperties";
+  /** An element or link id. */
+  readonly elementId: string;
+  readonly properties: Readonly<Record<string, string | null>>;
+}
+/**
+ * Merges into an element's `display` (colour, the auto-grown height from a label fit): a key set
+ * to `undefined` is removed, the rest is written as-is. Same semantics as `ElementPatch.display`
+ * (`@istar-ts/core`), which this forwards to.
+ */
+export interface UpdateDisplayOperation extends Operation {
+  readonly kind: "istar.updateDisplay";
+  readonly elementId: string;
+  readonly patch: Readonly<Record<string, unknown>>;
+}
+/**
+ * Sets an existing link's contribution value (`label` in the save file), e.g. a Contribution
+ * link's make/help/hurt/break. `null` clears it. Rejected when the link's kind has no
+ * `possibleLabels`, or `value` is not one of them (as `createEdge.args.value` is checked at
+ * creation).
+ */
+export interface SetLinkValueOperation extends Operation {
+  readonly kind: "istar.setLinkValue";
+  readonly linkId: string;
+  readonly value: string | null;
+}
+/**
+ * Merges into a link's `display` (its bend points, `vertices`): a key set to `undefined` is
+ * removed, the rest is written as-is. Same semantics as `LinkPatch.display` (`@istar-ts/core`),
+ * which this forwards to. GLSP's counterpart is `changeRoutingPoints`.
+ */
+export interface UpdateLinkDisplayOperation extends Operation {
+  readonly kind: "istar.updateLinkDisplay";
+  readonly linkId: string;
+  readonly patch: Readonly<Record<string, unknown>>;
+}
+/** Every operation, keyed by `kind`. */
+export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation;
+export interface RequestModelAction extends RequestAction {
+  readonly kind: "requestModel";
+  readonly options?: Args;
+}
+export interface SetModelAction extends ResponseAction {
+  readonly kind: "setModel";
+  /** The model as a piStar save file (`toPistarObject`). */
+  readonly newRoot: PistarFile;
+}
+/**
+ * The model changed: sent to subscribers after every edit, undo, redo or load, whoever caused
+ * it. `source` and `changes` are iStar extras (the store's `ModelChangeEvent`).
+ */
+export interface ModelSourceChangedAction extends Action {
+  readonly kind: "sourceModelChanged";
+  /** The dispatcher's `sourceModelName` option. */
+  readonly sourceModelName: string;
+  readonly source: "edit" | "undo" | "redo" | "load";
+  /** What an edit did; empty for undo, redo and load. */
+  readonly changes: readonly ModelChange[];
+  /**
+   * The new model as a piStar save file (`toPistarObject`), when the dispatcher was created with
+   * `sendModel`: what a mirror (`createMirrorStore`) follows without asking for it. An iStar
+   * extra.
+   */
+  readonly newRoot?: PistarFile;
+  /**
+   * Whether undo is possible, from the remote store after this change (when the dispatcher was
+   * created with `sendModel`). An iStar extra; a mirror uses this to know the exact state.
+   */
+  readonly canUndo?: boolean;
+  /**
+   * Whether redo is possible, from the remote store after this change (when the dispatcher was
+   * created with `sendModel`). An iStar extra; a mirror uses this to know the exact state.
+   */
+  readonly canRedo?: boolean;
+}
+/** Saves the model through the host's `save` callback. */
+export interface SaveModelAction extends Action {
+  readonly kind: "saveModel";
+  readonly fileUri?: string;
+}
+export type DirtyStateChangeReason = "operation" | "undo" | "redo" | "save" | "external";
+/** Sent to subscribers when the model starts or stops differing from the last saved one. */
+export interface SetDirtyStateAction extends Action {
+  readonly kind: "setDirtyState";
+  readonly isDirty: boolean;
+  readonly reason?: DirtyStateChangeReason;
+}
+export interface UndoAction extends Action {
+  readonly kind: "glspUndo";
+}
+export interface RedoAction extends Action {
+  readonly kind: "glspRedo";
+}
+export interface TypeHint {
+  readonly elementTypeId: string;
+  readonly repositionable: boolean;
+  readonly deletable: boolean;
+}
+export interface ShapeTypeHint extends TypeHint {
+  readonly resizable: boolean;
+  /** Can move into or out of an actor. */
+  readonly reparentable: boolean;
+  /** For an actor: the node kinds it can contain. */
+  readonly containableElementTypeIds?: readonly string[];
+}
+export interface EdgeTypeHint extends TypeHint {
+  readonly routable: boolean;
+  /** Element kinds that may be the source; absent when any may. */
+  readonly sourceElementTypeIds?: readonly string[];
+  /** Element kinds that may be the target; absent when any may. */
+  readonly targetElementTypeIds?: readonly string[];
+  /** Always true for iStar: kinds alone don't decide (same actor, uniqueness…); ask `requestCheckEdge`. */
+  readonly dynamic?: boolean;
+}
+export interface RequestTypeHintsAction extends RequestAction {
+  readonly kind: "requestTypeHints";
+}
+export interface SetTypeHintsAction extends ResponseAction {
+  readonly kind: "setTypeHints";
+  readonly shapeHints: readonly ShapeTypeHint[];
+  readonly edgeHints: readonly EdgeTypeHint[];
+}
+/** Would a link of `edgeType` from source to target be accepted (`canLink`)? */
+export interface RequestCheckEdgeAction extends RequestAction {
+  readonly kind: "requestCheckEdge";
+  readonly edgeType: string;
+  readonly sourceElementId: string;
+  /** Absent: is the source an acceptable source at all? */
+  readonly targetElementId?: string;
+}
+export interface CheckEdgeResultAction extends ResponseAction {
+  readonly kind: "checkEdgeTargetResult";
+  readonly isValid: boolean;
+  readonly edgeType: string;
+  readonly sourceElementId: string;
+  readonly targetElementId?: string;
+  /** iStar extra: why not, when `isValid` is false. */
+  readonly reason?: string;
+  /** iStar extra: the constraint that failed (`ConstraintCode`). */
+  readonly code?: string;
+}
+export interface EditorContext {
+  readonly selectedElementIds: readonly string[];
+  /** Where the user is about to create something, in model coordinates. */
+  readonly lastMousePosition?: Point;
+  readonly args?: Args;
+}
+/** GLSP's context ids. The dispatcher answers every context with the palette. */
+export type ContextId = "tool-palette" | "context-menu" | "command-palette" | (string & {});
+export interface RequestContextActions extends RequestAction {
+  readonly kind: "requestContextActions";
+  readonly contextId: ContextId;
+  readonly editorContext: EditorContext;
+}
+/** One palette entry: the trigger action(s) a click sends, with the palette's data. */
+export interface LabeledAction {
+  readonly label: string;
+  readonly actions: readonly IstarAction[];
+  readonly icon?: string;
+  /** iStar extras, from the `PaletteDescription` entry. */
+  readonly id?: string;
+  readonly group?: string;
+  readonly section?: string;
+  readonly order?: number;
+}
+export interface SetContextActions extends ResponseAction {
+  readonly kind: "setContextActions";
+  /** Sorted by `order`. */
+  readonly actions: readonly LabeledAction[];
+  /** iStar extra: labels of the entries' `group`s (the palette's dropdown buttons). */
+  readonly groups?: Readonly<Record<string, {
+    readonly label: string;
+  }>>;
+  readonly args?: Args;
+}
+/** Arms the client's node creation tool; the client then sends a `CreateNodeOperation`. */
+export interface TriggerNodeCreationAction extends Action {
+  readonly kind: "triggerNodeCreation";
+  readonly elementTypeId: string;
+  /** Presets for the operation's `args`. */
+  readonly args?: {
+    readonly customProperties?: CustomProperties;
+  };
+}
+/** Arms the client's edge creation tool; the client then sends a `CreateEdgeOperation`. */
+export interface TriggerEdgeCreationAction extends Action {
+  readonly kind: "triggerEdgeCreation";
+  readonly elementTypeId: string;
+  /** Presets for the operation's `args`: a contribution's value, a dependency's dependum kind. */
+  readonly args?: {
+    readonly value?: string;
+    readonly dependum?: {
+      readonly kind: string;
+    };
+  };
+}
+/** GLSP's validation marker; `kind` is a `DiagnosticSeverity`. */
+export interface Marker {
+  /** Short text (the diagnostic's message). */
+  readonly label: string;
+  /** Full text (the message, with its source when it has one). */
+  readonly description: string;
+  readonly elementId: string;
+  readonly kind: DiagnosticSeverity | (string & {});
+  /** iStar extras, kept so a marker converts back to the same `GoalDiagnostic`. */
+  readonly key?: string;
+  readonly source?: string;
+  readonly code?: string;
+}
+/**
+ * Markers of the model: link constraint violations (`validateModel`), property issues (the
+ * dispatcher's `schemas`) and the host's `diagnostics`.
+ */
+export interface RequestMarkersAction extends RequestAction {
+  readonly kind: "requestMarkers";
+  /**
+   * Elements to report on (GLSP's spelling). Empty, or naming no element or link of the model
+   * (a GLSP client sends its root's id), means the whole model.
+   */
+  readonly elementsIDs: readonly string[];
+  readonly reason?: string;
+}
+export interface SetMarkersAction extends ResponseAction {
+  readonly kind: "setMarkers";
+  readonly markers: readonly Marker[];
+  readonly reason?: string;
+}
+export interface DeleteMarkersAction extends Action {
+  readonly kind: "deleteMarkers";
+  readonly markers: readonly Marker[];
+}
+export type IstarRequestAction = RequestModelAction | RequestTypeHintsAction | RequestCheckEdgeAction | RequestContextActions | RequestMarkersAction;
+export type IstarResponseAction = SetModelAction | SetTypeHintsAction | CheckEdgeResultAction | SetContextActions | SetMarkersAction;
+/**
+ * Actions the dispatcher does not act on: it passes them to its subscribers (a server telling
+ * its clients), and sends the first two itself.
+ */
+export type IstarNotificationAction = ModelSourceChangedAction | SetDirtyStateAction | TriggerNodeCreationAction | TriggerEdgeCreationAction | DeleteMarkersAction;
+/** Every action of the protocol, keyed by `kind`. */
+export type IstarAction<EK extends string = ElementKind, LK extends string = LinkKind> = IstarOperation<EK, LK> | UndoAction | RedoAction | SaveModelAction | IstarRequestAction | IstarResponseAction | IstarNotificationAction;
+/**
+ * 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.
+ */
+export declare const HANDLED_ACTION_KINDS: {
+  readonly operations: readonly IstarOperation["kind"][];
+  readonly requests: readonly IstarRequestAction["kind"][];
+  readonly notifications: readonly (UndoAction | RedoAction | SaveModelAction | IstarNotificationAction)["kind"][];
+};
+/** True for the operations (actions that edit the model). */
+export declare function isOperation<EK extends string, LK extends string>(action: IstarAction<EK, LK>): action is IstarOperation<EK, LK>;
+/** True for the requests (actions answered with a response action). */
+export declare function isRequestAction(action: Action): action is IstarRequestAction;
+//#endregion
+//#region src/dispatcher.d.ts
+/** The response a request is answered with; `never` for other actions. */
+export type ResponseFor<A> = A extends RequestModelAction ? SetModelAction : A extends RequestTypeHintsAction ? SetTypeHintsAction : A extends RequestCheckEdgeAction ? CheckEdgeResultAction : A extends RequestContextActions ? SetContextActions : A extends RequestMarkersAction ? SetMarkersAction : never;
+/**
+ * What dispatching an action did. Plain JSON, like the actions.
+ *
+ * A rejection (`ok: false`) left the model untouched: the same model object, no undo step. Its
+ * diagnostics say why (an unknown element, a link `canLink` refuses, a guard, a property schema).
+ */
+export type ActionResult<R = never> = {
+  readonly ok: true;
+  /** Ids of the elements, then links, the action added, in model order. */
+  readonly createdIds: readonly string[];
+  /** A request's answer. */
+  readonly response?: R;
+  /** Non-error diagnostics from guards, for an operation that was applied anyway. */
+  readonly diagnostics?: readonly GoalDiagnostic[];
+} | {
+  readonly ok: false;
+  readonly diagnostics: readonly GoalDiagnostic[];
+};
+export type ActionListener<EK extends string = ElementKind, LK extends string = LinkKind> = (action: IstarAction<EK, LK>) => void;
+/**
+ * Sends actions and hears what the other side sends back. Implemented in-process by
+ * `createActionDispatcher`; a transport implements it over a message port.
+ */
+export interface ActionDispatcher<EK extends string = ElementKind, LK extends string = LinkKind> {
+  dispatch<A extends IstarAction<EK, LK>>(action: A): 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.
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener: ActionListener<EK, LK>): () => void;
+}
+/**
+ * A host's rule, run before each operation is applied (and before each operation of a compound
+ * one, against the model as the previous ones left it). Diagnostics of severity `error` reject
+ * the operation; others are returned with the result.
+ */
+export type ActionGuard<EK extends string = ElementKind, LK extends string = LinkKind> = (operation: IstarOperation<EK, LK>, model: IstarModel<EK, LK>) => readonly GoalDiagnostic[] | void;
+export interface ActionDispatcherOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
+  readonly guards?: readonly ActionGuard<EK, LK>[];
+  /** What `RequestContextActions` offers. Default: `DEFAULT_PALETTE` (iStar 2.0's). */
+  readonly palette?: AnyPaletteDescription;
+  /**
+   * Property schemas an operation must not break: an operation that adds an issue
+   * (`validateModelProperties`) is rejected. Their issues are also markers.
+   */
+  readonly schemas?: readonly PropertySchema<PropertyShape, string>[];
+  /** The host's diagnostics (e.g. a `DiagnosticsStore`'s `getAll`), reported as markers. */
+  readonly diagnostics?: () => readonly GoalDiagnostic[];
+  /** Writes the file for `SaveModelAction`; without it, saving is rejected. */
+  readonly save?: (file: PistarFile, action: SaveModelAction) => void | Promise<void>;
+  /** `ModelSourceChangedAction.sourceModelName`, e.g. the file name. Default `''`. */
+  readonly sourceModelName?: string;
+  /**
+   * Attach the new model to every `sourceModelChanged` as `newRoot` (piStar JSON), so a mirror
+   * on the other end of a transport (`createMirrorStore`) follows without a `requestModel` round
+   * trip. Costs a `toPistarObject` per change (0.3 ms on the largest fixture). Default false.
+   */
+  readonly sendModel?: boolean;
+}
+export interface StoreActionDispatcher<EK extends string = ElementKind, LK extends string = LinkKind> extends ActionDispatcher<EK, LK> {
+  /** True while the model differs from the one last saved (or loaded, or given at creation). */
+  isDirty(): boolean;
+  /** Stops listening to the store. */
+  dispose(): void;
+}
+/**
+ * A dispatcher over `store`, in-process. Hand it to a transport to serve remote clients.
+ */
+export declare function createActionDispatcher<EK extends string = ElementKind, LK extends string = LinkKind>(store: ModelStore<EK, LK>, options?: ActionDispatcherOptions<EK, LK>): StoreActionDispatcher<EK, LK>;
+//#endregion
+//#region src/hints.d.ts
+/**
+ * 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.
+ */
+export declare function typeHintsFor<EK extends string, LK extends string>(metamodel: Metamodel<EK, LK>): Pick<SetTypeHintsAction, "shapeHints" | "edgeHints">;
+/**
+ * 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.
+ */
+export declare function contextActionsFor<EK extends string, LK extends string>(palette: AnyPaletteDescription, metamodel: Metamodel<EK, LK>): Pick<SetContextActions, "actions" | "groups">;
+//#endregion
+//#region src/host.d.ts
+/** A host's knowledge for the model: a system-prompt section and/or an MCP resource. */
+export interface HostContextProvider {
+  /**
+   * `^[a-zA-Z0-9_-]{1,64}$`: the MCP resource's name (and its tool's, when the server lists
+   * resources as tools), and the section's heading unless `title` is set.
+   */
+  readonly name: string;
+  readonly title?: string;
+  /** What the resource holds, for an MCP client's catalog. Default: the title. */
+  readonly description?: string;
+  /** The text: fixed, or computed from the model each time it is read. */
+  readonly text: string | ((model: AnyIstarModel) => string | Promise<string>);
+  /** Also a section of `runAgent`'s system prompt. Default true. */
+  readonly prompt?: boolean;
+  /** Also an MCP resource of every diagram session. Default true. */
+  readonly resource?: boolean;
+}
+/** What a host tool's handler is given. */
+export interface HostToolContext {
+  /** The model as it is now: the live one, or a Propose-mode run's scratch copy. */
+  getModel(): AnyIstarModel;
+  /**
+   * The session's dispatcher, the only way a tool edits the model. A read-only tool's refuses
+   * everything but requests (`requestModel`, `requestMarkers`, ...), with a `read-only-tool`
+   * diagnostic.
+   */
+  readonly dispatcher: ActionDispatcher<string, string>;
+  readonly signal?: AbortSignal;
+}
+/**
+ * What a host tool answers, in `ActionResult`'s shape: `content` (any JSON value) for the model
+ * to read, or a refusal with typed diagnostics it can repair against. A refused dispatch's
+ * `ActionResult` is one already: `if (!result.ok) return result;`.
+ */
+export type HostToolResult = {
+  readonly ok: true;
+  readonly content: unknown;
+} | {
+  readonly ok: false;
+  readonly diagnostics: readonly GoalDiagnostic[];
+};
+/** A tool of the host's own, served next to the istar tools. */
+export interface HostTool {
+  /** `^[a-zA-Z0-9_-]{1,64}$`, distinct from every other tool's. */
+  readonly name: string;
+  readonly title?: string;
+  /** What the model reads about the tool. */
+  readonly description: string;
+  /**
+   * JSON Schema of the arguments: an object schema (`{ type: 'object', properties, required }`).
+   * Over MCP the server validates calls against it (it needs `zod` 4.2 or later, for
+   * `z.fromJSONSchema`), with the session's `sessionId` added.
+   */
+  readonly inputSchema: {
+    readonly [key: string]: unknown;
+  };
+  /**
+   * True for a tool that only reads (MCP's `readOnlyHint`): Propose mode runs it straight away
+   * and never makes it a review step, and its `dispatcher` takes requests only.
+   */
+  readonly readOnly?: boolean;
+  handler(args: {
+    readonly [key: string]: unknown;
+  }, context: HostToolContext): HostToolResult | Promise<HostToolResult>;
+}
+/** `dispatcher`, refusing anything but requests: what a read-only host tool is handed. */
+export declare function readOnlyDispatcher(dispatcher: ActionDispatcher<string, string>, tool: string): ActionDispatcher<string, string>;
+/** The context a call of `tool` gets: `dispatcher` as is, or read-only for a read-only tool. */
+export declare function hostToolContext(tool: HostTool, dispatcher: ActionDispatcher<string, string>, getModel: () => AnyIstarModel, signal?: AbortSignal): HostToolContext;
+/** A provider's text for `model`. */
+export declare function contextText(provider: HostContextProvider, model: AnyIstarModel): Promise<string>;
+//#endregion
+//#region src/markers.d.ts
+/** A `GoalDiagnostic` as a GLSP marker: `kind` is its severity, `label` its message. */
+export declare function diagnosticToMarker(diagnostic: GoalDiagnostic): Marker;
+/**
+ * A GLSP marker as a `GoalDiagnostic`. A `kind` that is no `DiagnosticSeverity` reads as
+ * `info`; `range` and `data` are not carried by markers.
+ */
+export declare function markerToDiagnostic(marker: Marker): GoalDiagnostic;
+//#endregion
+//#region src/mirror.d.ts
+export interface MirrorStoreOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
+  /**
+   * The metamodel the remote's files are read with (`parsePistar`'s `metamodel`), and of the
+   * empty model shown until the first one arrives. Default iStar 2.0.
+   */
+  readonly metamodel?: Metamodel<EK, LK>;
+  /** `parsePistar`'s `fileMetamodel`: apply the file's own `"metamodel"` block. Default false. */
+  readonly fileMetamodel?: boolean;
+  /**
+   * How many undo steps the remote keeps, for `canUndo` estimate (see `MirrorStore`). Only used
+   * when the dispatcher doesn't send exact values. Default 100, a `ModelStore`'s default.
+   */
+  readonly historyLimit?: number;
+  /** Hears a failed update (a transport fault, a file that doesn't parse). Default: ignored. */
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * A `ModelStore` whose model is the remote's. Reading (`getModel`, `subscribe`, `canLink`) works
+ * as on any store; every mutation (`addElement` … `replace`, `load`, `transaction`,
+ * `clearHistory`) throws a `ModelOperationError`: dispatch the edit to the remote instead.
+ *
+ * Undo is the remote's, one stack for all its clients: `undo`/`redo` dispatch `glspUndo` /
+ * `glspRedo` to it. `canUndo`/`canRedo` are exact when the dispatcher sends them with each
+ * change (a dispatcher created with `sendModel`), or an estimate counted from the notifications
+ * heard since the mirror connected (the remote doesn't publish its stack's depth when not sending
+ * them): edits made before then are not counted.
+ */
+export interface MirrorStore<EK extends string = ElementKind, LK extends string = LinkKind> extends ModelStore<EK, LK> {
+  /** Resolves once the remote's model is shown; rejects if the first `requestModel` fails. */
+  readonly ready: Promise<void>;
+  /**
+   * The remote, wrapped so that `dispatch` resolves only once the mirror shows what the action
+   * did: give this to `IstarProvider` as `dispatcher`. (With a `sendModel` remote, the remote
+   * itself already has that order, since a change's notification arrives before its result.)
+   */
+  readonly dispatcher: ActionDispatcher<EK, LK>;
+  /** Resolves once every change heard so far is shown. */
+  synced(): Promise<void>;
+  /** Stops following the remote (the remote itself stays open). */
+  dispose(): void;
+}
+/**
+ * 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.
+ */
+export declare function createMirrorStore<EK extends string = ElementKind, LK extends string = LinkKind>(remote: ActionDispatcher<EK, LK>, options?: MirrorStoreOptions<EK, LK>): MirrorStore<EK, LK>;
+//#endregion
+//#region src/transport.d.ts
+/** An id a JSON-RPC request carries and its response answers back. */
+export type JsonRpcId = string | number;
+export interface JsonRpcRequest {
+  readonly jsonrpc: "2.0";
+  readonly id: JsonRpcId;
+  readonly method: string;
+  readonly params?: unknown;
+}
+/** A subscriber event, sent with no `id`: it expects no response. */
+export interface JsonRpcNotification {
+  readonly jsonrpc: "2.0";
+  readonly method: string;
+  readonly params?: unknown;
+}
+export interface JsonRpcSuccess {
+  readonly jsonrpc: "2.0";
+  readonly id: JsonRpcId;
+  readonly result: unknown;
+}
+export interface JsonRpcErrorObject {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: unknown;
+}
+export interface JsonRpcError {
+  readonly jsonrpc: "2.0";
+  readonly id: JsonRpcId;
+  readonly error: JsonRpcErrorObject;
+}
+/** The envelope `connectDispatcher`/`createRemoteDispatcher` exchange over the port. */
+export type ActionMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcSuccess | JsonRpcError;
+/**
+ * Structurally what a DOM `MessagePort`, a worker's `self`, or any two-way `postMessage` channel
+ * gives us: enough to send and receive `ActionMessage`s, nothing DOM-specific. Generic over the
+ * event type `onmessage` is handed (`MessageEvent` for a real port, inferred at the call site),
+ * so a real `MessagePort` or `Worker` fits without a cast: `strictFunctionTypes` checks a
+ * property-typed handler's parameter invariantly, so pinning it to a narrower `{ data: unknown }`
+ * here would reject `MessagePort`'s own, wider `onmessage` type.
+ */
+export interface MessagePortLike<E extends {
+  readonly data: unknown;
+} = {
+  readonly data: unknown;
+}> {
+  postMessage(data: unknown): void;
+  onmessage: ((ev: E) => unknown) | null;
+}
+/**
+ * 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`.
+ */
+export declare function connectDispatcher<EK extends string = ElementKind, LK extends string = LinkKind, E extends {
+  readonly data: unknown;
+} = {
+  readonly data: unknown;
+}>(port: MessagePortLike<E>, dispatcher: ActionDispatcher<EK, LK>): () => void;
+/**
+ * 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.
+ */
+export declare function createRemoteDispatcher<EK extends string = ElementKind, LK extends string = LinkKind, E extends {
+  readonly data: unknown;
+} = {
+  readonly data: unknown;
+}>(port: MessagePortLike<E>): ActionDispatcher<EK, LK>;
+//#endregion
+//#region src/index.d.ts
+/** Version of the action protocol this package speaks. */
+export declare const ACTIONS_PROTOCOL_VERSION: string;
+//#endregion
+//# sourceMappingURL=index.d.cts.map