@rool-dev/client 0.3.1-dev.e2c481d → 0.3.1-dev.ff89f50

package/dist/graph.js

@@ -1,6 +1,6 @@
 // =============================================================================
 // Graph
-// First-class Graph object with node/edge operations, undo/redo, and events
+// First-class Graph object with object/edge operations, undo/redo, and events
 // =============================================================================
 import { immutableJSONPatch } from 'immutable-json-patch';
 import { EventEmitter } from './event-emitter.js';
@@ -18,7 +18,7 @@ export function generateEntityId() {
  * First-class Graph object.
  *
  * Features:
- * - High-level node/edge operations
+ * - High-level object/edge operations
  * - Built-in undo/redo with checkpoints
  * - Metadata management
  * - Event emission for state changes
@@ -36,10 +36,6 @@ export class RoolGraph extends EventEmitter {
     // Undo/redo stacks
     undoStack = [];
     redoStack = [];
-    // Patch batching
-    pendingPatch = [];
-    patchScheduled = false;
-    patchSettled = Promise.resolve();
     // Subscription state
     _isSubscribed = false;
     constructor(config) {
@@ -114,7 +110,6 @@ export class RoolGraph extends EventEmitter {
         this.unsubscribe();
         this.undoStack = [];
         this.redoStack = [];
-        this.pendingPatch = [];
         this.removeAllListeners();
     }
     // ===========================================================================
@@ -152,14 +147,11 @@ export class RoolGraph extends EventEmitter {
     }
     /**
      * Undo to the previous checkpoint.
-     * Waits for any pending patches to settle before applying.
      * @returns true if undo was performed
      */
     async undo() {
         if (!this.canUndo())
             return false;
-        // Wait for pending patches before replacing state
-        await this.patchSettled;
         // Save current state to redo stack
         const currentEntry = {
             timestamp: Date.now(),
@@ -173,7 +165,7 @@ export class RoolGraph extends EventEmitter {
         // Sync to server - resync on failure
         try {
             await this.graphqlClient.setGraph(this._id, this._data);
-            this.emit('reset', { source: 'local' });
+            this.emit('reset', { source: 'local_user' });
         }
         catch (error) {
             console.error('[Graph] Failed to sync undo to server:', error);
@@ -183,14 +175,11 @@ export class RoolGraph extends EventEmitter {
     }
     /**
      * Redo a previously undone action.
-     * Waits for any pending patches to settle before applying.
      * @returns true if redo was performed
      */
     async redo() {
         if (!this.canRedo())
             return false;
-        // Wait for pending patches before replacing state
-        await this.patchSettled;
         // Save current state to undo stack
         const currentEntry = {
             timestamp: Date.now(),
@@ -204,7 +193,7 @@ export class RoolGraph extends EventEmitter {
         // Sync to server - resync on failure
         try {
             await this.graphqlClient.setGraph(this._id, this._data);
-            this.emit('reset', { source: 'local' });
+            this.emit('reset', { source: 'local_user' });
         }
         catch (error) {
             console.error('[Graph] Failed to sync redo to server:', error);
@@ -221,213 +210,330 @@ export class RoolGraph extends EventEmitter {
         this.redoStack = [];
     }
     // ===========================================================================
-    // Node Operations
+    // Object Operations
     // ===========================================================================
     /**
-     * Get a node by ID.
-     * @throws Error if node not found
+     * Get an object's data by ID.
+     * Returns just the data portion (RoolObject), not the full entry with meta/links.
+     * @throws Error if object not found
      */
-    getNode(nodeId) {
-        const node = this._data.nodes[nodeId];
-        if (!node) {
-            throw new Error(`Node ${nodeId} not found`);
+    getObject(objectId) {
+        const entry = this._data.objects[objectId];
+        if (!entry) {
+            throw new Error(`Object ${objectId} not found`);
         }
-        return node;
+        return entry.data;
     }
     /**
-     * Get a node by ID, or undefined if not found.
+     * Get an object's data by ID, or undefined if not found.
      */
-    getNodeOrUndefined(nodeId) {
-        return this._data.nodes[nodeId];
+    getObjectOrUndefined(objectId) {
+        return this._data.objects[objectId]?.data;
     }
     /**
-     * Get all nodes of a specific type.
+     * Get an object's metadata (position, UI state, etc).
      */
-    getNodesByType(type) {
-        return Object.values(this._data.nodes).filter(node => node.type === type);
+    getObjectMeta(objectId) {
+        const entry = this._data.objects[objectId];
+        if (!entry) {
+            throw new Error(`Object ${objectId} not found`);
+        }
+        return entry.meta;
     }
     /**
-     * Get all node IDs.
+     * Get all objects of a specific type.
      */
-    getNodeIds() {
-        return Object.keys(this._data.nodes);
+    getObjectsByType(type) {
+        return Object.values(this._data.objects)
+            .filter(entry => entry.data.type === type)
+            .map(entry => entry.data);
     }
     /**
-     * Add a new node.
+     * Get all object IDs.
      */
-    addNode(nodeId, node) {
-        this._data.nodes[nodeId] = node;
-        const ops = [{ op: 'add', path: `/nodes/${nodeId}`, value: node }];
-        this.sendPatch(ops);
-        this.emit('patch', { ops, source: 'local' });
+    getObjectIds() {
+        return Object.keys(this._data.objects);
     }
     /**
-     * Update an existing node.
-     * @param updates - Partial node data to merge
-     * @param persist - If false, update local state only (for drag/animation)
+     * Create a new object with optional AI generation.
+     * @param options.type - The object type (required)
+     * @param options.fields - Object fields (optional). Use {{placeholder}} for AI-generated content.
+     * @param options.meta - Client-private metadata (optional). Hidden from AI operations.
+     * @param options.prompt - AI prompt for content generation (optional).
+     * @returns The generated object ID
      */
-    updateNode(nodeId, updates) {
-        const node = this._data.nodes[nodeId];
-        if (!node) {
-            throw new Error(`Node ${nodeId} not found for update`);
+    async createObject(options) {
+        const objectId = generateEntityId();
+        const { type, fields, meta, prompt } = options;
+        // Build the entry for local state
+        const entry = {
+            meta: meta ?? {},
+            links: {},
+            data: { type, ...fields },
+        };
+        // Update local state immediately (optimistic)
+        this._data.objects[objectId] = entry;
+        this.emit('objectCreated', { objectId, object: entry.data, source: 'local_user' });
+        // Await server call
+        try {
+            const message = await this.graphqlClient.createObject(this.id, objectId, type, fields, meta, prompt);
+            return { id: objectId, message };
         }
-        // Merge updates locally
-        Object.assign(node, updates);
-        // Optimization: If only _meta is being updated, send a smaller patch
-        const updateKeys = Object.keys(updates);
-        let ops;
-        if (updateKeys.length === 1 && updateKeys[0] === '_meta' && updates._meta) {
-            // "add" is an upsert operation, so it works regardless of whether the _meta exists or not
-            ops = [{ op: 'add', path: `/nodes/${nodeId}/_meta`, value: updates._meta }];
+        catch (error) {
+            console.error('[Graph] Failed to create object:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
         }
-        else {
-            ops = [{ op: 'replace', path: `/nodes/${nodeId}`, value: node }];
+    }
+    /**
+     * Update an existing object.
+     * @param objectId - The ID of the object to update
+     * @param options.type - Optional new type for the object
+     * @param options.fields - Fields to add or update. Use {{placeholder}} for AI-generated content.
+     * @param options.meta - Client-private metadata to merge. Hidden from AI operations.
+     * @param options.prompt - AI prompt for content editing (optional).
+     */
+    async updateObject(objectId, options) {
+        const entry = this._data.objects[objectId];
+        if (!entry) {
+            throw new Error(`Object ${objectId} not found for update`);
+        }
+        const { type, fields, meta } = options;
+        // Build local updates
+        if (type) {
+            entry.data.type = type;
+        }
+        if (fields) {
+            Object.assign(entry.data, fields);
+        }
+        if (meta) {
+            entry.meta = { ...entry.meta, ...meta };
+        }
+        // Emit semantic event with updated object
+        if (type || fields || meta) {
+            this.emit('objectUpdated', { objectId, object: entry.data, source: 'local_user' });
+        }
+        // Await server call
+        try {
+            return await this.graphqlClient.updateObject(this.id, objectId, type, fields, meta, options.prompt);
+        }
+        catch (error) {
+            console.error('[Graph] Failed to update object:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
         }
-        this.sendPatch(ops);
-        this.emit('patch', { ops, source: 'local' });
     }
     /**
-     * Delete nodes by IDs.
-     * Also removes any edges connected to the deleted nodes.
+     * Delete objects by IDs.
+     * Outbound links are automatically deleted with the object.
+     * Inbound links become orphans (tolerated).
      */
-    async deleteNodes(nodeIds) {
-        if (nodeIds.length === 0)
+    async deleteObjects(objectIds) {
+        if (objectIds.length === 0)
             return;
-        const patch = [];
-        const nodeIdSet = new Set(nodeIds);
-        // Remove edges connected to any deleted node (local state)
-        for (const [edgeId, edge] of Object.entries(this._data.edges)) {
-            const hasDeletedSource = edge.sources.some(s => nodeIdSet.has(s));
-            const hasDeletedTarget = edge.targets.some(t => nodeIdSet.has(t));
-            if (hasDeletedSource || hasDeletedTarget) {
-                delete this._data.edges[edgeId];
-                patch.push({ op: 'remove', path: `/edges/${edgeId}` });
+        const deletedObjectIds = [];
+        // Collect edges that will be orphaned (for events)
+        const deletedEdges = [];
+        for (const objectId of objectIds) {
+            const entry = this._data.objects[objectId];
+            if (entry) {
+                // Collect outbound edges for deletion events
+                for (const [edgeType, targets] of Object.entries(entry.links)) {
+                    for (const targetId of Object.keys(targets)) {
+                        deletedEdges.push({ sourceId: objectId, targetId, edgeType });
+                    }
+                }
             }
         }
-        // Remove nodes (local state)
-        for (const nodeId of nodeIds) {
-            if (this._data.nodes[nodeId]) {
-                delete this._data.nodes[nodeId];
-                patch.push({ op: 'remove', path: `/nodes/${nodeId}` });
+        // Remove objects (local state)
+        for (const objectId of objectIds) {
+            if (this._data.objects[objectId]) {
+                delete this._data.objects[objectId];
+                deletedObjectIds.push(objectId);
             }
         }
-        if (patch.length > 0) {
-            this.emit('patch', { ops: patch, source: 'local' });
+        // Emit semantic events
+        for (const edge of deletedEdges) {
+            this.emit('edgeDeleted', { ...edge, source: 'local_user' });
+        }
+        for (const objectId of deletedObjectIds) {
+            this.emit('objectDeleted', { objectId, source: 'local_user' });
+        }
+        // Await server call
+        try {
+            await this.graphqlClient.deleteObjects(this.id, objectIds);
+        }
+        catch (error) {
+            console.error('[Graph] Failed to delete objects:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
         }
-        // Send to server via mutation
-        await this.graphqlClient.deleteNodes(this.id, nodeIds);
     }
     // ===========================================================================
     // Edge Operations
     // ===========================================================================
     /**
-     * Create an edge between nodes.
-     * @returns The generated edge ID
+     * Create a link between objects.
+     * Links are stored on the source object.
      */
-    async createEdge(sourceId, targetId, edgeType) {
-        const edgeId = generateEntityId();
-        const edge = {
-            sources: [sourceId],
-            targets: [targetId],
-            type: edgeType,
-            _meta: {},
-        };
+    async link(sourceId, targetId, edgeType) {
+        const entry = this._data.objects[sourceId];
+        if (!entry) {
+            throw new Error(`Source object ${sourceId} not found`);
+        }
         // Update local state immediately
-        this._data.edges[edgeId] = edge;
-        const ops = [{ op: 'add', path: `/edges/${edgeId}`, value: edge }];
-        this.emit('patch', { ops, source: 'local' });
-        // Send to server via mutation
-        await this.graphqlClient.createEdge(this.id, edgeId, sourceId, targetId, edgeType);
-        return edgeId;
+        if (!entry.links[edgeType]) {
+            entry.links[edgeType] = {};
+        }
+        entry.links[edgeType][targetId] = {};
+        const linkData = entry.links[edgeType][targetId];
+        this.emit('edgeCreated', { sourceId, targetId, edgeType, linkData, source: 'local_user' });
+        // Await server call
+        try {
+            await this.graphqlClient.link(this.id, sourceId, targetId, edgeType);
+        }
+        catch (error) {
+            console.error('[Graph] Failed to create link:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
     }
     /**
-     * Remove edges between two nodes.
-     * @returns true if any edges were removed
+     * Remove a link between two objects.
+     * @param edgeType - Optional: if provided, only removes that type; otherwise removes all links between the objects
+     * @returns true if any links were removed
      */
-    async deleteEdge(sourceId, targetId) {
-        const patch = [];
+    async unlink(sourceId, targetId, edgeType) {
+        const entry = this._data.objects[sourceId];
+        if (!entry) {
+            throw new Error(`Source object ${sourceId} not found`);
+        }
+        const deletedEdges = [];
         // Update local state
-        for (const [edgeId, edge] of Object.entries(this._data.edges)) {
-            if (edge.sources.includes(sourceId) && edge.targets.includes(targetId)) {
-                delete this._data.edges[edgeId];
-                patch.push({ op: 'remove', path: `/edges/${edgeId}` });
+        if (edgeType) {
+            // Remove specific edge type
+            if (entry.links[edgeType]?.[targetId] !== undefined) {
+                delete entry.links[edgeType][targetId];
+                deletedEdges.push({ edgeType });
             }
         }
-        if (patch.length > 0) {
-            this.emit('patch', { ops: patch, source: 'local' });
+        else {
+            // Remove all links from source to target
+            for (const [type, targets] of Object.entries(entry.links)) {
+                if (targets[targetId] !== undefined) {
+                    delete targets[targetId];
+                    deletedEdges.push({ edgeType: type });
+                }
+            }
+        }
+        // Emit semantic events
+        for (const edge of deletedEdges) {
+            this.emit('edgeDeleted', { sourceId, targetId, edgeType: edge.edgeType, source: 'local_user' });
+        }
+        // Await server call
+        try {
+            await this.graphqlClient.unlink(this.id, sourceId, targetId);
         }
-        // Send to server via mutation
-        await this.graphqlClient.deleteEdge(this.id, sourceId, targetId);
-        return patch.length > 0;
+        catch (error) {
+            console.error('[Graph] Failed to remove link:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        return deletedEdges.length > 0;
     }
     /**
-     * Get parent node IDs (nodes that have edges pointing TO this node).
+     * Get parent object IDs (objects that have edges pointing TO this object).
      * @param edgeType - Optional filter by edge type
      */
-    getParents(nodeId, edgeType) {
-        return Object.values(this._data.edges)
-            .filter(edge => edge.targets.includes(nodeId) &&
-            (!edgeType || edge.type === edgeType))
-            .flatMap(edge => edge.sources);
+    getParents(objectId, edgeType) {
+        const parents = [];
+        for (const [entryId, entry] of Object.entries(this._data.objects)) {
+            for (const [type, targets] of Object.entries(entry.links)) {
+                if ((!edgeType || type === edgeType) && objectId in targets) {
+                    parents.push(entryId);
+                    break; // Found a link, move to next object
+                }
+            }
+        }
+        return parents;
     }
     /**
-     * Get child node IDs (nodes that this node has edges pointing TO).
+     * Get child object IDs (objects that this object has edges pointing TO).
+     * Filters out orphan targets (targets that don't exist).
      * @param edgeType - Optional filter by edge type
      */
-    getChildren(nodeId, edgeType) {
-        return Object.values(this._data.edges)
-            .filter(edge => edge.sources.includes(nodeId) &&
-            (!edgeType || edge.type === edgeType))
-            .flatMap(edge => edge.targets);
-    }
-    /**
-     * Get an edge by ID.
-     */
-    getEdge(edgeId) {
-        return this._data.edges[edgeId];
+    getChildren(objectId, edgeType) {
+        const entry = this._data.objects[objectId];
+        if (!entry)
+            return [];
+        const children = [];
+        for (const [type, targets] of Object.entries(entry.links)) {
+            if (!edgeType || type === edgeType) {
+                for (const targetId of Object.keys(targets)) {
+                    // Filter orphans - only return existing targets
+                    if (this._data.objects[targetId]) {
+                        children.push(targetId);
+                    }
+                }
+            }
+        }
+        return children;
     }
     /**
-     * Get all edge IDs.
+     * Get all child object IDs including orphans (targets that may not exist).
+     * @param edgeType - Optional filter by edge type
      */
-    getEdgeIds() {
-        return Object.keys(this._data.edges);
+    getChildrenIncludingOrphans(objectId, edgeType) {
+        const entry = this._data.objects[objectId];
+        if (!entry)
+            return [];
+        const children = [];
+        for (const [type, targets] of Object.entries(entry.links)) {
+            if (!edgeType || type === edgeType) {
+                children.push(...Object.keys(targets));
+            }
+        }
+        return children;
     }
     // ===========================================================================
     // Metadata Operations
     // ===========================================================================
     /**
-     * Set a metadata value.
-     * Metadata is stored in _meta and hidden from AI operations.
+     * Set a graph-level metadata value.
+     * Metadata is stored in meta and hidden from AI operations.
      */
     setMetadata(key, value) {
-        if (!this._data._meta) {
-            this._data._meta = {};
+        if (!this._data.meta) {
+            this._data.meta = {};
         }
-        this._data._meta[key] = value;
-        // "add" is an upsert operation, so it works regardless of whether /_meta exists
-        this.sendPatch([{ op: 'add', path: '/_meta', value: this._data._meta }]);
+        this._data.meta[key] = value;
+        this.emit('metaUpdated', { meta: this._data.meta, source: 'local_user' });
+        // Fire-and-forget server call - errors trigger resync
+        this.graphqlClient.setGraphMeta(this.id, this._data.meta)
+            .catch((error) => {
+            console.error('[Graph] Failed to set graph meta:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+        });
     }
     /**
-     * Get a metadata value.
+     * Get a graph-level metadata value.
      */
     getMetadata(key) {
-        return this._data._meta?.[key];
+        return this._data.meta?.[key];
     }
     /**
-     * Get all metadata.
+     * Get all graph-level metadata.
      */
     getAllMetadata() {
-        return this._data._meta ?? {};
+        return this._data.meta ?? {};
     }
     // ===========================================================================
     // AI Operations
     // ===========================================================================
     /**
      * Send a prompt to the AI agent for graph manipulation.
-     * Waits for any pending patches to settle before sending.
      */
     async prompt(prompt, options) {
-        await this.patchSettled;
         return this.graphqlClient.promptGraph(this._id, prompt, options);
     }
     // ===========================================================================
@@ -494,21 +600,6 @@ export class RoolGraph extends EventEmitter {
     getData() {
         return this._data;
     }
-    /**
-     * Apply a raw JSON patch.
-     * Use sparingly - prefer semantic operations.
-     */
-    patch(operations) {
-        try {
-            this._data = immutableJSONPatch(this._data, operations);
-        }
-        catch (error) {
-            console.error('[Graph] Failed to apply patch:', error);
-            return;
-        }
-        this.sendPatch(operations);
-        this.emit('patch', { ops: operations, source: 'local' });
-    }
     // ===========================================================================
     // Event Handlers (called by RoolClient for routing)
     // ===========================================================================
@@ -526,8 +617,84 @@ export class RoolGraph extends EventEmitter {
             this.resyncFromServer(error instanceof Error ? error : new Error(String(error))).catch(() => { });
             return;
         }
-        const emitterSource = source === 'agent' ? 'remote_agent' : 'remote_user';
-        this.emit('patch', { ops: patch, source: emitterSource });
+        // Parse patch operations and emit semantic events
+        const changeSource = source === 'agent' ? 'remote_agent' : 'remote_user';
+        this.emitSemanticEventsFromPatch(patch, changeSource);
+    }
+    /**
+     * Parse JSON patch operations and emit semantic events.
+     * @internal
+     */
+    emitSemanticEventsFromPatch(patch, source) {
+        // Track which objects have been updated (to avoid duplicate events)
+        const updatedObjects = new Set();
+        for (const op of patch) {
+            const { path } = op;
+            // Object operations: /objects/{objectId}/...
+            if (path.startsWith('/objects/')) {
+                const parts = path.split('/');
+                const objectId = parts[2];
+                if (parts.length === 3) {
+                    // /objects/{objectId} - full object add or remove
+                    if (op.op === 'add') {
+                        const entry = this._data.objects[objectId];
+                        if (entry) {
+                            this.emit('objectCreated', { objectId, object: entry.data, source });
+                        }
+                    }
+                    else if (op.op === 'remove') {
+                        this.emit('objectDeleted', { objectId, source });
+                    }
+                }
+                else if (parts[3] === 'data') {
+                    // /objects/{objectId}/data/... - data field update
+                    if (!updatedObjects.has(objectId)) {
+                        const entry = this._data.objects[objectId];
+                        if (entry) {
+                            this.emit('objectUpdated', { objectId, object: entry.data, source });
+                            updatedObjects.add(objectId);
+                        }
+                    }
+                }
+                else if (parts[3] === 'links') {
+                    // /objects/{objectId}/links/{type}/{targetId}
+                    if (parts.length >= 6) {
+                        const edgeType = parts[4];
+                        const targetId = parts[5];
+                        if (op.op === 'add') {
+                            const linkData = this._data.objects[objectId]?.links[edgeType]?.[targetId] ?? {};
+                            this.emit('edgeCreated', { sourceId: objectId, targetId, edgeType, linkData, source });
+                        }
+                        else if (op.op === 'remove') {
+                            this.emit('edgeDeleted', { sourceId: objectId, targetId, edgeType, source });
+                        }
+                    }
+                    else if (parts.length === 5 && op.op === 'add') {
+                        // /objects/{objectId}/links/{type} - new link type object added
+                        const edgeType = parts[4];
+                        const targets = this._data.objects[objectId]?.links[edgeType] ?? {};
+                        for (const [targetId, linkData] of Object.entries(targets)) {
+                            this.emit('edgeCreated', { sourceId: objectId, targetId, edgeType, linkData: linkData, source });
+                        }
+                    }
+                }
+                else if (parts[3] === 'meta') {
+                    // /objects/{objectId}/meta/... - object meta update
+                    // Could emit an objectMeta event if needed, but for now treat as object update
+                    if (!updatedObjects.has(objectId)) {
+                        const entry = this._data.objects[objectId];
+                        if (entry) {
+                            this.emit('objectUpdated', { objectId, object: entry.data, source });
+                            updatedObjects.add(objectId);
+                        }
+                    }
+                }
+            }
+            // Graph metadata
+            else if (path === '/meta' || path.startsWith('/meta/')) {
+                this.emit('metaUpdated', { meta: this._data.meta, source });
+            }
+        }
     }
     /**
      * Handle a full graph reload from server.
@@ -547,32 +714,6 @@ export class RoolGraph extends EventEmitter {
     // ===========================================================================
     // Private Methods
     // ===========================================================================
-    sendPatch(patch) {
-        this.pendingPatch.push(...patch);
-        if (!this.patchScheduled) {
-            this.patchScheduled = true;
-            // Chain onto patchSettled so callers can await all pending patches
-            this.patchSettled = this.patchSettled.then(() => new Promise((resolve) => {
-                queueMicrotask(() => {
-                    const batch = this.pendingPatch;
-                    this.pendingPatch = [];
-                    this.patchScheduled = false;
-                    if (batch.length > 0) {
-                        this.graphqlClient
-                            .patch(this._id, batch)
-                            .catch((error) => {
-                            console.error('[Graph] Failed to send patch:', error);
-                            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
-                        })
-                            .finally(resolve);
-                    }
-                    else {
-                        resolve();
-                    }
-                });
-            }));
-        }
-    }
     async resyncFromServer(originalError) {
         console.warn('[Graph] Resyncing from server after sync failure');
         try {