@dxos/app-graph 0.6.2 → 0.6.3-main.226a8ae

package/dist/lib/node/index.cjs

@@ -18,65 +18,83 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var node_exports = {};
 __export(node_exports, {
+  ACTION_GROUP_TYPE: () => ACTION_GROUP_TYPE,
+  ACTION_TYPE: () => ACTION_TYPE,
   Graph: () => Graph,
   GraphBuilder: () => GraphBuilder,
   ROOT_ID: () => ROOT_ID,
+  ROOT_TYPE: () => ROOT_TYPE,
   actionGroupSymbol: () => actionGroupSymbol,
+  cleanup: () => cleanup,
+  createExtension: () => createExtension,
+  getGraph: () => getGraph,
   isAction: () => isAction,
   isActionGroup: () => isActionGroup,
   isActionLike: () => isActionLike,
   isGraphNode: () => isGraphNode,
-  manageNodes: () => manageNodes
+  memoize: () => memoize,
+  toSignal: () => toSignal
 });
 module.exports = __toCommonJS(node_exports);
 var import_signals_core = require("@preact/signals-core");
+var import_async = require("@dxos/async");
 var import_echo_schema = require("@dxos/echo-schema");
 var import_invariant = require("@dxos/invariant");
 var import_util = require("@dxos/util");
-var import_async = require("@dxos/async");
+var import_signals_core2 = require("@preact/signals-core");
+var import_echo_schema2 = require("@dxos/echo-schema");
+var import_invariant2 = require("@dxos/invariant");
+var import_util2 = require("@dxos/util");
 var isGraphNode = (data) => data && typeof data === "object" && "id" in data && "properties" in data && data.properties ? typeof data.properties === "object" && "data" in data : false;
 var isAction = (data) => isGraphNode(data) ? typeof data.data === "function" : false;
 var actionGroupSymbol = Symbol("ActionGroup");
 var isActionGroup = (data) => isGraphNode(data) ? data.data === actionGroupSymbol : false;
 var isActionLike = (data) => isAction(data) || isActionGroup(data);
 var __dxlog_file = "/home/runner/work/dxos/dxos/packages/sdk/app-graph/src/graph.ts";
+var graphSymbol = Symbol("graph");
+var getGraph = (node) => {
+  const graph = node[graphSymbol];
+  (0, import_invariant.invariant)(graph, "Node is not associated with a graph.", {
+    F: __dxlog_file,
+    L: 20,
+    S: void 0,
+    A: [
+      "graph",
+      "'Node is not associated with a graph.'"
+    ]
+  });
+  return graph;
+};
 var ROOT_ID = "root";
