@rool-dev/client 0.3.0 → 0.3.1-dev.34258b6

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/link 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/link operations
  * - Built-in undo/redo with checkpoints
  * - Metadata management
  * - Event emission for state changes
@@ -36,9 +36,6 @@ export class RoolGraph extends EventEmitter {
     // Undo/redo stacks
     undoStack = [];
     redoStack = [];
-    // Patch batching
-    pendingPatch = [];
-    patchScheduled = false;
     // Subscription state
     _isSubscribed = false;
     constructor(config) {
@@ -113,7 +110,6 @@ export class RoolGraph extends EventEmitter {
         this.unsubscribe();
         this.undoStack = [];
         this.redoStack = [];
-        this.pendingPatch = [];
         this.removeAllListeners();
     }
     // ===========================================================================
@@ -169,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);
@@ -197,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);
@@ -214,198 +210,322 @@ 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).
      */
-    deleteNodes(nodeIds) {
-        const patch = [];
-        const nodeIdSet = new Set(nodeIds);
-        // Remove edges connected to any deleted node
-        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}` });
+    async deleteObjects(objectIds) {
+        if (objectIds.length === 0)
+            return;
+        const deletedObjectIds = [];
+        // Collect links that will be orphaned (for events)
+        const deletedLinks = [];
+        for (const objectId of objectIds) {
+            const entry = this._data.objects[objectId];
+            if (entry) {
+                // Collect outbound links for deletion events
+                for (const [linkType, targets] of Object.entries(entry.links)) {
+                    for (const targetId of Object.keys(targets)) {
+                        deletedLinks.push({ sourceId: objectId, targetId, linkType });
+                    }
+                }
             }
         }
-        // Remove nodes
-        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.sendPatch(patch);
-            this.emit('patch', { ops: patch, source: 'local' });
+        // Emit semantic events
+        for (const link of deletedLinks) {
+            this.emit('unlinked', { ...link, 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;
         }
     }
     // ===========================================================================
-    // Edge Operations
+    // Link Operations
     // ===========================================================================
     /**
-     * Create an edge between nodes.
-     * @returns The generated edge ID
+     * Create a link between objects.
+     * Links are stored on the source object.
      */
-    linkNodes(sourceId, targetId, edgeType) {
-        const edgeId = generateEntityId();
-        const edge = {
-            sources: [sourceId],
-            targets: [targetId],
-            type: edgeType,
-            _meta: {},
-        };
-        this._data.edges[edgeId] = edge;
-        const ops = [{ op: 'add', path: `/edges/${edgeId}`, value: edge }];
-        this.sendPatch(ops);
-        this.emit('patch', { ops, source: 'local' });
-        return edgeId;
-    }
-    /**
-     * Remove edges between two nodes.
-     * @returns true if any edges were removed
-     */
-    unlinkNodes(sourceId, targetId) {
-        const patch = [];
-        const removedEdgeIds = [];
-        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}` });
-                removedEdgeIds.push(edgeId);
-            }
+    async link(sourceId, targetId, linkType) {
+        const entry = this._data.objects[sourceId];
+        if (!entry) {
+            throw new Error(`Source object ${sourceId} not found`);
         }
-        if (patch.length > 0) {
-            this.sendPatch(patch);
-            this.emit('patch', { ops: patch, source: 'local' });
-            return true;
+        // Update local state immediately
+        if (!entry.links[linkType]) {
+            entry.links[linkType] = {};
+        }
+        entry.links[linkType][targetId] = {};
+        const linkData = entry.links[linkType][targetId];
+        this.emit('linked', { sourceId, targetId, linkType, linkData, source: 'local_user' });
+        // Await server call
+        try {
+            await this.graphqlClient.link(this.id, sourceId, targetId, linkType);
+        }
+        catch (error) {
+            console.error('[Graph] Failed to create link:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
         }
-        return false;
-    }
-    /**
-     * Get parent node IDs (nodes that have edges pointing TO this node).
-     * @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);
     }
     /**
-     * Get child node IDs (nodes that this node has edges pointing TO).
-     * @param edgeType - Optional filter by edge type
+     * Remove a link between two objects.
+     * @param linkType - Optional: if provided, only removes that type; otherwise removes all links between the objects
+     * @returns true if any links were removed
      */
-    getChildren(nodeId, edgeType) {
-        return Object.values(this._data.edges)
-            .filter(edge => edge.sources.includes(nodeId) &&
-            (!edgeType || edge.type === edgeType))
-            .flatMap(edge => edge.targets);
+    async unlink(sourceId, targetId, linkType) {
+        const entry = this._data.objects[sourceId];
+        if (!entry) {
+            throw new Error(`Source object ${sourceId} not found`);
+        }
+        const deletedLinks = [];
+        // Update local state
+        if (linkType) {
+            // Remove specific link type
+            if (entry.links[linkType]?.[targetId] !== undefined) {
+                delete entry.links[linkType][targetId];
+                deletedLinks.push({ linkType });
+            }
+        }
+        else {
+            // Remove all links from source to target
+            for (const [type, targets] of Object.entries(entry.links)) {
+                if (targets[targetId] !== undefined) {
+                    delete targets[targetId];
+                    deletedLinks.push({ linkType: type });
+                }
+            }
+        }
+        // Emit semantic events
+        for (const link of deletedLinks) {
+            this.emit('unlinked', { sourceId, targetId, linkType: link.linkType, source: 'local_user' });
+        }
+        // Await server call
+        try {
+            await this.graphqlClient.unlink(this.id, sourceId, targetId);
+        }
+        catch (error) {
+            console.error('[Graph] Failed to remove link:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        return deletedLinks.length > 0;
     }
     /**
-     * Get an edge by ID.
+     * Get parent object IDs (objects that have links pointing TO this object).
+     * @param linkType - Optional filter by link type
      */
-    getEdge(edgeId) {
-        return this._data.edges[edgeId];
+    getParents(objectId, linkType) {
+        const parents = [];
+        for (const [entryId, entry] of Object.entries(this._data.objects)) {
+            for (const [type, targets] of Object.entries(entry.links)) {
+                if ((!linkType || type === linkType) && objectId in targets) {
+                    parents.push(entryId);
+                    break; // Found a link, move to next object
+                }
+            }
+        }
+        return parents;
+    }
+    /**
+     * Get child object IDs (objects that this object has links pointing TO).
+     * Filters out orphan targets (targets that don't exist).
+     * @param linkType - Optional filter by link type
+     */
+    getChildren(objectId, linkType) {
+        const entry = this._data.objects[objectId];
+        if (!entry)
+            return [];
+        const children = [];
+        for (const [type, targets] of Object.entries(entry.links)) {
+            if (!linkType || type === linkType) {
+                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 linkType - Optional filter by link type
      */
-    getEdgeIds() {
-        return Object.keys(this._data.edges);
+    getChildrenIncludingOrphans(objectId, linkType) {
+        const entry = this._data.objects[objectId];
+        if (!entry)
+            return [];
+        const children = [];
+        for (const [type, targets] of Object.entries(entry.links)) {
+            if (!linkType || type === linkType) {
+                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;
-        this.sendPatch([{ op: 'replace', 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
@@ -416,18 +536,6 @@ export class RoolGraph extends EventEmitter {
     async prompt(prompt, options) {
         return this.graphqlClient.promptGraph(this._id, prompt, options);
     }
-    /**
-     * Generate an AI image.
-     */
-    async generateImage(prompt, aspectRatio) {
-        return this.graphqlClient.generateImage(this._id, prompt, aspectRatio);
-    }
-    /**
-     * Edit an existing image using AI.
-     */
-    async editImage(prompt, url) {
-        return this.graphqlClient.editImage(this._id, prompt, url);
-    }
     // ===========================================================================
     // Collaboration
     // ===========================================================================
@@ -492,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)
     // ===========================================================================
@@ -524,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 linkType = parts[4];
+                        const targetId = parts[5];
+                        if (op.op === 'add') {
+                            const linkData = this._data.objects[objectId]?.links[linkType]?.[targetId] ?? {};
+                            this.emit('linked', { sourceId: objectId, targetId, linkType, linkData, source });
+                        }
+                        else if (op.op === 'remove') {
+                            this.emit('unlinked', { sourceId: objectId, targetId, linkType, source });
+                        }
+                    }
+                    else if (parts.length === 5 && op.op === 'add') {
+                        // /objects/{objectId}/links/{type} - new link type object added
+                        const linkType = parts[4];
+                        const targets = this._data.objects[objectId]?.links[linkType] ?? {};
+                        for (const [targetId, linkData] of Object.entries(targets)) {
+                            this.emit('linked', { sourceId: objectId, targetId, linkType, 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.
@@ -545,23 +714,6 @@ export class RoolGraph extends EventEmitter {
     // ===========================================================================
     // Private Methods
     // ===========================================================================
-    sendPatch(patch) {
-        this.pendingPatch.push(...patch);
-        if (!this.patchScheduled) {
-            this.patchScheduled = true;
-            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)));
-                    });
-                }
-            });
-        }
-    }
     async resyncFromServer(originalError) {
         console.warn('[Graph] Resyncing from server after sync failure');
         try {