@stuly/anode 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,6 @@
-# anode
+# @stuly/anode
 
-The core headless engine for Anode. It manages graph state, connectivity,
-spatial indexing, and history independently of any UI framework.
+The high-performance, headless core engine for Anode. It manages graph topology, spatial indexing, transactional history, and reactive data flow independently of any UI framework.
 
 ## Installation
 
@@ -9,11 +8,29 @@ spatial indexing, and history independently of any UI framework.
 npm install @stuly/anode
 ```
 
-## Features
+## Quick Start
 
-- **Headless Context:** Centralized state management for nodes, links, and sockets.
-- **QuadTree Indexing:** High-performance spatial querying and culling.
-- **Transactional History:** Built-in undo/redo with support for batched actions.
-- **Data Flow:** Automated value propagation between linked sockets.
+```typescript
+import { Context, SocketKind } from '@stuly/anode';
 
-For detailed documentation and usage examples, see the [root README](../../README.md).
+const ctx = new Context();
+
+const nodeA = ctx.newEntity({ label: 'Source' });
+const outA = ctx.newSocket(nodeA, SocketKind.OUTPUT, 'out');
+
+const nodeB = ctx.newEntity({ label: 'Sink' });
+const inB = ctx.newSocket(nodeB, SocketKind.INPUT, 'in');
+
+ctx.newLink(outA, inB);
+ctx.setSocketValue(outA.id, 'Data');
+```
+
+## Core Elements
+
+- **`Context`**: Central state manager.
+- **`Entity`**: Graph node with `inner` data.
+- **`Socket`**: Reactive connection point (`INPUT`/`OUTPUT`).
+- **`Link`**: Connection between sockets.
+- **`Group`**: Hierarchical container.
+
+For comprehensive documentation on architecture, spatial indexing, and history management, see the [Full README](https://github.com/stulyproject/anode?tab=readme-ov-file).

package/dist/core/context.d.ts

@@ -3,13 +3,29 @@ import { QuadTree } from "./layout.js";
 import { HistoryAction, HistoryManager } from "./history.js";
 
 //#region src/core/context.d.ts
+/** Callback triggered when an entity is created or dropped */
 type EntityCallback<T> = (entity: Entity<T>) => void;
+/** Callback triggered when a link is created, dropped, or updated */
 type LinkCallback = (link: Link) => void;
+/** Callback triggered when a socket is created, dropped, or moved */
 type SocketCallback = (socket: Socket) => void;
+/** Callback triggered when an entity moves, providing its new world position */
 type EntityMoveCallback<T> = (entity: Entity<T>, pos: Vec2) => void;
+/** Callback triggered when a group is created or dropped */
 type GroupCallback = (group: Group) => void;
+/** Callback triggered when a socket value is updated */
 type SocketValueCallback = (socket: Socket, value: any) => void;
+/** A unique handle used to unregister a listener */
 type CallbackHandle = number;
+/**
+ * The central engine for Anode.
+ *
+ * Context manages the lifecycle of entities, sockets, links, and groups.
+ * It handles reactive data propagation, spatial indexing (QuadTree),
+ * and transactional history (undo/redo).
+ *
+ * @template T The type of the custom data associated with entities.
+ */
 declare class Context<T = any> {
   private eid;
   private lid;
@@ -34,15 +50,20 @@ declare class Context<T = any> {
   private groupCreateCallbacks;
   private groupDropCallbacks;
   private bulkChangeCallbacks;
+  /** Map of all entities indexed by their unique ID */
   entities: Map<number, Entity<T>>;
+  /** Map of all links indexed by their unique ID */
   links: Map<number, Link>;
+  /** Map of all sockets indexed by their unique ID */
   sockets: Map<number, Socket>;
+  /** Map of all groups indexed by their unique ID */
   groups: Map<number, Group>;
+  /** Spatial index for efficient querying and culling */
   quadTree: QuadTree<number>;
+  /** Manager for undo/redo history */
   history: HistoryManager;
   private isApplyingHistory;
   private currentBatch;
-  private currentUndoBatch;
   private isBatchingQuadTree;
   private getNextEid;
   private getNextLid;
@@ -50,48 +71,146 @@ declare class Context<T = any> {
   private getNextGid;
   private getNextCallbackHandle;
   private setupEntity;
+  /** Triggers all bulk change listeners. Usually called after undo/redo or batch operations. */
   notifyBulkChange(): void;
+  /**
+   * Registers a callback that is triggered when multiple changes occur at once.
+   * Useful for syncing UI state that doesn't need to respond to every individual mutation.
+   */
   registerBulkChangeListener(cb: () => void): CallbackHandle;
+  /**
+   * Sets the value of a specific socket and triggers reactive propagation.
+   *
+   * **Side Effects:**
+   * 1. Updates the `socket.value`.
+   * 2. Triggers `SocketValueListener` for the socket.
+   * 3. If the socket is an `OUTPUT`, pushes the value to all linked `INPUT` sockets recursively.
+   *
+   * @param socketId The unique ID of the socket.
+   * @param value The new value to assign.
+   */
   setSocketValue(socketId: number, value: any): void;
+  /** Registers a listener for socket value changes. */
   registerSocketValueListener(cb: SocketValueCallback): CallbackHandle;
+  /**
+   * Records a custom set of actions to the history stack.
+   * Internally used by all mutation methods.
+   */
   record(doActions: HistoryAction | HistoryAction[], undoActions: HistoryAction | HistoryAction[], label?: string): void;
+  /**
+   * Executes a function as a single atomic transaction in the history stack.
+   *
+   * During the batch:
+   * 1. Individual operations do not record separate history entries.
+   * 2. QuadTree updates are suspended until the end of the batch.
+   * 3. A single snapshot-based history entry is created for the entire operation.
+   *
+   * @param fn The function containing multiple mutations.
+   * @param label A human-readable label for the history entry (e.g., "Layout Graph").
+   */
   batch(fn: () => void, label?: string): void;
+  /** Reverts the last recorded transaction. */
   undo(): void;
+  /** Re-applies the last undone transaction. */
   redo(): void;
   private applyAction;
+  /** Registers a listener for entity creation. */
   registerEntityCreateListener(cb: EntityCallback<T>): CallbackHandle;
+  /** Registers a listener for entity deletion. */
   registerEntityDropListener(cb: EntityCallback<T>): CallbackHandle;
+  /** Registers a listener for entity movements (absolute position). */
   registerEntityMoveListener(cb: EntityMoveCallback<T>): CallbackHandle;
+  /** Registers a listener for socket movements (relative offset changes). */
   registerSocketMoveListener(cb: SocketCallback): CallbackHandle;
+  /** Triggers all socket move listeners. */
   notifySocketMove(socket: Socket): void;
+  /** Registers a listener for link creation. */
   registerLinkCreateListener(cb: LinkCallback): CallbackHandle;
+  /** Registers a listener for link deletion. */
   registerLinkDropListener(cb: LinkCallback): CallbackHandle;
+  /** Registers a listener for link updates (reconnections, waypoints). */
   registerLinkUpdateListener(cb: LinkCallback): CallbackHandle;
+  /** Registers a listener for socket creation. */
   registerSocketCreateListener(cb: SocketCallback): CallbackHandle;
+  /** Registers a listener for socket deletion. */
   registerSocketDropListener(cb: SocketCallback): CallbackHandle;
+  /** Registers a listener for group creation. */
   registerGroupCreateListener(cb: GroupCallback): CallbackHandle;
+  /** Registers a listener for group deletion. */
   registerGroupDropListener(cb: GroupCallback): CallbackHandle;
+  /**
+   * Unregisters a listener using the handle returned by the registration method.
+   * @returns true if the listener was successfully removed.
+   */
   unregisterListener(handle: CallbackHandle): boolean;
+  /** Creates and returns a new group. */
   newGroup(name?: string): Group;
+  /**
+   * Drops a group.
+   *
+   * **Side Effects:**
+   * 1. Detaches all child entities and groups (they remain in the context).
+   * 2. Removes the group from its parent group if applicable.
+   * 3. Triggers `GroupDropListener`.
+   */
   dropGroup(group: Group): void;
+  /** Calculates the absolute world position of an entity by traversing its parent group hierarchy. */
   getWorldPosition(entityId: number): Vec2;
+  /** Calculates the absolute world position of a group by traversing its parent group hierarchy. */
   getGroupWorldPosition(groupId: number): Vec2;
+  /**
+   * Moves a group and triggers move notifications for all nested entities recursively.
+   * This handles the complex coordinate system updates during group drags.
+   */
   moveGroup(group: Group, dx: number, dy: number): void;
+  /** Adds an entity to a group. Automatically removes it from its previous group if necessary. */
   addToGroup(groupId: number, entityId: number): void;
+  /** Removes an entity from its parent group. */
   removeFromGroup(groupId: number, entityId: number): void;
+  /** Adds a group to a parent group, creating a nested hierarchy. */
   addGroupToGroup(parentGroupId: number, childGroupId: number): void;
+  /** Removes a group from its parent group. */
   removeGroupFromGroup(parentGroupId: number, childGroupId: number): void;
+  /**
+   * Rebuilds the QuadTree spatial index.
+   * Suspended if `isBatchingQuadTree` is true.
+   */
   updateQuadTree(): void;
+  /**
+   * Creates a new entity.
+   * @param inner Custom data associated with the entity.
+   * @param forcedId Optional forced ID (useful for synchronization/deserialization).
+   */
   newEntity(inner: T, forcedId?: number): Entity<T>;
+  /**
+   * Drops an entity and all its associated sockets and links.
+   * This is performed as a batched operation to ensure consistent history.
+   */
   dropEntity(entity: Entity<T>): void;
+  /** Adds a new socket to an entity. */
   newSocket(entity: Entity<T>, kind: SocketKind, name?: string, forcedId?: number): Socket;
+  /** Drops a socket and all links connected to it. */
   dropSocket(socket: Socket): void;
+  /**
+   * Creates a new link between two sockets.
+   * Fails if the connection is invalid (e.g., creating a cycle, connecting same entity, etc.).
+   */
   newLink(from: Socket, to: Socket, kind?: LinkKind, forcedId?: number, inner?: any): Link<any> | null;
+  /** Updates an existing link's source or target. */
   updateLink(link: Link, fromId?: number, toId?: number): void;
+  /** Sets custom routing waypoints for a link. */
   setLinkWaypoints(link: Link, waypoints: Vec2[]): void;
+  /**
+   * Validation logic for connections.
+   * Prevents self-loops, same-entity links, identical kind connections,
+   * duplicate links, and cycles.
+   */
   canLink(from: Socket, to: Socket): boolean;
+  /** Performs a cycle detection search in the graph. */
   detectCycle(from: Socket, to: Socket): boolean;
+  /** Deletes a link from the context. */
   dropLink(link: Link): void;
+  /** Serializes the entire context state into a JSON-compatible object. */
   toJSON(): {
     entities: {
       id: number;
@@ -134,6 +253,10 @@ declare class Context<T = any> {
       parentId: number | null;
     }[];
   };
+  /**
+   * Restores the context state from a serialized JSON object.
+   * **Note:** This clears the current state completely.
+   */
   fromJSON(data: any): void;
 }
 //#endregion

package/dist/core/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","names":[],"sources":["../../src/core/context.ts"],"mappings":"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"}
+{"version":3,"file":"context.d.ts","names":[],"sources":["../../src/core/context.ts"],"mappings":";;;;;;KAKY,cAAA,OAAqB,MAAA,EAAQ,MAAA,CAAO,CAAA;AAAhD;AAAA,KAEY,YAAA,IAAgB,IAAA,EAAM,IAAA;;KAEtB,cAAA,IAAkB,MAAA,EAAQ,MAAA;;KAE1B,kBAAA,OAAyB,MAAA,EAAQ,MAAA,CAAO,CAAA,GAAI,GAAA,EAAK,IAAA;;KAEjD,aAAA,IAAiB,KAAA,EAAO,KAAA;;KAExB,mBAAA,IAAuB,MAAA,EAAQ,MAAA,EAAQ,KAAA;AARnD;AAAA,KAUY,cAAA;;;;AARZ;;;;;AAEA;cAiBa,OAAA;EAAA,QACH,GAAA;EAAA,QACA,GAAA;EAAA,QACA,GAAA;EAAA,QACA,GAAA;EAAA,QAEA,QAAA;EAAA,QACA,QAAA;EAAA,QACA,QAAA;EAAA,QACA,QAAA;EAAA,QAEA,WAAA;EAAA,QACA,eAAA;EAAA,QAEA,qBAAA;EAAA,QACA,mBAAA;EAAA,QACA,mBAAA;EAAA,QACA,mBAAA;EAAA,QACA,oBAAA;EAAA,QAEA,mBAAA;EAAA,QACA,iBAAA;EAAA,QACA,mBAAA;EAAA,QAEA,qBAAA;EAAA,QACA,mBAAA;EAAA,QAEA,oBAAA;EAAA,QACA,kBAAA;EAAA,QACA,mBAAA;EA1CiC;EA6CzC,QAAA,EAAU,GAAA,SAAY,MAAA,CAAO,CAAA;EA7CoB;EA+CjD,KAAA,EAAO,GAAA,SAAY,IAAA;EA/CwC;EAiD3D,OAAA,EAAS,GAAA,SAAY,MAAA;EA/CG;EAiDxB,MAAA,EAAQ,GAAA,SAAY,KAAA;EAjDI;EAoDxB,QAAA,EAAU,QAAA;EAzCC;EA2CX,OAAA,EAAS,cAAA;EAAA,QAED,iBAAA;EAAA,QACA,YAAA;EAAA,QACA,kBAAA;EAAA,QAEA,UAAA;EAAA,QAGA,UAAA;EAAA,QAGA,UAAA;EAAA,QAGA,UAAA;EAAA,QAGA,qBAAA;EAAA,QAIA,WAAA;EA3BA;EAyCR,gBAAA,CAAA;EApCS;;;;EAkDT,0BAAA,CAA2B,EAAA,eAAiB,cAAA;EAgDf;;;;;;;;;;;EA/B7B,cAAA,CAAe,QAAA,UAAkB,KAAA;EA6RF;EAzQ/B,2BAAA,CAA4B,EAAA,EAAI,mBAAA,GAAsB,cAAA;EAgR7B;;;;EAtQzB,MAAA,CACE,SAAA,EAAW,aAAA,GAAgB,aAAA,IAC3B,WAAA,EAAa,aAAA,GAAgB,aAAA,IAC7B,KAAA;EA4R6B;;;;;;;;;;;EAjQ/B,KAAA,CAAM,EAAA,cAAgB,KAAA;EAmVL;EAlTjB,IAAA,CAAA;EAgWwC;EA5UxC,IAAA,CAAA;EAAA,QAmBQ,WAAA;EAyb6B;EArTrC,4BAAA,CAA6B,EAAA,EAAI,cAAA,CAAe,CAAA,IAAK,cAAA;EAkW3B;EA3V1B,0BAAA,CAA2B,EAAA,EAAI,cAAA,CAAe,CAAA,IAAK,cAAA;EAwY1B;EAjYzB,0BAAA,CAA2B,EAAA,EAAI,kBAAA,CAAmB,CAAA,IAAK,cAAA;EAiYpB;EA1XnC,0BAAA,CAA2B,EAAA,EAAI,cAAA,GAAiB,cAAA;EAoa7B;EA7ZnB,gBAAA,CAAiB,MAAA,EAAQ,MAAA;EAgdnB;EArcN,0BAAA,CAA2B,EAAA,EAAI,YAAA,GAAe,cAAA;EAwc7B;EAjcjB,wBAAA,CAAyB,EAAA,EAAI,YAAA,GAAe,cAAA;EAoiBrB;EA7hBvB,0BAAA,CAA2B,EAAA,EAAI,YAAA,GAAe,cAAA;EAqkBhC;EA9jBd,4BAAA,CAA6B,EAAA,EAAI,cAAA,GAAiB,cAAA;EAmlBhC;EA5kBlB,0BAAA,CAA2B,EAAA,EAAI,cAAA,GAAiB,cAAA;EA2mBjC;EApmBf,2BAAA,CAA4B,EAAA,EAAI,aAAA,GAAgB,cAAA;;EAOhD,yBAAA,CAA0B,EAAA,EAAI,aAAA,GAAgB,cAAA;;;;;EAU9C,kBAAA,CAAmB,MAAA,EAAQ,cAAA;EA9cnB;EAqeR,QAAA,CAAS,IAAA,YAAiB,KAAA;EAlelB;;;;;;;;EAufR,SAAA,CAAU,KAAA,EAAO,KAAA;EA5eT;EAugBR,gBAAA,CAAiB,QAAA,WAAmB,IAAA;EApgB5B;EAuhBR,qBAAA,CAAsB,OAAA,WAAkB,IAAA;EArhBhC;;;;EA2iBR,SAAA,CAAU,KAAA,EAAO,KAAA,EAAO,EAAA,UAAY,EAAA;EApiB5B;EAmkBR,UAAA,CAAW,OAAA,UAAiB,QAAA;EAhkBlB;EA8kBV,eAAA,CAAgB,OAAA,UAAiB,QAAA;EA9kBJ;EAylB7B,eAAA,CAAgB,aAAA,UAAuB,YAAA;EAvlBhC;EAqmBP,oBAAA,CAAqB,aAAA,UAAuB,YAAA;EAnmB5C;;;;EAinBA,cAAA,CAAA;EA/mBoB;;;;;EAqoBpB,SAAA,CAAU,KAAA,EAAO,CAAA,EAAG,QAAA,YAAiB,MAAA,CAAA,CAAA;EA7nB7B;;;;EA0qBR,UAAA,CAAW,MAAA,EAAQ,MAAA,CAAO,CAAA;EA9pBlB;EA2sBR,SAAA,CAAU,MAAA,EAAQ,MAAA,CAAO,CAAA,GAAI,IAAA,EAAM,UAAA,EAAY,IAAA,WAAmB,QAAA,YAAiB,MAAA;EApsB3E;EA8uBR,UAAA,CAAW,MAAA,EAAQ,MAAA;EAltBnB;;;;EAmwBA,OAAA,CACE,IAAA,EAAM,MAAA,EACN,EAAA,EAAI,MAAA,EACJ,IAAA,GAAM,QAAA,EACN,QAAA,WACA,KAAA,SAAe,IAAA;EAvvBgB;EAwyBjC,UAAA,CAAW,IAAA,EAAM,IAAA,EAAM,MAAA,WAAiB,IAAA;EApxBR;EAs0BhC,gBAAA,CAAiB,IAAA,EAAM,IAAA,EAAM,SAAA,EAAW,IAAA;EAt0Bc;;;;;EA82BtD,OAAA,CAAQ,IAAA,EAAM,MAAA,EAAQ,EAAA,EAAI,MAAA;EAl2BK;EAu3B/B,WAAA,CAAY,IAAA,EAAM,MAAA,EAAQ,EAAA,EAAI,MAAA;EAt3B5B;EAq5BF,QAAA,CAAS,IAAA,EAAM,IAAA;EA13BT;EA65BN,MAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA9oBA;;;;EAmrBA,QAAA,CAAS,IAAA;AAAA"}

package/dist/core/context.js

@@ -3,6 +3,15 @@ import { QuadTree, Rect } from "./layout.js";
 import { HistoryManager } from "./history.js";
 
 //#region src/core/context.ts
+/**
+* The central engine for Anode.
+*
+* Context manages the lifecycle of entities, sockets, links, and groups.
+* It handles reactive data propagation, spatial indexing (QuadTree),
+* and transactional history (undo/redo).
+*
+* @template T The type of the custom data associated with entities.
+*/
 var Context = class {
 	eid = 0;
 	lid = 0;
@@ -27,15 +36,20 @@ var Context = class {
 	groupCreateCallbacks = /* @__PURE__ */ new Map();
 	groupDropCallbacks = /* @__PURE__ */ new Map();
 	bulkChangeCallbacks = /* @__PURE__ */ new Map();
+	/** Map of all entities indexed by their unique ID */
 	entities = /* @__PURE__ */ new Map();
+	/** Map of all links indexed by their unique ID */
 	links = /* @__PURE__ */ new Map();
+	/** Map of all sockets indexed by their unique ID */
 	sockets = /* @__PURE__ */ new Map();
+	/** Map of all groups indexed by their unique ID */
 	groups = /* @__PURE__ */ new Map();
+	/** Spatial index for efficient querying and culling */
 	quadTree = new QuadTree(new Rect(-1e5, -1e5, 2e5, 2e5));
+	/** Manager for undo/redo history */
 	history = new HistoryManager();
 	isApplyingHistory = false;
 	currentBatch = null;
-	currentUndoBatch = null;
 	isBatchingQuadTree = false;
 	getNextEid() {
 		return this.freeEids.pop() ?? this.eid++;
@@ -53,7 +67,7 @@ var Context = class {
 		return this.freeCallbackIds.pop() ?? this.callbackIds++;
 	}
 	setupEntity(entity) {
-		entity.onMove((pos) => {
+		entity.onMove((_pos) => {
 			this.updateQuadTree();
 			for (const cb of this.entityMoveCallbacks.values()) try {
 				cb(entity, this.getWorldPosition(entity.id));
@@ -62,6 +76,7 @@ var Context = class {
 			}
 		});
 	}
+	/** Triggers all bulk change listeners. Usually called after undo/redo or batch operations. */
 	notifyBulkChange() {
 		for (const cb of this.bulkChangeCallbacks.values()) try {
 			cb();
@@ -69,11 +84,26 @@ var Context = class {
 			console.error(err);
 		}
 	}
+	/**
+	* Registers a callback that is triggered when multiple changes occur at once.
+	* Useful for syncing UI state that doesn't need to respond to every individual mutation.
+	*/
 	registerBulkChangeListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.bulkChangeCallbacks.set(handle, cb);
 		return handle;
 	}
+	/**
+	* Sets the value of a specific socket and triggers reactive propagation.
+	*
+	* **Side Effects:**
+	* 1. Updates the `socket.value`.
+	* 2. Triggers `SocketValueListener` for the socket.
+	* 3. If the socket is an `OUTPUT`, pushes the value to all linked `INPUT` sockets recursively.
+	*
+	* @param socketId The unique ID of the socket.
+	* @param value The new value to assign.
+	*/
 	setSocketValue(socketId, value) {
 		const socket = this.sockets.get(socketId);
 		if (!socket) return;
@@ -83,11 +113,16 @@ var Context = class {
 			for (const link of this.links.values()) if (link.from === socketId) this.setSocketValue(link.to, value);
 		}
 	}
+	/** Registers a listener for socket value changes. */
 	registerSocketValueListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.socketValueCallbacks.set(handle, cb);
 		return handle;
 	}
+	/**
+	* Records a custom set of actions to the history stack.
+	* Internally used by all mutation methods.
+	*/
 	record(doActions, undoActions, label) {
 		if (this.isApplyingHistory) return;
 		if (this.currentBatch) return;
@@ -100,6 +135,17 @@ var Context = class {
 			timestamp: Date.now()
 		});
 	}
+	/**
+	* Executes a function as a single atomic transaction in the history stack.
+	*
+	* During the batch:
+	* 1. Individual operations do not record separate history entries.
+	* 2. QuadTree updates are suspended until the end of the batch.
+	* 3. A single snapshot-based history entry is created for the entire operation.
+	*
+	* @param fn The function containing multiple mutations.
+	* @param label A human-readable label for the history entry (e.g., "Layout Graph").
+	*/
 	batch(fn, label) {
 		if (this.currentBatch) {
 			fn();
@@ -132,6 +178,7 @@ var Context = class {
 			this.isBatchingQuadTree = oldBatchingQT;
 		}
 	}
+	/** Reverts the last recorded transaction. */
 	undo() {
 		const cmd = this.history.undoStack.pop();
 		if (!cmd) return;
@@ -148,6 +195,7 @@ var Context = class {
 			this.isBatchingQuadTree = false;
 		}
 	}
+	/** Re-applies the last undone transaction. */
 	redo() {
 		const cmd = this.history.redoStack.pop();
 		if (!cmd) return;
@@ -284,26 +332,31 @@ var Context = class {
 			}
 		}
 	}
+	/** Registers a listener for entity creation. */
 	registerEntityCreateListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.entityCreateCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for entity deletion. */
 	registerEntityDropListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.entityDropCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for entity movements (absolute position). */
 	registerEntityMoveListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.entityMoveCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for socket movements (relative offset changes). */
 	registerSocketMoveListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.socketMoveCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Triggers all socket move listeners. */
 	notifySocketMove(socket) {
 		for (const cb of this.socketMoveCallbacks.values()) try {
 			cb(socket);
@@ -311,41 +364,52 @@ var Context = class {
 			console.error(err);
 		}
 	}
+	/** Registers a listener for link creation. */
 	registerLinkCreateListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.linkCreateCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for link deletion. */
 	registerLinkDropListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.linkDropCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for link updates (reconnections, waypoints). */
 	registerLinkUpdateListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.linkUpdateCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for socket creation. */
 	registerSocketCreateListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.socketCreateCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for socket deletion. */
 	registerSocketDropListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.socketDropCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for group creation. */
 	registerGroupCreateListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.groupCreateCallbacks.set(handle, cb);
 		return handle;
 	}
+	/** Registers a listener for group deletion. */
 	registerGroupDropListener(cb) {
 		const handle = this.getNextCallbackHandle();
 		this.groupDropCallbacks.set(handle, cb);
 		return handle;
 	}
+	/**
+	* Unregisters a listener using the handle returned by the registration method.
+	* @returns true if the listener was successfully removed.
+	*/
 	unregisterListener(handle) {
 		if (this.linkCreateCallbacks.delete(handle) || this.linkDropCallbacks.delete(handle) || this.linkUpdateCallbacks.delete(handle) || this.entityCreateCallbacks.delete(handle) || this.entityDropCallbacks.delete(handle) || this.entityMoveCallbacks.delete(handle) || this.socketCreateCallbacks.delete(handle) || this.socketDropCallbacks.delete(handle) || this.socketMoveCallbacks.delete(handle) || this.groupCreateCallbacks.delete(handle) || this.groupDropCallbacks.delete(handle) || this.bulkChangeCallbacks.delete(handle)) {
 			this.freeCallbackIds.push(handle);
@@ -353,6 +417,7 @@ var Context = class {
 		}
 		return false;
 	}
+	/** Creates and returns a new group. */
 	newGroup(name = "") {
 		const group = new Group(this.getNextGid(), name);
 		this.groups.set(group.id, group);
@@ -363,6 +428,14 @@ var Context = class {
 		}
 		return group;
 	}
+	/**
+	* Drops a group.
+	*
+	* **Side Effects:**
+	* 1. Detaches all child entities and groups (they remain in the context).
+	* 2. Removes the group from its parent group if applicable.
+	* 3. Triggers `GroupDropListener`.
+	*/
 	dropGroup(group) {
 		if (this.groups.delete(group.id)) {
 			if (group.parentId !== null) this.removeGroupFromGroup(group.parentId, group.id);
@@ -383,6 +456,7 @@ var Context = class {
 			this.updateQuadTree();
 		}
 	}
+	/** Calculates the absolute world position of an entity by traversing its parent group hierarchy. */
 	getWorldPosition(entityId) {
 		const entity = this.entities.get(entityId);
 		if (!entity) return new Vec2();
@@ -397,6 +471,7 @@ var Context = class {
 		}
 		return pos;
 	}
+	/** Calculates the absolute world position of a group by traversing its parent group hierarchy. */
 	getGroupWorldPosition(groupId) {
 		const group = this.groups.get(groupId);
 		if (!group) return new Vec2();
@@ -411,6 +486,10 @@ var Context = class {
 		}
 		return pos;
 	}
+	/**
+	* Moves a group and triggers move notifications for all nested entities recursively.
+	* This handles the complex coordinate system updates during group drags.
+	*/
 	moveGroup(group, dx, dy) {
 		const oldBatching = this.isBatchingQuadTree;
 		this.isBatchingQuadTree = true;
@@ -433,6 +512,7 @@ var Context = class {
 			this.updateQuadTree();
 		}
 	}
+	/** Adds an entity to a group. Automatically removes it from its previous group if necessary. */
 	addToGroup(groupId, entityId) {
 		const group = this.groups.get(groupId);
 		const entity = this.entities.get(entityId);
@@ -443,6 +523,7 @@ var Context = class {
 			this.updateQuadTree();
 		}
 	}
+	/** Removes an entity from its parent group. */
 	removeFromGroup(groupId, entityId) {
 		const group = this.groups.get(groupId);
 		const entity = this.entities.get(entityId);
@@ -452,6 +533,7 @@ var Context = class {
 			this.updateQuadTree();
 		}
 	}
+	/** Adds a group to a parent group, creating a nested hierarchy. */
 	addGroupToGroup(parentGroupId, childGroupId) {
 		const parent = this.groups.get(parentGroupId);
 		const child = this.groups.get(childGroupId);
@@ -462,6 +544,7 @@ var Context = class {
 			this.updateQuadTree();
 		}
 	}
+	/** Removes a group from its parent group. */
 	removeGroupFromGroup(parentGroupId, childGroupId) {
 		const parent = this.groups.get(parentGroupId);
 		const child = this.groups.get(childGroupId);
@@ -471,6 +554,10 @@ var Context = class {
 			this.updateQuadTree();
 		}
 	}
+	/**
+	* Rebuilds the QuadTree spatial index.
+	* Suspended if `isBatchingQuadTree` is true.
+	*/
 	updateQuadTree() {
 		if (this.isBatchingQuadTree) return;
 		this.quadTree.clear();
@@ -480,6 +567,11 @@ var Context = class {
 			for (const socket of entity.sockets.values()) this.quadTree.insert(new Vec2(entityWorldPos.x + socket.offset.x, entityWorldPos.y + socket.offset.y), entity.id);
 		}
 	}
+	/**
+	* Creates a new entity.
+	* @param inner Custom data associated with the entity.
+	* @param forcedId Optional forced ID (useful for synchronization/deserialization).
+	*/
 	newEntity(inner, forcedId) {
 		const ett = new Entity(forcedId ?? this.getNextEid(), inner);
 		this.entities.set(ett.id, ett);
@@ -506,6 +598,10 @@ var Context = class {
 		this.updateQuadTree();
 		return ett;
 	}
+	/**
+	* Drops an entity and all its associated sockets and links.
+	* This is performed as a batched operation to ensure consistent history.
+	*/
 	dropEntity(entity) {
 		if (this.entities.has(entity.id)) this.batch(() => {
 			this.record({
@@ -533,6 +629,7 @@ var Context = class {
 			this.updateQuadTree();
 		}, "Drop Entity");
 	}
+	/** Adds a new socket to an entity. */
 	newSocket(entity, kind, name = "", forcedId) {
 		const socket = new Socket(forcedId ?? this.getNextSid(), entity.id, kind, name);
 		this.sockets.set(socket.id, socket);
@@ -560,6 +657,7 @@ var Context = class {
 		}
 		return socket;
 	}
+	/** Drops a socket and all links connected to it. */
 	dropSocket(socket) {
 		if (this.sockets.delete(socket.id)) {
 			if (!this.isApplyingHistory) this.record({
@@ -588,6 +686,10 @@ var Context = class {
 			}
 		}
 	}
+	/**
+	* Creates a new link between two sockets.
+	* Fails if the connection is invalid (e.g., creating a cycle, connecting same entity, etc.).
+	*/
 	newLink(from, to, kind = LinkKind.BEZIER, forcedId, inner = {}) {
 		if (!this.canLink(from, to)) return null;
 		const link = new Link(forcedId ?? this.getNextLid(), from.id, to.id, kind, inner);
@@ -616,6 +718,7 @@ var Context = class {
 		}
 		return link;
 	}
+	/** Updates an existing link's source or target. */
 	updateLink(link, fromId, toId) {
 		const oldFrom = link.from;
 		const oldTo = link.to;
@@ -668,6 +771,7 @@ var Context = class {
 			console.error(err);
 		}
 	}
+	/** Sets custom routing waypoints for a link. */
 	setLinkWaypoints(link, waypoints) {
 		const oldWaypoints = link.waypoints.map((p) => ({
 			x: p.x,
@@ -715,6 +819,11 @@ var Context = class {
 			console.error(err);
 		}
 	}
+	/**
+	* Validation logic for connections.
+	* Prevents self-loops, same-entity links, identical kind connections,
+	* duplicate links, and cycles.
+	*/
 	canLink(from, to) {
 		if (from.id === to.id) return false;
 		if (from.entityId === to.entityId) return false;
@@ -723,6 +832,7 @@ var Context = class {
 		if (this.detectCycle(from, to)) return false;
 		return true;
 	}
+	/** Performs a cycle detection search in the graph. */
 	detectCycle(from, to) {
 		const visited = /* @__PURE__ */ new Set();
 		const stack = [to.entityId];
@@ -742,6 +852,7 @@ var Context = class {
 		}
 		return false;
 	}
+	/** Deletes a link from the context. */
 	dropLink(link) {
 		if (this.links.delete(link.id)) {
 			if (!this.isApplyingHistory) this.record({
@@ -767,6 +878,7 @@ var Context = class {
 			}
 		}
 	}
+	/** Serializes the entire context state into a JSON-compatible object. */
 	toJSON() {
 		return {
 			entities: Array.from(this.entities.values()).map((e) => ({
@@ -811,6 +923,10 @@ var Context = class {
 			}))
 		};
 	}
+	/**
+	* Restores the context state from a serialized JSON object.
+	* **Note:** This clears the current state completely.
+	*/
 	fromJSON(data) {
 		this.entities.clear();
 		this.links.clear();