+var ROOT_TYPE = "dxos.org/type/GraphRoot";
+var ACTION_TYPE = "dxos.org/type/GraphAction";
+var ACTION_GROUP_TYPE = "dxos.org/type/GraphActionGroup";
+var NODE_TIMEOUT = 5e3;
 var Graph = class {
-  constructor() {
-    this._nodes = (0, import_echo_schema.create)({
-      [ROOT_ID]: {
-        id: ROOT_ID,
-        properties: {},
-        data: null
-      }
-    });
-    this._edges = (0, import_echo_schema.create)({});
-    this._constructNode = (nodeBase) => {
-      const node = {
-        ...nodeBase,
-        edges: ({ direction = "outbound" } = {}) => {
-          return this._edges[this.getEdgeKey(node.id, direction)];
-        },
-        nodes: ({ direction, filter } = {}) => {
-          const nodes = this._getNodes({
-            id: node.id,
-            direction
-          }).filter((n) => !isActionLike(n));
-          return filter ? nodes.filter((n) => filter(n, node)) : nodes;
-        },
-        node: (id) => {
-          return this._getNodes({
-            id
-          }).find((node2) => node2.id === id);
-        },
-        actions: () => {
-          return this._getNodes({
-            id: node.id
-          }).filter(isActionLike);
-        }
-      };
-      return node;
+  constructor({ onInitialNode, onInitialNodes, onRemoveNode } = {}) {
+    this._waitingForNodes = {};
+    this._initialized = {};
+    this._nodes = {};
+    this._edges = {};
+    this._constructNode = (node) => {
+      return (0, import_echo_schema.create)({
+        ...node,
+        [graphSymbol]: this
+      });
     };
+    this._onInitialNode = onInitialNode;
+    this._onInitialNodes = onInitialNodes;
+    this._onRemoveNode = onRemoveNode;
+    this._nodes[ROOT_ID] = this._constructNode({
+      id: ROOT_ID,
+      type: ROOT_TYPE,
+      properties: {},
+      data: null
+    });
+    this._edges[ROOT_ID] = (0, import_echo_schema.create)({
+      inbound: [],
+      outbound: []
+    });
   }
   /**
   * Alias for `findNode('root')`.
@@ -87,11 +105,14 @@ var Graph = class {
   /**
   * Convert the graph to a JSON object.
   */
-  toJSON({ id = ROOT_ID, maxLength = 32 } = {}) {
+  toJSON({ id = ROOT_ID, maxLength = 32, onlyLoaded = true } = {}) {
     const toJSON = (node, seen = []) => {
-      const nodes = node.nodes();
+      const nodes = this.nodes(node, {
+        onlyLoaded
+      });
       const obj = {
-        id: node.id.length > maxLength ? `${node.id.slice(0, maxLength - 3)}...` : node.id
+        id: node.id.length > maxLength ? `${node.id.slice(0, maxLength - 3)}...` : node.id,
+        type: node.type
       };
       if (node.properties.label) {
         obj.label = node.properties.label;
@@ -110,7 +131,7 @@ var Graph = class {
     const root = this.findNode(id);
     (0, import_invariant.invariant)(root, `Node not found: ${id}`, {
       F: __dxlog_file,
-      L: 91,
+      L: 140,
       S: this,
       A: [
         "root",
@@ -121,112 +142,309 @@ var Graph = class {
   }
   /**
   * Find the node with the given id in the graph.
+  *
+  * If a node is not found within the graph and an `onInitialNode` callback is provided,
+  * it is called with the id and type of the node, potentially initializing the node.
   */
-  findNode(id) {
-    const nodeBase = this._nodes[id];
-    if (!nodeBase) {
-      return void 0;
+  findNode(id, type) {
+    const existingNode = this._nodes[id];
+    const nodeArg = !existingNode && this._onInitialNode?.(id, type);
+    return existingNode ?? (nodeArg ? this._addNode(nodeArg) : void 0);
+  }
+  /**
+  * Wait for a node to be added to the graph.
+  *
+  * If the node is already present in the graph, the promise resolves immediately.
+  *
+  * @param id The id of the node to wait for.
+  * @param timeout The time in milliseconds to wait for the node to be added.
+  */
+  async waitForNode(id, timeout = NODE_TIMEOUT) {
+    const node = this.findNode(id);
+    if (node) {
+      return node;
     }
-    return this._constructNode(nodeBase);
+    const trigger = this._waitingForNodes[id] ?? (this._waitingForNodes[id] = new import_async.Trigger());
+    return (0, import_async.asyncTimeout)(trigger.wait(), timeout, `Node not found: ${id}`);
   }
-  _getNodes({ id, direction = "outbound" }) {
-    const edges = this._edges[this.getEdgeKey(id, direction)];
-    if (!edges) {
-      return [];
+  /**
+  * Nodes that this node is connected to in default order.
+  */
+  nodes(node, options = {}) {
+    const { onlyLoaded, relation, filter, type } = options;
+    const nodes = this._getNodes({
+      node,
+      relation,
+      type,
+      onlyLoaded
+    });
+    return nodes.filter((n) => (0, import_signals_core.untracked)(() => !isActionLike(n))).filter((n) => filter?.(n, node) ?? true);
+  }
+  /**
+  * Edges that this node is connected to in default order.
+  */
+  edges(node, { relation = "outbound" } = {}) {
+    return this._edges[node.id]?.[relation] ?? [];
+  }
+  /**
+  * Actions or action groups that this node is connected to in default order.
+  */
+  actions(node, { onlyLoaded } = {}) {
+    return [
+      ...this._getNodes({
+        node,
+        type: ACTION_GROUP_TYPE,
+        onlyLoaded
+      }),
+      ...this._getNodes({
+        node,
+        type: ACTION_TYPE,
+        onlyLoaded
+      })
+    ];
+  }
+  /**
+  * Recursive depth-first traversal of the graph.
+  *
+  * @param options.node The node to start traversing from.
+  * @param options.relation The relation to traverse graph edges.
+  * @param options.visitor A callback which is called for each node visited during traversal.
+  */
+  traverse({ visitor, node = this.root, relation = "outbound", onlyLoaded }, path = []) {
+    if (path.includes(node.id)) {
+      return;
+    }
+    const shouldContinue = visitor(node, [
+      ...path,
+      node.id
+    ]);
+    if (shouldContinue === false) {
+      return;
     }
-    return edges.map((id2) => this.findNode(id2)).filter(import_util.nonNullable);
+    Object.values(this._getNodes({
+      node,
+      relation,
+      onlyLoaded
+    })).forEach((child) => this.traverse({
+      node: child,
+      relation,
+      visitor,
+      onlyLoaded
+    }, [
+      ...path,
+      node.id
+    ]));
   }
-  getEdgeKey(id, direction) {
-    return `${id}-${direction}`;
+  /**
+  * Recursive depth-first traversal of the graph wrapping each visitor call in an effect.
+  *
+  * @param options.node The node to start traversing from.
+  * @param options.relation The relation to traverse graph edges.
+  * @param options.visitor A callback which is called for each node visited during traversal.
+  */
+  subscribeTraverse({ visitor, node = this.root, relation = "outbound", onlyLoaded }, currentPath = []) {
+    return (0, import_signals_core.effect)(() => {
+      const path = [
+        ...currentPath,
+        node.id
+      ];
+      const result = visitor(node, path);
+      if (result === false) {
+        return;
+      }
+      const nodes = this._getNodes({
+        node,
+        relation,
+        onlyLoaded
+      });
+      const nodeSubscriptions = nodes.map((n) => this.subscribeTraverse({
+        node: n,
+        visitor,
+        onlyLoaded
+      }, path));
+      return () => {
+        nodeSubscriptions.forEach((unsubscribe) => unsubscribe());
+      };
+    });
+  }
+  /**
+  * Get the path between two nodes in the graph.
+  */
+  getPath({ source = "root", target }) {
+    const start = this.findNode(source);
+    if (!start) {
+      return void 0;
+    }
+    let found;
+    this.traverse({
+      onlyLoaded: true,
+      node: start,
+      visitor: (node, path) => {
+        if (found) {
+          return false;
+        }
+        if (node.id === target) {
+          found = path;
+        }
+      }
+    });
+    return found;
   }
   /**
   * Add nodes to the graph.
+  *
+  * @internal
   */
-  addNodes(...nodes) {
-    return nodes.map((node) => this._addNode(node));
+  _addNodes(nodes) {
+    return (0, import_signals_core.batch)(() => nodes.map((node) => this._addNode(node)));
   }
   _addNode({ nodes, edges, ..._node }) {
     return (0, import_signals_core.untracked)(() => {
-      const node = {
+      const existingNode = this._nodes[_node.id];
+      const node = existingNode ?? this._constructNode({
         data: null,
         properties: {},
         ..._node
-      };
-      this._nodes[node.id] = node;
+      });
+      if (existingNode) {
+        const { data, properties, type } = _node;
+        if (data && data !== node.data) {
+          node.data = data;
+        }
+        if (type !== node.type) {
+          node.type = type;
+        }
+        for (const key in properties) {
+          if (properties[key] !== node.properties[key]) {
+            node.properties[key] = properties[key];
+          }
+        }
+      } else {
+        this._nodes[node.id] = node;
+        this._edges[node.id] = (0, import_echo_schema.create)({
+          inbound: [],
+          outbound: []
+        });
+      }
+      const trigger = this._waitingForNodes[node.id];
+      if (trigger) {
+        trigger.wake(node);
+        delete this._waitingForNodes[node.id];
+      }
       if (nodes) {
         nodes.forEach((subNode) => {
           this._addNode(subNode);
-          this.addEdge({
+          this._addEdge({
             source: node.id,
             target: subNode.id
           });
         });
       }
       if (edges) {
-        edges.forEach(([id, direction]) => direction === "outbound" ? this.addEdge({
+        edges.forEach(([id, relation]) => relation === "outbound" ? this._addEdge({
           source: node.id,
           target: id
-        }) : this.addEdge({
+        }) : this._addEdge({
           source: id,
           target: node.id
         }));
       }
-      return this._constructNode(node);
+      return node;
     });
   }
   /**
   * Remove nodes from the graph.
   *
-  * @param id The id of the node to remove.
+  * @param ids The id of the node to remove.
   * @param edges Whether to remove edges connected to the node from the graph as well.
+  * @internal
   */
-  removeNode(id, edges = false) {
+  _removeNodes(ids, edges = false) {
+    (0, import_signals_core.batch)(() => ids.forEach((id) => this._removeNode(id, edges)));
+  }
+  _removeNode(id, edges = false) {
     (0, import_signals_core.untracked)(() => {
       const node = this.findNode(id);
       if (!node) {
         return;
       }
       if (edges) {
-        delete this._edges[this.getEdgeKey(id, "outbound")];
-        delete this._edges[this.getEdgeKey(id, "inbound")];
         this._getNodes({
-          id
-        }).forEach((node2) => this.removeEdge({
-          source: id,
-          target: node2.id
-        }));
+          node,
+          onlyLoaded: true
+        }).forEach((node2) => {
+          this._removeEdge({
+            source: id,
+            target: node2.id
+          });
+        });
         this._getNodes({
-          id,
-          direction: "inbound"
-        }).forEach((node2) => this.removeEdge({
-          source: node2.id,
-          target: id
-        }));
+          node,
+          relation: "inbound",
+          onlyLoaded: true
+        }).forEach((node2) => {
+          this._removeEdge({
+            source: node2.id,
+            target: id
+          });
+        });
+        delete this._edges[id];
       }
       delete this._nodes[id];
+      this._onRemoveNode?.(id);
     });
   }
   /**
-  * Add an edge to the graph.
+  * Add edges to the graph.
+  *
+  * @internal
   */
-  addEdge({ source, target }) {
+  _addEdges(edges) {
+    (0, import_signals_core.batch)(() => edges.forEach((edge) => this._addEdge(edge)));
+  }
+  _addEdge({ source, target }) {
     (0, import_signals_core.untracked)(() => {
-      const outbound = this._edges[this.getEdgeKey(source, "outbound")];
-      if (!outbound) {
-        this._edges[this.getEdgeKey(source, "outbound")] = [
-          target
-        ];
-      } else if (!outbound.includes(target)) {
-        outbound.push(target);
+      if (!this._edges[source]) {
+        this._edges[source] = (0, import_echo_schema.create)({
+          inbound: [],
+          outbound: []
+        });
+      }
+      if (!this._edges[target]) {
+        this._edges[target] = (0, import_echo_schema.create)({
+          inbound: [],
+          outbound: []
+        });
       }
-      const inbound = this._edges[this.getEdgeKey(target, "inbound")];
-      if (!inbound) {
-        this._edges[this.getEdgeKey(target, "inbound")] = [
-          source
-        ];
-      } else if (!inbound.includes(source)) {
-        inbound.push(source);
+      const sourceEdges = this._edges[source];
+      if (!sourceEdges.outbound.includes(target)) {
+        sourceEdges.outbound.push(target);
       }
+      const targetEdges = this._edges[target];
+      if (!targetEdges.inbound.includes(source)) {
+        targetEdges.inbound.push(source);
+      }
+    });
+  }
+  /**
+  * Remove edges from the graph.
+  * @internal
+  */
+  _removeEdges(edges) {
+    (0, import_signals_core.batch)(() => edges.forEach((edge) => this._removeEdge(edge)));
+  }
+  _removeEdge({ source, target }) {
+    (0, import_signals_core.untracked)(() => {
+      (0, import_signals_core.batch)(() => {
+        const outboundIndex = this._edges[source]?.outbound.findIndex((id) => id === target);
+        if (outboundIndex !== void 0 && outboundIndex !== -1) {
+          this._edges[source].outbound.splice(outboundIndex, 1);
+        }
+        const inboundIndex = this._edges[target]?.inbound.findIndex((id) => id === source);
+        if (inboundIndex !== void 0 && inboundIndex !== -1) {
+          this._edges[target].inbound.splice(inboundIndex, 1);
+        }
+      });
     });
   }
   /**
@@ -235,139 +453,322 @@ var Graph = class {
   * Edges not included in the sorted list are appended to the end of the list.
   *
   * @param nodeId The id of the node to sort edges for.
-  * @param direction The direction of the edges from the node to sort.
+  * @param relation The relation of the edges from the node to sort.
   * @param edges The ordered list of edges.
+  * @ignore
   */
-  sortEdges(nodeId, direction, edges) {
+  _sortEdges(nodeId, relation, edges) {
     (0, import_signals_core.untracked)(() => {
-      const current = this._edges[this.getEdgeKey(nodeId, direction)];
-      if (current) {
-        const unsorted = current.filter((id) => !edges.includes(id)) ?? [];
-        const sorted = edges.filter((id) => current.includes(id)) ?? [];
-        current.splice(0, current.length, ...[
-          ...sorted,
-          ...unsorted
-        ]);
-      }
+      (0, import_signals_core.batch)(() => {
+        const current = this._edges[nodeId];
+        if (current) {
+          const unsorted = current[relation].filter((id) => !edges.includes(id)) ?? [];
+          const sorted = edges.filter((id) => current[relation].includes(id)) ?? [];
+          current[relation].splice(0, current[relation].length, ...[
+            ...sorted,
+            ...unsorted
+          ]);
+        }
+      });
     });
   }
-  /**
-  * Remove an edge from the graph.
-  */
-  removeEdge({ source, target }) {
-    (0, import_signals_core.untracked)(() => {
-      const outboundIndex = this._edges[this.getEdgeKey(source, "outbound")]?.findIndex((id) => id === target);
-      if (outboundIndex !== -1) {
-        this._edges[this.getEdgeKey(source, "outbound")].splice(outboundIndex, 1);
-      }
-      const inboundIndex = this._edges[this.getEdgeKey(target, "inbound")]?.findIndex((id) => id === source);
-      if (inboundIndex !== -1) {
-        this._edges[this.getEdgeKey(target, "inbound")].splice(inboundIndex, 1);
+  _getNodes({ node, relation = "outbound", type, onlyLoaded }) {
+    const key = `${node.id}-${relation}-${type}`;
+    const initialized = this._initialized[key];
+    if (!initialized && !onlyLoaded && this._onInitialNodes) {
+      const args = this._onInitialNodes(node, relation, type)?.filter((n) => !type || n.type === type);
+      this._initialized[key] = true;
+      if (args && args.length > 0) {
+        const nodes = this._addNodes(args);
+        this._addEdges(nodes.map(({ id }) => relation === "outbound" ? {
+          source: node.id,
+          target: id
+        } : {
+          source: id,
+          target: node.id
+        }));
       }
-    });
-  }
-  /**
-  * Recursive depth-first traversal.
-  *
-  * @param options.node The node to start traversing from.
-  * @param options.direction The direction to traverse graph edges.
-  * @param options.filter A predicate to filter nodes which are passed to the `visitor` callback.
-  * @param options.visitor A callback which is called for each node visited during traversal.
-  */
-  traverse({ node = this.root, direction = "outbound", filter, visitor }, path = []) {
-    if (path.includes(node.id)) {
-      return;
     }
-    if (!filter || filter(node)) {
-      visitor?.(node, [
-        ...path,
-        node.id
-      ]);
+    const edges = this._edges[node.id];
+    if (!edges) {
+      return [];
+    } else {
+      return edges[relation].map((id) => this._nodes[id]).filter(import_util.nonNullable).filter((n) => !type || n.type === type);
     }
-    Object.values(this._getNodes({
-      id: node.id,
-      direction
-    })).forEach((child) => this.traverse({
-      node: child,
-      direction,
-      filter,
-      visitor
-    }, [
-      ...path,
-      node.id
-    ]));
   }
-  /**
-  * Get the path between two nodes in the graph.
-  */
-  getPath({ source = "root", target }) {
-    const start = this.findNode(source);
-    if (!start) {
-      return void 0;
+};
+var __dxlog_file2 = "/home/runner/work/dxos/dxos/packages/sdk/app-graph/src/graph-builder.ts";
+var createExtension = (extension) => {
+  const { id, resolver, connector, actions, actionGroups, ...rest } = extension;
+  const getId = (key) => `${id}/${key}`;
+  return [
+    resolver ? {
+      id: getId("resolver"),
+      resolver
+    } : void 0,
+    connector ? {
+      ...rest,
+      id: getId("connector"),
+      connector
+    } : void 0,
+    actionGroups ? {
+      ...rest,
+      id: getId("actionGroups"),
+      type: ACTION_GROUP_TYPE,
+      relation: "outbound",
+      connector: ({ node }) => actionGroups({
+        node
+      })?.map((arg) => ({
+        ...arg,
+        data: actionGroupSymbol,
+        type: ACTION_GROUP_TYPE
+      }))
+    } : void 0,
+    actions ? {
+      ...rest,
+      id: getId("actions"),
+      type: ACTION_TYPE,
+      relation: "outbound",
+      connector: ({ node }) => actions({
+        node
+      })?.map((arg) => ({
+        ...arg,
+        type: ACTION_TYPE
+      }))
+    } : void 0
+  ].filter(import_util2.nonNullable);
+};
+var Dispatcher = class {
+  constructor() {
+    this.stateIndex = 0;
+    this.state = {};
+    this.cleanup = [];
+  }
+};
+var BuilderInternal = class {
+};
+var memoize = (fn, key = "result") => {
+  const dispatcher = BuilderInternal.currentDispatcher;
+  (0, import_invariant2.invariant)(dispatcher?.currentExtension, "memoize must be called within an extension", {
+    F: __dxlog_file2,
+    L: 129,
+    S: void 0,
+    A: [
+      "dispatcher?.currentExtension",
+      "'memoize must be called within an extension'"
+    ]
+  });
+  const all = dispatcher.state[dispatcher.currentExtension][dispatcher.stateIndex] ?? {};
+  const current = all[key];
+  const result = current ? current.result : fn();
+  dispatcher.state[dispatcher.currentExtension][dispatcher.stateIndex] = {
+    ...all,
+    [key]: {
+      result
     }
-    let found;
-    this.traverse({
-      node: start,
-      filter: () => !found,
-      visitor: (node, path) => {
-        if (node.id === target) {
-          found = path;
-        }
-      }
+  };
+  dispatcher.stateIndex++;
+  return result;
+};
+var cleanup = (fn) => {
+  memoize(() => {
+    const dispatcher = BuilderInternal.currentDispatcher;
+    (0, import_invariant2.invariant)(dispatcher, "cleanup must be called within an extension", {
+      F: __dxlog_file2,
+      L: 144,
+      S: void 0,
+      A: [
+        "dispatcher",
+        "'cleanup must be called within an extension'"
+      ]
     });
-    return found;
-  }
+    dispatcher.cleanup.push(fn);
+  });
+};
+var toSignal = (subscribe, get, key) => {
+  const thisSignal = memoize(() => {
+    return (0, import_signals_core2.signal)(get());
+  }, key);
+  const unsubscribe = memoize(() => {
+    return subscribe(() => thisSignal.value = get());
+  }, key);
+  cleanup(() => {
+    unsubscribe();
+  });
+  return thisSignal.value;
 };
 var GraphBuilder = class {
   constructor() {
-    this._extensions = /* @__PURE__ */ new Map();
-    this._unsubscribe = new import_async.EventSubscriptions();
+    this._dispatcher = new Dispatcher();
+    this._extensions = (0, import_echo_schema2.create)({});
+    this._resolverSubscriptions = /* @__PURE__ */ new Map();
+    this._connectorSubscriptions = /* @__PURE__ */ new Map();
+    this._nodeChanged = {};
+    this._graph = new Graph({
+      onInitialNode: (id, type) => this._onInitialNode(id, type),
+      onInitialNodes: (node, relation, type) => this._onInitialNodes(node, relation, type),
+      onRemoveNode: (id) => this._onRemoveNode(id)
+    });
+  }
+  get graph() {
+    return this._graph;
   }
   /**
   * Register a node builder which will be called in order to construct the graph.
   */
-  addExtension(id, extension) {
-    this._extensions.set(id, extension);
+  addExtension(extension) {
+    if (Array.isArray(extension)) {
+      extension.forEach((ext) => this.addExtension(ext));
+      return this;
+    }
+    this._dispatcher.state[extension.id] = [];
+    this._extensions[extension.id] = extension;
     return this;
   }
   /**
   * Remove a node builder from the graph builder.
   */
   removeExtension(id) {
-    this._extensions.delete(id);
+    delete this._extensions[id];
     return this;
   }
+  destroy() {
+    this._dispatcher.cleanup.forEach((fn) => fn());
+    this._resolverSubscriptions.forEach((unsubscribe) => unsubscribe());
+    this._connectorSubscriptions.forEach((unsubscribe) => unsubscribe());
+    this._resolverSubscriptions.clear();
+    this._connectorSubscriptions.clear();
+  }
   /**
-  * Construct the graph, starting by calling all registered extensions.
-  * @param previousGraph If provided, the graph will be updated in place.
+  * Traverse a graph using just the connector extensions, without subscribing to any signals or persisting any nodes.
   */
-  build(previousGraph) {
-    this._unsubscribe.clear();
-    const graph = previousGraph ?? new Graph();
-    Array.from(this._extensions.values()).forEach((builder) => {
-      const unsubscribe = builder(graph);
-      unsubscribe && this._unsubscribe.add(unsubscribe);
-    });
-    return graph;
+  // TODO(wittjosiah): Rename? This is not traversing the graph proper.
+  async traverse({ node, relation = "outbound", visitor }, path = []) {
+    if (path.includes(node.id)) {
+      return;
+    }
+    visitor(node, [
+      ...path,
+      node.id
+    ]);
+    const nodes = Object.values(this._extensions).filter((extension) => relation === (extension.relation ?? "outbound")).flatMap((extension) => extension.connector?.({
+      node
+    }) ?? []).map((arg) => ({
+      id: arg.id,
+      type: arg.type,
+      data: arg.data ?? null,
+      properties: arg.properties ?? {}
+    }));
+    await Promise.all(nodes.map((n) => this.traverse({
+      node: n,
+      relation,
+      visitor
+    }, [
+      ...path,
+      node.id
+    ])));
   }
-};
-var manageNodes = ({ graph, condition, nodes, removeEdges }) => {
-  if (condition) {
-    return graph.addNodes(...nodes);
-  } else {
-    nodes.forEach(({ id }) => graph.removeNode(id, removeEdges));
+  _onInitialNode(nodeId, nodeType) {
+    this._nodeChanged[nodeId] = this._nodeChanged[nodeId] ?? (0, import_signals_core2.signal)({});
+    let initialized;
+    for (const { id, type, resolver } of Object.values(this._extensions)) {
+      if (!resolver || nodeType && type !== nodeType) {
+        continue;
+      }
+      const unsubscribe = (0, import_signals_core2.effect)(() => {
+        this._dispatcher.currentExtension = id;
+        this._dispatcher.stateIndex = 0;
+        BuilderInternal.currentDispatcher = this._dispatcher;
+        const node = resolver({
+          id: nodeId
+        });
+        BuilderInternal.currentDispatcher = void 0;
+        if (node && initialized) {
+          this.graph._addNodes([
+            node
+          ]);
+          if (this._nodeChanged[initialized.id]) {
+            this._nodeChanged[initialized.id].value = {};
+          }
+        } else if (node) {
+          initialized = node;
+        }
+      });
+      if (initialized) {
+        this._resolverSubscriptions.set(nodeId, unsubscribe);
+        break;
+      } else {
+        unsubscribe();
+      }
+    }
+    return initialized;
+  }
+  _onInitialNodes(node, nodesRelation, nodesType) {
+    this._nodeChanged[node.id] = this._nodeChanged[node.id] ?? (0, import_signals_core2.signal)({});
+    let initialized;
+    let previous = [];
+    this._connectorSubscriptions.set(node.id, (0, import_signals_core2.effect)(() => {
+      Object.keys(this._extensions);
+      this._nodeChanged[node.id].value;
+      const nodes = [];
+      for (const { id, connector, filter, type, relation = "outbound" } of Object.values(this._extensions)) {
+        if (!connector || relation !== nodesRelation || nodesType && type !== nodesType || filter && !filter(node)) {
+          continue;
+        }
+        this._dispatcher.currentExtension = id;
+        this._dispatcher.stateIndex = 0;
+        BuilderInternal.currentDispatcher = this._dispatcher;
+        nodes.push(...connector({
+          node
+        }) ?? []);
+        BuilderInternal.currentDispatcher = void 0;
+      }
+      const ids = nodes.map((n) => n.id);
+      const removed = previous.filter((id) => !ids.includes(id));
+      previous = ids;
+      if (initialized) {
+        this.graph._removeNodes(removed, true);
+        this.graph._addNodes(nodes);
+        this.graph._addEdges(nodes.map(({ id }) => ({
+          source: node.id,
+          target: id
+        })));
+        this.graph._sortEdges(node.id, "outbound", nodes.map(({ id }) => id));
+        nodes.forEach((n) => {
+          if (this._nodeChanged[n.id]) {
+            this._nodeChanged[n.id].value = {};
+          }
+        });
+      } else {
+        initialized = nodes;
+      }
+    }));
+    return initialized;
+  }
+  _onRemoveNode(nodeId) {
+    this._resolverSubscriptions.get(nodeId)?.();
+    this._connectorSubscriptions.get(nodeId)?.();
+    this._resolverSubscriptions.delete(nodeId);
+    this._connectorSubscriptions.delete(nodeId);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ACTION_GROUP_TYPE,
+  ACTION_TYPE,
   Graph,
   GraphBuilder,
   ROOT_ID,
+  ROOT_TYPE,
   actionGroupSymbol,
+  cleanup,
+  createExtension,
+  getGraph,
   isAction,
   isActionGroup,
   isActionLike,
   isGraphNode,
-  manageNodes
+  memoize,
+  toSignal
 });
 //# sourceMappingURL=index.cjs.map