@stocksharp/diagram 0.2.3 → 0.4.0

package/src/core/document.ts

@@ -1,15 +1,17 @@
+import { setJsonKey } from './json.js';
+import { toPortDynamicMode } from './model.js';
 import {
     DIAGRAM_DOCUMENT_VERSION,
     type DiagramDocument,
     type DiagramDocumentEndpoint,
     type DiagramDocumentInput,
     type DiagramDocumentLink,
-    type DiagramDocumentLinkInput,
+    type DiagramLinkStyle,
     type DiagramDocumentNode,
-    type DiagramDocumentNodeInput,
     type DiagramDocumentPort,
-    type DiagramDocumentPortInput,
+    type DiagramDocumentZone,
     type DiagramParameterSchema,
+    type PortDynamicMode,
     type JsonObject,
     type JsonValue,
 } from './model.js';
@@ -21,10 +23,13 @@ export type {
     DiagramDocumentInput,
     DiagramDocumentLink,
     DiagramDocumentLinkInput,
+    DiagramLinkStyle,
     DiagramDocumentNode,
     DiagramDocumentNodeInput,
     DiagramDocumentPort,
     DiagramDocumentPortInput,
+    DiagramDocumentZone,
+    DiagramDocumentZoneInput,
     DiagramDocumentVersion,
     DiagramParameterSchema,
     JsonObject,
@@ -40,13 +45,18 @@ export class DiagramDocumentError extends Error {
 }
 
 export function createDiagramDocument(input: DiagramDocumentInput = {}): DiagramDocument {
-    const nodes = (input.nodes ?? []).map((node, index) => normalizeNode(node, `$.nodes[${index}]`));
+    // DiagramDocumentInput is a structural interface, so its shape is a claim by
+    // the caller, not a guarantee. Elements are checked the same way parsed ones
+    // are, otherwise a malformed one surfaces as a TypeError naming no path.
+    const rawNodes = mapElements(input.nodes, '$.nodes');
+    const rawLinks = mapElements(input.links, '$.links');
+    const nodes = rawNodes.map((node, index) => normalizeNode(node, `$.nodes[${index}]`));
     const usedLinkIds = new Set<string>();
 
-    for (let index = 0; index < (input.links ?? []).length; index++) {
-        const id = input.links?.[index].id;
-        if (id === undefined) continue;
-        requireIdentifier(id, `$.links[${index}].id`);
+    for (let index = 0; index < rawLinks.length; index++) {
+        const raw = rawLinks[index].id;
+        if (raw === undefined) continue;
+        const id = requireIdentifier(raw, `$.links[${index}].id`);
         if (usedLinkIds.has(id)) {
             throw new DiagramDocumentError(`duplicate link id "${id}"`, `$.links[${index}].id`);
         }
@@ -54,19 +64,33 @@ export function createDiagramDocument(input: DiagramDocumentInput = {}): Diagram
     }
 
     let sequence = 1;
-    const links = (input.links ?? []).map((link, index) => {
+    const links = rawLinks.map((link, index) => {
         let id = link.id;
         if (id === undefined) {
-            do id = `link_${sequence++}`;
-            while (usedLinkIds.has(id));
-            usedLinkIds.add(id);
+            let generated: string;
+            do generated = `link_${sequence++}`;
+            while (usedLinkIds.has(generated));
+            usedLinkIds.add(generated);
+            id = generated;
         }
         return normalizeLink({ ...link, id }, `$.links[${index}]`);
     });
+    const rawZones = mapElements(input.zones, '$.zones');
+    const usedZoneIds = new Set<string>();
+    const zones = rawZones.map((zone, index) => {
+        const normalized = normalizeZone(zone, `$.zones[${index}]`);
+        if (usedZoneIds.has(normalized.id)) {
+            throw new DiagramDocumentError(`duplicate zone id "${normalized.id}"`, `$.zones[${index}].id`);
+        }
+        usedZoneIds.add(normalized.id);
+        return normalized;
+    });
+
     const document: DiagramDocument = {
         version: DIAGRAM_DOCUMENT_VERSION,
         nodes,
         links,
+        zones,
         metadata: cloneJsonObject(input.metadata ?? {}, '$.metadata'),
     };
     validateDocument(document);
@@ -92,7 +116,7 @@ export function parseDiagramDocument(source: string | unknown): DiagramDocument
         }
     }
 
-    const root = requireObject(value, '$');
+    const root = requireStructure(value, '$');
     const version = requireNumber(root.version, '$.version');
     if (version !== DIAGRAM_DOCUMENT_VERSION) {
         throw new DiagramDocumentError(`unsupported document version ${version}`, '$.version');
@@ -101,13 +125,19 @@ export function parseDiagramDocument(source: string | unknown): DiagramDocument
         version: DIAGRAM_DOCUMENT_VERSION,
         nodes: requireArray(root.nodes, '$.nodes').map((node, index) => parseNode(node, `$.nodes[${index}]`)),
         links: requireArray(root.links, '$.links').map((link, index) => parseLink(link, `$.links[${index}]`)),
+        // Zones arrived after the first documents were written, so their absence is not a fault:
+        // an older file simply has none, and reading it must not need a migration step.
+        zones: root.zones === undefined || root.zones === null
+            ? []
+            : requireArray(root.zones, '$.zones').map((zone, index) => normalizeZone(zone, `$.zones[${index}]`)),
         metadata: cloneJsonObject(root.metadata, '$.metadata'),
     };
     validateDocument(document);
     return document;
 }
 
-function normalizeNode(input: DiagramDocumentNodeInput, path: string): DiagramDocumentNode {
+function normalizeNode(value: unknown, path: string): DiagramDocumentNode {
+    const input = requireStructure(value, path);
     const id = requireIdentifier(input.id, `${path}.id`);
     return {
         id,
@@ -122,30 +152,36 @@ function normalizeNode(input: DiagramDocumentNodeInput, path: string): DiagramDo
         icon: requireString(input.icon ?? '', `${path}.icon`),
         message: requireString(input.message ?? '', `${path}.message`),
         openAction: requireString(input.openAction ?? '', `${path}.openAction`),
-        inPorts: (input.inPorts ?? []).map((port, index) => normalizePort(port, `${path}.inPorts[${index}]`)),
-        outPorts: (input.outPorts ?? []).map((port, index) => normalizePort(port, `${path}.outPorts[${index}]`)),
-        parameters: (input.parameters ?? []).map((parameter, index) => normalizeParameter(parameter, `${path}.parameters[${index}]`)),
+        inPorts: mapElements(input.inPorts, `${path}.inPorts`)
+            .map((port, index) => normalizePort(port, `${path}.inPorts[${index}]`)),
+        outPorts: mapElements(input.outPorts, `${path}.outPorts`)
+            .map((port, index) => normalizePort(port, `${path}.outPorts[${index}]`)),
+        parameters: mapElements(input.parameters, `${path}.parameters`)
+            .map((parameter, index) => normalizeParameter(parameter, `${path}.parameters[${index}]`)),
         paramValues: cloneStringRecord(input.paramValues ?? {}, `${path}.paramValues`),
         metadata: cloneJsonObject(input.metadata ?? {}, `${path}.metadata`),
     };
 }
 
-function normalizePort(input: DiagramDocumentPortInput, path: string): DiagramDocumentPort {
+function normalizePort(value: unknown, path: string): DiagramDocumentPort {
+    const input = requireStructure(value, path);
     return {
         id: requireIdentifier(input.id, `${path}.id`),
         name: requireString(input.name, `${path}.name`),
         description: requireString(input.description ?? '', `${path}.description`),
         type: requireString(input.type ?? '', `${path}.type`),
         maxLinks: requireNonNegativeInteger(input.maxLinks ?? 0, `${path}.maxLinks`),
-        availableTypes: (input.availableTypes ?? []).map((type, index) => requireString(type, `${path}.availableTypes[${index}]`)),
+        availableTypes: requireArray(input.availableTypes ?? [], `${path}.availableTypes`)
+            .map((type, index) => requireString(type, `${path}.availableTypes[${index}]`)),
         isDynamic: requireBoolean(input.isDynamic ?? false, `${path}.isDynamic`),
-        dynamicMode: requireString(input.dynamicMode ?? '', `${path}.dynamicMode`),
+        dynamicMode: requirePortDynamicMode(input.dynamicMode ?? '', `${path}.dynamicMode`),
         isSibling: requireBoolean(input.isSibling ?? false, `${path}.isSibling`),
         metadata: cloneJsonObject(input.metadata ?? {}, `${path}.metadata`),
     };
 }
 
-function normalizeParameter(input: DiagramParameterSchema, path: string): DiagramParameterSchema {
+function normalizeParameter(value: unknown, path: string): DiagramParameterSchema {
+    const input = requireStructure(value, path);
     return {
         name: requireIdentifier(input.name, `${path}.name`),
         displayName: requireString(input.displayName, `${path}.displayName`),
@@ -162,16 +198,51 @@ function normalizeParameter(input: DiagramParameterSchema, path: string): Diagra
     };
 }
 
-function normalizeLink(input: DiagramDocumentLinkInput & { id: string }, path: string): DiagramDocumentLink {
+function normalizeLink(value: unknown, path: string): DiagramDocumentLink {
+    const input = requireStructure(value, path);
     return {
         id: requireIdentifier(input.id, `${path}.id`),
         from: normalizeEndpoint(input.from, `${path}.from`),
         to: normalizeEndpoint(input.to, `${path}.to`),
+        style: requireLinkStyle(input.style, `${path}.style`),
         metadata: cloneJsonObject(input.metadata ?? {}, `${path}.metadata`),
     };
 }
 
-function normalizeEndpoint(input: DiagramDocumentEndpoint, path: string): DiagramDocumentEndpoint {
+// A style the caller misspelled is a drawing that quietly loses its meaning, so it is refused
+// rather than defaulted - unlike an absent one, which simply means a plain line.
+function requireLinkStyle(value: unknown, path: string): DiagramLinkStyle {
+    if (value === undefined || value === null) return 'solid';
+    if (value !== 'solid' && value !== 'dashed') {
+        throw new DiagramDocumentError(`unknown link style "${String(value)}"`, path);
+    }
+    return value;
+}
+
+function normalizeZone(value: unknown, path: string): DiagramDocumentZone {
+    const input = requireStructure(value, path);
+    return {
+        id: requireIdentifier(input.id, `${path}.id`),
+        name: requireString(input.name, `${path}.name`),
+        x: requireNumber(input.x, `${path}.x`),
+        y: requireNumber(input.y, `${path}.y`),
+        width: requirePositiveSize(input.width, `${path}.width`),
+        height: requirePositiveSize(input.height, `${path}.height`),
+        color: input.color === undefined || input.color === null ? '' : requireString(input.color, `${path}.color`),
+        metadata: cloneJsonObject(input.metadata ?? {}, `${path}.metadata`),
+    };
+}
+
+// A zone with no area cannot be pointed at, and a negative one paints outside itself, so the
+// size is refused rather than clamped - a caller that computed it wrong wants to hear about it.
+function requirePositiveSize(value: unknown, path: string): number {
+    const size = requireNumber(value, path);
+    if (!(size > 0)) throw new DiagramDocumentError('size must be greater than zero', path);
+    return size;
+}
+
+function normalizeEndpoint(value: unknown, path: string): DiagramDocumentEndpoint {
+    const input = requireStructure(value, path);
     return {
         nodeId: requireIdentifier(input.nodeId, `${path}.nodeId`),
         portId: requireIdentifier(input.portId, `${path}.portId`),
@@ -179,7 +250,7 @@ function normalizeEndpoint(input: DiagramDocumentEndpoint, path: string): Diagra
 }
 
 function parseNode(value: unknown, path: string): DiagramDocumentNode {
-    const node = requireObject(value, path);
+    const node = requireStructure(value, path);
     return normalizeNode({
         id: requireString(node.id, `${path}.id`),
         typeId: requireString(node.typeId, `${path}.typeId`),
@@ -202,7 +273,7 @@ function parseNode(value: unknown, path: string): DiagramDocumentNode {
 }
 
 function parsePort(value: unknown, path: string): DiagramDocumentPort {
-    const port = requireObject(value, path);
+    const port = requireStructure(value, path);
     return normalizePort({
         id: requireString(port.id, `${path}.id`),
         name: requireString(port.name, `${path}.name`),
@@ -211,14 +282,14 @@ function parsePort(value: unknown, path: string): DiagramDocumentPort {
         maxLinks: requireNumber(port.maxLinks, `${path}.maxLinks`),
         availableTypes: requireArray(port.availableTypes, `${path}.availableTypes`).map((type, index) => requireString(type, `${path}.availableTypes[${index}]`)),
         isDynamic: requireBoolean(port.isDynamic, `${path}.isDynamic`),
-        dynamicMode: requireString(port.dynamicMode, `${path}.dynamicMode`),
+        dynamicMode: requirePortDynamicMode(port.dynamicMode, `${path}.dynamicMode`),
         isSibling: requireBoolean(port.isSibling, `${path}.isSibling`),
         metadata: cloneJsonObject(port.metadata, `${path}.metadata`),
     }, path);
 }
 
 function parseParameter(value: unknown, path: string): DiagramParameterSchema {
-    const parameter = requireObject(value, path);
+    const parameter = requireStructure(value, path);
     return normalizeParameter({
         name: requireString(parameter.name, `${path}.name`),
         displayName: requireString(parameter.displayName, `${path}.displayName`),
@@ -236,17 +307,18 @@ function parseParameter(value: unknown, path: string): DiagramParameterSchema {
 }
 
 function parseLink(value: unknown, path: string): DiagramDocumentLink {
-    const link = requireObject(value, path);
+    const link = requireStructure(value, path);
     return normalizeLink({
         id: requireString(link.id, `${path}.id`),
         from: parseEndpoint(link.from, `${path}.from`),
         to: parseEndpoint(link.to, `${path}.to`),
+        style: link.style === undefined ? undefined : requireLinkStyle(link.style, `${path}.style`),
         metadata: cloneJsonObject(link.metadata, `${path}.metadata`),
     }, path);
 }
 
 function parseEndpoint(value: unknown, path: string): DiagramDocumentEndpoint {
-    const endpoint = requireObject(value, path);
+    const endpoint = requireStructure(value, path);
     return {
         nodeId: requireIdentifier(endpoint.nodeId, `${path}.nodeId`),
         portId: requireIdentifier(endpoint.portId, `${path}.portId`),
@@ -298,7 +370,7 @@ function validateUniquePorts(ports: readonly DiagramDocumentPort[], path: string
 function cloneStringRecord(value: unknown, path: string): Record<string, string> {
     const object = requireObject(value, path);
     const result: Record<string, string> = {};
-    for (const [key, item] of Object.entries(object)) result[key] = requireString(item, `${path}.${key}`);
+    for (const [key, item] of Object.entries(object)) setJsonKey(result, key, requireString(item, `${path}.${key}`));
     return result;
 }
 
@@ -309,7 +381,7 @@ function cloneJsonObject(value: unknown, path: string, ancestors = new WeakSet<o
     const result: JsonObject = {};
     try {
         for (const [key, item] of Object.entries(object)) {
-            result[key] = cloneJsonValue(item, `${path}.${key}`, ancestors);
+            setJsonKey(result, key, cloneJsonValue(item, `${path}.${key}`, ancestors));
         }
     } finally {
         ancestors.delete(object);
@@ -333,6 +405,23 @@ function cloneJsonValue(value: unknown, path: string, ancestors: WeakSet<object>
     throw new DiagramDocumentError('expected a JSON value', path);
 }
 
+/**
+ * A container whose fields are read individually. Any object will do, including
+ * a class instance: hosts build schemes out of DiagramNode and Port, not object
+ * literals, and every field is validated on its own below.
+ */
+function requireStructure(value: unknown, path: string): Record<string, unknown> {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new DiagramDocumentError('expected an object', path);
+    }
+    return value as Record<string, unknown>;
+}
+
+/**
+ * A value that has to survive JSON round-tripping unchanged. Stricter than
+ * requireStructure on purpose: a Date or any other class instance would
+ * serialize to something the parser could not read back.
+ */
 function requireObject(value: unknown, path: string): Record<string, unknown> {
     if (!isObject(value)) throw new DiagramDocumentError('expected an object', path);
     return value;
@@ -344,6 +433,21 @@ function isObject(value: unknown): value is Record<string, unknown> {
     return prototype === Object.prototype || prototype === null;
 }
 
+/**
+ * Reads an optional array of objects, rejecting a non-array, a hole or a
+ * non-object element. null counts as absent, like the `?? []` every other
+ * optional field is read through.
+ */
+function mapElements(value: unknown, path: string): Record<string, unknown>[] {
+    if (value === undefined || value === null) return [];
+    // Array.from rather than map: map skips holes, carrying an undefined element
+    // into the result instead of reporting it.
+    return Array.from(
+        requireArray(value, path),
+        (element, index) => requireStructure(element, `${path}[${index}]`),
+    );
+}
+
 function requireArray(value: unknown, path: string): unknown[] {
     if (!Array.isArray(value)) throw new DiagramDocumentError('expected an array', path);
     return value;
@@ -354,6 +458,18 @@ function requireString(value: unknown, path: string): string {
     return value;
 }
 
+/**
+ * Coerces rather than rejects. The set is closed in the types, which is where a
+ * typo gets caught, but a persisted scheme can carry anything a JavaScript host
+ * wrote before that -- and refusing to load it would brick the whole document
+ * over a field whose every value except 'onConnect' behaves identically. The
+ * type must still be a string, so a number or an object is a real error.
+ */
+function requirePortDynamicMode(value: unknown, path: string): PortDynamicMode {
+    const mode = requireString(value, path);
+    return toPortDynamicMode(mode);
+}
+
 function requireIdentifier(value: unknown, path: string): string {
     const id = requireString(value, path);
     if (id.trim().length === 0) throw new DiagramDocumentError('identifier cannot be empty', path);

package/src/core/json.ts

@@ -0,0 +1,16 @@
+/**
+ * Stores a key that JSON can legitimately carry but plain assignment cannot hold.
+ *
+ * `JSON.parse` produces `__proto__` as an ordinary own key, yet writing it back
+ * with `target[key] = value` hits the inherited `__proto__` setter: the value is
+ * dropped and the object's prototype is replaced instead. A document parsed that
+ * way loses data and stops satisfying the parser's own "plain object" guard, so
+ * anything the parser accepted could no longer be serialized or cloned.
+ */
+export function setJsonKey<T>(target: Record<string, T>, key: string, value: T): void {
+    if (key === '__proto__') {
+        Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+        return;
+    }
+    target[key] = value;
+}

package/src/core/model.ts

@@ -20,6 +20,19 @@ export interface DiagramParameterSchema {
     editorType: string;
 }
 
+/**
+ * How a dynamic port grows. Only 'onConnect' makes the editor add a typed
+ * sibling when a link lands on the port; '' and 'manual' leave it to the host.
+ * The renderer compares this with ===, so a value outside the set silently
+ * selects the do-nothing branch -- hence a union rather than a string.
+ */
+export type PortDynamicMode = '' | 'manual' | 'onConnect';
+
+/** Narrows an untyped value to the closed set, defaulting to the inert mode. */
+export function toPortDynamicMode(value: unknown): PortDynamicMode {
+    return value === 'manual' || value === 'onConnect' ? value : '';
+}
+
 export interface DiagramDocumentPort {
     id: string;
     name: string;
@@ -28,7 +41,7 @@ export interface DiagramDocumentPort {
     maxLinks: number;
     availableTypes: string[];
     isDynamic: boolean;
-    dynamicMode: string;
+    dynamicMode: PortDynamicMode;
     isSibling: boolean;
     metadata: JsonObject;
 }
@@ -59,11 +72,43 @@ export interface DiagramDocumentEndpoint {
     portId: string;
 }
 
+/**
+ * How a link is drawn. A dashed link reads as one that may or may not be there -
+ * an optional hop, a path taken only in some deployments - which a solid line
+ * cannot say. The renderer compares this with ===, so a value outside the set
+ * would silently fall through to solid; hence a union rather than a string.
+ */
+export type DiagramLinkStyle = 'solid' | 'dashed';
+
+/** Narrows an untyped value to the closed set, defaulting to a plain line. */
+export function toDiagramLinkStyle(value: unknown): DiagramLinkStyle {
+    return value === 'dashed' ? 'dashed' : 'solid';
+}
+
 export interface DiagramDocumentLink {
     /** Stable identity used by selection, relinking and history. */
     id: string;
     from: DiagramDocumentEndpoint;
     to: DiagramDocumentEndpoint;
+    style: DiagramLinkStyle;
+    metadata: JsonObject;
+}
+
+/**
+ * A labelled rectangle drawn behind the nodes. It says where things are rather
+ * than what they do - a colocation cage, a tenant boundary, a process - which no
+ * arrangement of nodes and links can state on its own. A zone owns nothing: the
+ * nodes that sit on it are not its children, so moving one changes no membership.
+ */
+export interface DiagramDocumentZone {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Empty means the renderer picks its own neutral tint. */
+    color: string;
     metadata: JsonObject;
 }
 
@@ -74,6 +119,7 @@ export interface DiagramDocument {
     version: DiagramDocumentVersion;
     nodes: DiagramDocumentNode[];
     links: DiagramDocumentLink[];
+    zones: DiagramDocumentZone[];
     metadata: JsonObject;
 }
 
@@ -87,13 +133,20 @@ export type DiagramDocumentNodeInput = Pick<DiagramDocumentNode, 'id' | 'name'>
         outPorts?: readonly DiagramDocumentPortInput[];
     };
 
-export type DiagramDocumentLinkInput = Omit<DiagramDocumentLink, 'id' | 'metadata'> & {
+export type DiagramDocumentLinkInput = Omit<DiagramDocumentLink, 'id' | 'style' | 'metadata'> & {
     id?: string;
+    style?: DiagramLinkStyle;
+    metadata?: JsonObject;
+};
+
+export type DiagramDocumentZoneInput = Omit<DiagramDocumentZone, 'color' | 'metadata'> & {
+    color?: string;
     metadata?: JsonObject;
 };
 
 export interface DiagramDocumentInput {
     nodes?: readonly DiagramDocumentNodeInput[];
     links?: readonly DiagramDocumentLinkInput[];
+    zones?: readonly DiagramDocumentZoneInput[];
     metadata?: JsonObject;
 }

package/src/core/state.ts

@@ -1,3 +1,20 @@
+/**
+ * Recursively read-only view of a state object. The snapshot accessors hand back
+ * detached copies, so writing to one is silently discarded -- this makes that a
+ * compile error instead. The setters accept it, so a snapshot still round-trips.
+ */
+export type DiagramSnapshot<T> = {
+    readonly [K in keyof T]: DiagramSnapshotValue<T[K]>;
+};
+
+// Distributes over unions, so an optional or nullable object property keeps
+// being descended into instead of falling through as its writable self.
+type DiagramSnapshotValue<T> = T extends readonly (infer TItem)[]
+    ? readonly DiagramSnapshotValue<TItem>[]
+    : T extends object
+        ? DiagramSnapshot<T>
+        : T;
+
 export type DiagramPortDirection = 'in' | 'out';
 export type DiagramNodeErrorKind = 'runtime' | 'load';
 export type DiagramGlobalErrorKind = 'invalid' | 'load' | 'locked' | 'encrypted';
@@ -23,9 +40,18 @@ export interface DiagramNodePortRuntimeState {
     out: Record<string, DiagramPortRuntimeState>;
 }
 
+/**
+ * At most one error per kind. A node can carry a load error and a runtime error
+ * at the same time -- the tooltip shows both -- so a single slot could not hold
+ * what the editor already models, and every state write dropped one of them.
+ */
+export type DiagramNodeErrors = {
+    [TKind in DiagramNodeErrorKind]?: DiagramErrorState<TKind>;
+};
+
 export interface DiagramNodeRuntimeState {
     active: boolean;
-    error: DiagramErrorState<DiagramNodeErrorKind> | null;
+    errors: DiagramNodeErrors;
     ports: DiagramNodePortRuntimeState;
 }
 
@@ -77,7 +103,7 @@ export function cloneDiagramRuntimeState(state: DiagramRuntimeState): DiagramRun
         globalError: state.globalError === null ? null : { ...state.globalError },
         nodes: Object.fromEntries(Object.entries(state.nodes).map(([nodeId, node]) => [nodeId, {
             active: node.active,
-            error: node.error === null ? null : { ...node.error },
+            errors: cloneDiagramNodeErrors(node.errors),
             ports: {
                 in: Object.fromEntries(Object.entries(node.ports.in)
                     .map(([portId, port]) => [portId, { ...port }])),
@@ -142,7 +168,19 @@ export function createReadOnlyDiagramPermissions(): DiagramInteractionPermission
 export function createDiagramNodeRuntimeState(): DiagramNodeRuntimeState {
     return {
         active: false,
-        error: null,
+        errors: {},
         ports: { in: {}, out: {} },
     };
 }
+
+/**
+ * Tolerates a missing map: hosts persist runtime snapshots and build them by
+ * hand, so a state written before this field existed still has to be readable.
+ */
+export function cloneDiagramNodeErrors(errors: DiagramNodeErrors | undefined | null): DiagramNodeErrors {
+    const result: DiagramNodeErrors = {};
+    if (errors === undefined || errors === null) return result;
+    if (errors.runtime !== undefined) result.runtime = { ...errors.runtime };
+    if (errors.load !== undefined) result.load = { ...errors.load };
+    return result;
+}

package/src/diagram/api.ts

@@ -2,6 +2,7 @@ import type { DiagramDocument } from '../core/model.js';
 import type {
     DiagramRuntimeState,
     DiagramSelection,
+    DiagramSnapshot,
     DiagramViewState,
 } from '../core/state.js';
 import type { DiagramNode, Link, Port, PortDirection } from './types.js';
@@ -232,7 +233,7 @@ export interface LinkValidatorArgs {
 
 export type LinkValidator = (args: LinkValidatorArgs) => boolean;
 
-export interface DiagramEvents extends Record<string, unknown> {
+export interface DiagramEvents {
     nodeAdded: NodeChangePayload;
     nodeRemoved: NodeChangePayload;
     linkAdded: LinkChangePayload;
@@ -256,10 +257,10 @@ export interface DiagramEvents extends Record<string, unknown> {
     nodeProperties: NodeChangePayload;
     nodeOpen: NodeChangePayload;
     nodeHelp: NodeChangePayload;
-    zoomChanged: DiagramViewState;
-    viewChanged: DiagramViewState;
-    selectionChanged: DiagramSelection;
-    runtimeStateChanged: { state: DiagramRuntimeState };
+    zoomChanged: DiagramSnapshot<DiagramViewState>;
+    viewChanged: DiagramSnapshot<DiagramViewState>;
+    selectionChanged: DiagramSnapshot<DiagramSelection>;
+    runtimeStateChanged: { state: DiagramSnapshot<DiagramRuntimeState> };
     undoStackChanged: { canUndo: boolean; canRedo: boolean };
     documentLoaded: { document: DiagramDocument };
     documentLoadFailed: DocumentLoadFailedPayload;

package/src/diagram/catalog.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from './event-emitter.js';
 import { Node, NodeInit, PortType, PortTypeInit } from './types.js';
 
-export interface CatalogEvents extends Record<string, unknown> {
+export interface CatalogEvents {
     portTypesChanged: PortType[];
     nodeTypesChanged: Node[];
 }
@@ -35,21 +35,33 @@ export class StockSharpCatalog extends EventEmitter<CatalogEvents> {
     // imported node ("Element type is missing from the palette"). Node.id
     // keeps its original casing so save/load round-trips unchanged.
     addNodeType(node: Node | NodeInit): void {
-        const n = node instanceof Node ? node : new Node(node);
+        // Copied on the way in as well as on the way out: otherwise the caller
+        // keeps a handle on the stored definition and can edit it afterwards.
+        // The clone covers the init branch too -- Node's constructor keeps the
+        // caller's Port instances and parameters array as they are.
+        const n = (node instanceof Node ? node : new Node(node)).clone();
         this.nodeTypes.set(n.id.toLowerCase(), n);
-        this.emit('nodeTypesChanged', this.getNodeTypes());
+        this.emitNodeTypesChanged();
     }
 
     removeNodeType(id: string): void {
         this.nodeTypes.delete(id.toLowerCase());
-        this.emit('nodeTypesChanged', this.getNodeTypes());
+        this.emitNodeTypesChanged();
     }
 
     getNodeType(id: string): Node | null {
-        return this.nodeTypes.get(id.toLowerCase()) ?? null;
+        return this.nodeTypes.get(id.toLowerCase())?.clone() ?? null;
     }
 
     getNodeTypes(): Node[] {
-        return Array.from(this.nodeTypes.values());
+        return Array.from(this.nodeTypes.values(), (node) => node.clone());
+    }
+
+    // Node definitions are mutable, so the payload has to be a copy of each one.
+    // Building a catalog is a loop of addNodeType calls, which would make that
+    // quadratic; skipping it while nobody listens keeps catalog construction --
+    // where no subscriber exists yet -- as cheap as it was.
+    private emitNodeTypesChanged(): void {
+        if (this.hasHandlers('nodeTypesChanged')) this.emit('nodeTypesChanged', this.getNodeTypes());
     }
 }

package/src/diagram/event-emitter.ts

@@ -1,6 +1,9 @@
 export type EventHandler<T> = (payload: T) => void;
 
-export class EventEmitter<TEvents extends Record<string, unknown>> {
+// TEvents is constrained to object rather than Record<string, unknown>: the
+// latter forces every event map to carry a string index signature, which
+// collapses keyof TEvents to string and lets any misspelled name compile.
+export class EventEmitter<TEvents extends object> {
     private readonly handlers = new Map<keyof TEvents, Set<EventHandler<unknown>>>();
 
     on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void {
@@ -38,6 +41,14 @@ export class EventEmitter<TEvents extends Record<string, unknown>> {
         }
     }
 
+    /**
+     * Whether anyone is listening. Lets a subject skip building a payload that
+     * is expensive to produce and that nothing would read.
+     */
+    protected hasHandlers<K extends keyof TEvents>(event: K): boolean {
+        return (this.handlers.get(event)?.size ?? 0) > 0;
+    }
+
     protected clearEventHandlers(): void {
         this.handlers.clear();
     }

package/src/diagram/palette.ts

@@ -22,7 +22,7 @@ export interface PaletteContextMenuPayload extends PaletteNodePayload {
     y: number;
 }
 
-export interface PaletteEvents extends Record<string, unknown> {
+export interface PaletteEvents {
     selectionChanged: PaletteSelectionChangedPayload;
     nodeActivated: PaletteNodePayload;
     contextMenuRequested: PaletteContextMenuPayload;