@dxos/app-graph 0.8.4-main.fffef41 → 0.9.0

package/src/graph-builder.ts

@@ -3,225 +3,168 @@
 //
 
 import { Atom, Registry } from '@effect-atom/atom-react';
-import { effect } from '@preact/signals-core';
 import * as Array from 'effect/Array';
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
 import * as Record from 'effect/Record';
 
-import { type CleanupFn, type MulticastObservable, type Trigger } from '@dxos/async';
+import { type CleanupFn, type Trigger } from '@dxos/async';
+import { type Type } from '@dxos/echo';
 import { log } from '@dxos/log';
-import { type MaybePromise, type Position, byPosition, getDebugName, isNode, isNonNullable } from '@dxos/util';
+import { type MaybePromise, type Position, byPosition, getDebugName, isNonNullable } from '@dxos/util';
+
+import { scheduleTask, yieldOrContinue } from '#scheduler';
+
+import * as Graph from './graph';
+import * as Node from './node';
+import * as NodeMatcher from './node-matcher';
+import {
+  getParentId,
+  nodeArgsUnchanged,
+  normalizeRelation,
+  primaryKey,
+  primaryParts,
+  qualifyId,
+  validateSegmentId,
+} from './util';
 
-import { ACTION_GROUP_TYPE, ACTION_TYPE, type ExpandableGraph, Graph, type GraphParams, ROOT_ID } from './graph';
-import { type ActionData, type Node, type NodeArg, type Relation, actionGroupSymbol } from './node';
+//
+// Extension Types
+//
 
 /**
  * Graph builder extension for adding nodes to the graph based on a node id.
  */
-export type ResolverExtension = (id: string) => Atom.Atom<NodeArg<any> | null>;
+export type ResolverExtension = (id: string) => Atom.Atom<Node.NodeArg<any> | null>;
 
 /**
  * Graph builder extension for adding nodes to the graph based on a connection to an existing node.
  *
  * @param params.node The existing node the returned nodes will be connected to.
  */
-export type ConnectorExtension = (node: Atom.Atom<Option.Option<Node>>) => Atom.Atom<NodeArg<any>[]>;
+export type ConnectorExtension = (node: Atom.Atom<Option.Option<Node.Node>>) => Atom.Atom<Node.NodeArg<any>[]>;
 
 /**
  * Constrained case of the connector extension for more easily adding actions to the graph.
  */
 export type ActionsExtension = (
-  node: Atom.Atom<Option.Option<Node>>,
-) => Atom.Atom<Omit<NodeArg<ActionData>, 'type' | 'nodes' | 'edges'>[]>;
+  node: Atom.Atom<Option.Option<Node.Node>>,
+) => Atom.Atom<Omit<Node.NodeArg<Node.ActionData<any>>, 'type' | 'nodes' | 'edges'>[]>;
 
 /**
  * Constrained case of the connector extension for more easily adding action groups to the graph.
  */
 export type ActionGroupsExtension = (
-  node: Atom.Atom<Option.Option<Node>>,
-) => Atom.Atom<Omit<NodeArg<typeof actionGroupSymbol>, 'type' | 'data' | 'nodes' | 'edges'>[]>;
+  node: Atom.Atom<Option.Option<Node.Node>>,
+) => Atom.Atom<Omit<Node.NodeArg<typeof Node.actionGroupSymbol>, 'type' | 'data' | 'nodes' | 'edges'>[]>;
 
-/**
- * A graph builder extension is used to add nodes to the graph.
- *
- * @param params.id The unique id of the extension.
- * @param params.relation The relation the graph is being expanded from the existing node.
- * @param params.position Affects the order the extensions are processed in.
- * @param params.resolver A function to add nodes to the graph based on just the node id.
- * @param params.connector A function to add nodes to the graph based on a connection to an existing node.
- * @param params.actions A function to add actions to the graph based on a connection to an existing node.
- * @param params.actionGroups A function to add action groups to the graph based on a connection to an existing node.
- */
-export type CreateExtensionOptions = {
+export type BuilderExtension = Readonly<{
   id: string;
-  relation?: Relation;
   position?: Position;
+  relation?: Node.RelationInput;
   resolver?: ResolverExtension;
-  connector?: ConnectorExtension;
-  actions?: ActionsExtension;
-  actionGroups?: ActionGroupsExtension;
-};
-
-/**
- * Create a graph builder extension.
- */
-export const createExtension = (extension: CreateExtensionOptions): BuilderExtension[] => {
-  const {
-    id,
-    position = 'static',
-    relation = 'outbound',
-    resolver: _resolver,
-    connector: _connector,
-    actions: _actions,
-    actionGroups: _actionGroups,
-  } = extension;
-  const getId = (key: string) => `${id}/${key}`;
-
-  const resolver =
-    _resolver && Atom.family((id: string) => _resolver(id).pipe(Atom.withLabel(`graph-builder:_resolver:${id}`)));
-
-  const connector =
-    _connector &&
-    Atom.family((node: Atom.Atom<Option.Option<Node>>) =>
-      _connector(node).pipe(Atom.withLabel(`graph-builder:_connector:${id}`)),
-    );
-
-  const actionGroups =
-    _actionGroups &&
-    Atom.family((node: Atom.Atom<Option.Option<Node>>) =>
-      _actionGroups(node).pipe(Atom.withLabel(`graph-builder:_actionGroups:${id}`)),
-    );
+  connector?: (node: Atom.Atom<Option.Option<Node.Node>>) => Atom.Atom<Node.NodeArg<any>[]>;
+}>;
 
-  const actions =
-    _actions &&
-    Atom.family((node: Atom.Atom<Option.Option<Node>>) =>
-      _actions(node).pipe(Atom.withLabel(`graph-builder:_actions:${id}`)),
-    );
+export type BuilderExtensions = BuilderExtension | BuilderExtension[] | BuilderExtensions[];
 
-  return [
-    resolver ? { id: getId('resolver'), position, resolver } : undefined,
-    connector
-      ? ({
-          id: getId('connector'),
-          position,
-          relation,
-          connector: Atom.family((node) =>
-            Atom.make((get) => {
-              try {
-                return get(connector(node));
-              } catch {
-                log.warn('Error in connector', { id: getId('connector'), node });
-                return [];
-              }
-            }).pipe(Atom.withLabel(`graph-builder:connector:${id}`)),
-          ),
-        } satisfies BuilderExtension)
-      : undefined,
-    actionGroups
-      ? ({
-          id: getId('actionGroups'),
-          position,
-          relation: 'outbound',
-          connector: Atom.family((node) =>
-            Atom.make((get) => {
-              try {
-                return get(actionGroups(node)).map((arg) => ({
-                  ...arg,
-                  data: actionGroupSymbol,
-                  type: ACTION_GROUP_TYPE,
-                }));
-              } catch {
-                log.warn('Error in actionGroups', { id: getId('actionGroups'), node });
-                return [];
-              }
-            }).pipe(Atom.withLabel(`graph-builder:connector:actionGroups:${id}`)),
-          ),
-        } satisfies BuilderExtension)
-      : undefined,
-    actions
-      ? ({
-          id: getId('actions'),
-          position,
-          relation: 'outbound',
-          connector: Atom.family((node) =>
-            Atom.make((get) => {
-              try {
-                return get(actions(node)).map((arg) => ({ ...arg, type: ACTION_TYPE }));
-              } catch {
-                log.warn('Error in actions', { id: getId('actions'), node });
-                return [];
-              }
-            }).pipe(Atom.withLabel(`graph-builder:connector:actions:${id}`)),
-          ),
-        } satisfies BuilderExtension)
-      : undefined,
-  ].filter(isNonNullable);
-};
+//
+// GraphBuilder Core
+//
 
 export type GraphBuilderTraverseOptions = {
-  visitor: (node: Node, path: string[]) => MaybePromise<boolean | void>;
+  visitor: (node: Node.Node, path: string[]) => MaybePromise<boolean | void>;
   registry?: Registry.Registry;
   source?: string;
-  relation?: Relation;
+  relation: Node.RelationInput | Node.RelationInput[];
 };
 
-export type BuilderExtension = Readonly<{
-  id: string;
-  position: Position;
-  relation?: Relation; // Only for connector.
-  resolver?: ResolverExtension;
-  connector?: (node: Atom.Atom<Option.Option<Node>>) => Atom.Atom<NodeArg<any>[]>;
-}>;
-
-export type BuilderExtensions = BuilderExtension | BuilderExtension[] | BuilderExtensions[];
+/**
+ * Identifier denoting a GraphBuilder.
+ */
+export const GraphBuilderTypeId: unique symbol = Symbol.for('@dxos/app-graph/GraphBuilder');
+export type GraphBuilderTypeId = typeof GraphBuilderTypeId;
 
-export const flattenExtensions = (extension: BuilderExtensions, acc: BuilderExtension[] = []): BuilderExtension[] => {
-  if (Array.isArray(extension)) {
-    return [...acc, ...extension.flatMap((ext) => flattenExtensions(ext, acc))];
-  } else {
-    return [...acc, extension];
-  }
-};
+/**
+ * GraphBuilder interface.
+ */
+export interface GraphBuilder extends Pipeable.Pipeable {
+  readonly [GraphBuilderTypeId]: GraphBuilderTypeId;
+  readonly graph: Graph.ExpandableGraph;
+  readonly extensions: Atom.Atom<Record<string, BuilderExtension>>;
+}
 
 /**
  * The builder provides an extensible way to compose the construction of the graph.
+ * @internal
  */
 // TODO(wittjosiah): Add api for setting subscription set and/or radius.
 //   Should unsubscribe from nodes that are not in the set/radius.
 //   Should track LRU nodes that are not in the set/radius and remove them beyond a certain threshold.
-export class GraphBuilder {
+class GraphBuilderImpl implements GraphBuilder {
+  readonly [GraphBuilderTypeId]: GraphBuilderTypeId = GraphBuilderTypeId;
+
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return Pipeable.pipeArguments(this, arguments);
+  }
+
   // TODO(wittjosiah): Use Context.
-  private readonly _subscriptions = new Map<string, CleanupFn>();
-  private readonly _extensions = Atom.make(Record.empty<string, BuilderExtension>()).pipe(
+  /** Active subscriptions keyed by composite ID, cleaned up on node removal. */
+  readonly _subscriptions = new Map<string, CleanupFn>();
+  /** Connector updates pending flush, keyed by connector key. */
+  readonly _dirtyConnectors = new Map<
+    string,
+    {
+      nodes: Node.NodeArg<any>[];
+      previous: string[];
+    }
+  >();
+  /** Last-flushed node IDs per connector key, used for edge removal on update. */
+  readonly _connectorPrevious = new Map<string, string[]>();
+  /** All inline-descendant IDs per connector key, used to remove stale inline nodes on update. */
+  readonly _connectorPreviousInlineIds = new Map<string, string[]>();
+  /** Last-flushed node args per connector key, used for change detection. */
+  readonly _connectorPreviousArgs = new Map<string, Node.NodeArg<any>[]>();
+  /** Whether a dirty-flush task is already scheduled. */
+  _flushScheduled = false;
+  /** Resolves when the current flush completes. */
+  _flushPromise: Promise<void> = Promise.resolve();
+  /** Registered builder extensions keyed by extension ID. */
+  readonly _extensions = Atom.make(Record.empty<string, BuilderExtension>()).pipe(
     Atom.keepAlive,
     Atom.withLabel('graph-builder:extensions'),
   );
-  private readonly _initialized: Record<string, Trigger> = {};
-  private readonly _registry: Registry.Registry;
-  private readonly _graph: Graph;
-
-  constructor({ registry, ...params }: Pick<GraphParams, 'registry' | 'nodes' | 'edges'> = {}) {
+  /** Triggers signalling that a node's resolver has fired at least once. */
+  readonly _initialized: Record<string, Trigger> = {};
+  /** Shared atom registry for reactive subscriptions. */
+  readonly _registry: Registry.Registry;
+  /** Backing graph with internal accessors for node atoms and construction. */
+  readonly _graph: Graph.Graph & {
+    _node: (id: string) => Atom.Writable<Option.Option<Node.Node>>;
+    _constructNode: (node: Node.NodeArg<any>) => Option.Option<Node.Node>;
+  };
+
+  constructor({ registry, ...params }: Pick<Graph.GraphProps, 'registry' | 'nodes' | 'edges'> = {}) {
     this._registry = registry ?? Registry.make();
-    this._graph = new Graph({
+    const graph = Graph.make({
       ...params,
       registry: this._registry,
       onExpand: (id, relation) => this._onExpand(id, relation),
       onInitialize: (id) => this._onInitialize(id),
       onRemoveNode: (id) => this._onRemoveNode(id),
     });
+    // Access internal methods via type assertion since GraphBuilder needs them
+    this._graph = graph as Graph.Graph & {
+      _node: (id: string) => Atom.Writable<Option.Option<Node.Node>>;
+      _constructNode: (node: Node.NodeArg<any>) => Option.Option<Node.Node>;
+    };
   }
 
-  static from(pickle?: string, registry?: Registry.Registry): GraphBuilder {
-    if (!pickle) {
-      return new GraphBuilder({ registry });
-    }
-
-    const { nodes, edges } = JSON.parse(pickle);
-    return new GraphBuilder({ nodes, edges, registry });
-  }
-
-  get graph(): ExpandableGraph {
+  get graph(): Graph.ExpandableGraph {
     return this._graph;
   }
 
@@ -229,70 +172,63 @@ export class GraphBuilder {
     return this._extensions;
   }
 
-  addExtension(extensions: BuilderExtensions): GraphBuilder {
-    flattenExtensions(extensions).forEach((extension) => {
-      const extensions = this._registry.get(this._extensions);
-      this._registry.set(this._extensions, Record.set(extensions, extension.id, extension));
-    });
-    return this;
-  }
-
-  removeExtension(id: string): GraphBuilder {
-    const extensions = this._registry.get(this._extensions);
-    this._registry.set(this._extensions, Record.remove(extensions, id));
-    return this;
-  }
-
-  async explore(
-    // TODO(wittjosiah): Currently defaulting to new registry.
-    //   Currently unsure about how to handle nodes which are expanded in the background.
-    //   This seems like a good place to start.
-    { registry = Registry.make(), source = ROOT_ID, relation = 'outbound', visitor }: GraphBuilderTraverseOptions,
-    path: string[] = [],
-  ): Promise<void> {
-    // Break cycles.
-    if (path.includes(source)) {
-      return;
-    }
-
-    // TODO(wittjosiah): This is a workaround for esm not working in the test runner.
-    //   Switching to vitest is blocked by having node esm versions of echo-schema & echo-signals.
-    if (!isNode()) {
-      const { yieldOrContinue } = await import('main-thread-scheduling');
-      await yieldOrContinue('idle');
-    }
-
-    const node = registry.get(this._graph.nodeOrThrow(source));
-    const shouldContinue = await visitor(node, [...path, node.id]);
-    if (shouldContinue === false) {
-      return;
-    }
-
-    const nodes = Object.values(this._registry.get(this._extensions))
-      .filter((extension) => relation === (extension.relation ?? 'outbound'))
-      .map((extension) => extension.connector)
-      .filter(isNonNullable)
-      .flatMap((connector) => registry.get(connector(this._graph.node(source))));
-
-    await Promise.all(
-      nodes.map((nodeArg) => {
-        registry.set(this._graph._node(nodeArg.id), this._graph._constructNode(nodeArg));
-        return this.explore({ registry, source: nodeArg.id, relation, visitor }, [...path, node.id]);
-      }),
+  /** Apply a set of node changes for a single connector key. */
+  private _applyConnectorUpdate(key: string, nodes: Node.NodeArg<any>[], previous: string[]): void {
+    const { id, relation } = relationFromConnectorKey(key);
+    const ids = nodes.map((node) => node.id);
+    const removed = previous.filter((pid) => !ids.includes(pid));
+    this._connectorPrevious.set(key, ids);
+    this._connectorPreviousArgs.set(key, nodes);
+
+    const currentInlineIds = collectAllInlineIds(nodes);
+    const previousInlineIds = this._connectorPreviousInlineIds.get(key) ?? [];
+    const staleInlineIds = previousInlineIds.filter((pid) => !currentInlineIds.includes(pid));
+    this._connectorPreviousInlineIds.set(key, currentInlineIds);
+
+    Graph.removeNodes(this._graph, staleInlineIds, true);
+    Graph.removeEdges(
+      this._graph,
+      removed.map((target) => ({ source: id, target, relation })),
+      true,
     );
-
-    if (registry !== this._registry) {
-      registry.reset();
-      registry.dispose();
+    Graph.addNodes(this._graph, nodes);
+    Graph.addEdges(
+      this._graph,
+      nodes.map((node) => ({ source: id, target: node.id, relation })),
+    );
+    if (ids.length > 0) {
+      const sortedIds = [...nodes]
+        .sort((a, b) =>
+          byPosition(a.properties ?? ({} as { position?: Position }), b.properties ?? ({} as { position?: Position })),
+        )
+        .map((n) => n.id);
+      Graph.sortEdges(this._graph, id, relation, sortedIds);
     }
   }
 
-  destroy(): void {
-    this._subscriptions.forEach((unsubscribe) => unsubscribe());
-    this._subscriptions.clear();
+  private _scheduleDirtyFlush(): void {
+    if (!this._flushScheduled) {
+      this._flushScheduled = true;
+      this._flushPromise = scheduleTask(
+        () => {
+          this._flushScheduled = false;
+          while (this._dirtyConnectors.size > 0) {
+            const entries = [...this._dirtyConnectors.entries()];
+            this._dirtyConnectors.clear();
+
+            Atom.batch(() => {
+              for (const [key, { nodes, previous }] of entries) {
+                this._applyConnectorUpdate(key, nodes, previous);
+              }
+            });
+          }
+        },
+        { strategy: 'smooth' },
+      );
+    }
   }
 
-  private readonly _resolvers = Atom.family<string, Atom.Atom<Option.Option<NodeArg<any>>>>((id) => {
+  private readonly _resolvers = Atom.family<string, Atom.Atom<Option.Option<Node.NodeArg<any>>>>((id) => {
     return Atom.make((get) => {
       return Function.pipe(
         get(this._extensions),
@@ -307,72 +243,74 @@ export class GraphBuilder {
     });
   });
 
-  private readonly _connectors = Atom.family<string, Atom.Atom<NodeArg<any>[]>>((key) => {
+  private readonly _connectors = Atom.family<string, Atom.Atom<Node.NodeArg<any>[]>>((key) => {
     return Atom.make((get) => {
-      const [id, relation] = key.split('+');
+      const { id, relation } = relationFromConnectorKey(key);
       const node = this._graph.node(id);
 
-      return Function.pipe(
+      const sourceNode = Option.getOrElse(get(node), () => undefined);
+      if (!sourceNode) {
+        return [];
+      }
+
+      const extensions = Function.pipe(
         get(this._extensions),
         Record.values,
-        // TODO(wittjosiah): Sort on write rather than read.
         Array.sortBy(byPosition),
-        Array.filter(({ relation: _relation = 'outbound' }) => _relation === relation),
-        Array.map(({ connector }) => connector?.(node)),
-        Array.filter(isNonNullable),
-        Array.flatMap((result) => get(result)),
+        Array.filter(
+          (ext): ext is BuilderExtension & { connector: NonNullable<BuilderExtension['connector']> } =>
+            Graph.relationKey(ext.relation ?? 'child') === Graph.relationKey(relation) && ext.connector != null,
+        ),
       );
+
+      const nodes: Node.NodeArg<any>[] = [];
+      for (const ext of extensions) {
+        const result = get(ext.connector(node));
+        nodes.push(...result);
+      }
+
+      return nodes;
     }).pipe(Atom.withLabel(`graph-builder:connectors:${key}`));
   });
 
-  private _onExpand(id: string, relation: Relation): void {
+  private _onExpand(id: string, relation: Node.Relation): void {
     log('onExpand', { id, relation, registry: getDebugName(this._registry) });
-    const connectors = this._connectors(`${id}+${relation}`);
+    this._expandRelation(id, relation);
+
+    // TODO(wittjosiah): Remove. This is for backwards compatibility.
+    if (relation.kind === 'child' && relation.direction === 'outbound') {
+      Graph.expand(this._graph, id, 'action');
+    }
+  }
+
+  private _expandRelation(id: string, relation: Node.RelationInput): void {
+    const key = connectorKey(id, relation);
+    const connectors = this._connectors(key);
 
-    let previous: string[] = [];
     const cancel = this._registry.subscribe(
       connectors,
-      (nodes) => {
+      (rawNodes) => {
+        const nodes = qualifyNodeArgs(id)(rawNodes);
+        const previous = this._connectorPrevious.get(key) ?? [];
         const ids = nodes.map((n) => n.id);
-        const removed = previous.filter((id) => !ids.includes(id));
-        previous = ids;
-
-        log('update', { id, relation, ids, removed });
-        const update = () => {
-          Atom.batch(() => {
-            this._graph.removeEdges(
-              removed.map((target) => ({ source: id, target })),
-              true,
-            );
-            this._graph.addNodes(nodes);
-            this._graph.addEdges(
-              nodes.map((node) =>
-                relation === 'outbound' ? { source: id, target: node.id } : { source: node.id, target: id },
-              ),
-            );
-            this._graph.sortEdges(
-              id,
-              relation,
-              nodes.map(({ id }) => id),
-            );
-          });
-        };
-
-        // TODO(wittjosiah): Remove `requestAnimationFrame` once we have a better solution.
-        //  This is a workaround to avoid a race condition where the graph is updated during React render.
-        if (typeof requestAnimationFrame === 'function') {
-          requestAnimationFrame(update);
-        } else {
-          update();
+
+        if (ids.length === previous.length && ids.every((nodeId, idx) => nodeId === previous[idx])) {
+          const prevArgs = this._connectorPreviousArgs.get(key);
+          if (prevArgs && nodeArgsUnchanged(prevArgs, nodes)) {
+            return;
+          }
         }
+
+        log('update', { id, relation, ids });
+        this._dirtyConnectors.set(key, { nodes, previous });
+        this._scheduleDirtyFlush();
       },
       { immediate: true },
     );
 
-    this._subscriptions.set(id, cancel);
+    this._subscriptions.set(subscriptionKey(id, 'expand', key), cancel);
   }
 
-  // TODO(wittjosiah): If the same node is added by a connector, the resolver should probably cancel itself?
   private async _onInitialize(id: string) {
     log('onInitialize', { id });
     const resolver = this._resolvers(id);
@@ -381,59 +319,576 @@ export class GraphBuilder {
       resolver,
       (node) => {
         const trigger = this._initialized[id];
+        const connectorOwned = [...this._connectorPrevious.values()].some((ids) => ids.includes(id));
         Option.match(node, {
           onSome: (node) => {
-            this._graph.addNodes([node]);
+            if (!connectorOwned) {
+              Graph.addNodes(this._graph, [node]);
+              // Connect resolved node to its parent via a child edge.
+              const parentId = getParentId(id);
+              if (parentId) {
+                Graph.addEdges(this._graph, [{ source: parentId, target: id, relation: 'child' }]);
+              }
+            }
             trigger?.wake();
           },
           onNone: () => {
             trigger?.wake();
-            this._graph.removeNodes([id]);
+            if (!connectorOwned) {
+              Graph.removeNodes(this._graph, [id]);
+            }
           },
         });
       },
       { immediate: true },
     );
 
-    this._subscriptions.set(id, cancel);
+    this._subscriptions.set(subscriptionKey(id, 'init'), cancel);
   }
 
   private _onRemoveNode(id: string): void {
-    this._subscriptions.get(id)?.();
-    this._subscriptions.delete(id);
+    for (const [key, cleanup] of this._subscriptions) {
+      if (primaryParts(key)[0] === id) {
+        cleanup();
+        this._subscriptions.delete(key);
+      }
+    }
   }
 }
 
 /**
- * Creates an Atom.Atom<T> from a callback which accesses signals.
- * Will return a new atom instance each time.
+ * Creates a new GraphBuilder instance.
  */
-export const atomFromSignal = <T>(cb: () => T): Atom.Atom<T> => {
-  return Atom.make((get) => {
-    const dispose = effect(() => {
-      get.setSelf(cb());
-    });
+export const make = (params?: Pick<Graph.GraphProps, 'registry' | 'nodes' | 'edges'>): GraphBuilder => {
+  return new GraphBuilderImpl(params);
+};
+
+/**
+ * Creates a GraphBuilder from a serialized pickle string.
+ */
+export const from = (pickle?: string, registry?: Registry.Registry): GraphBuilder => {
+  if (!pickle) {
+    return make({ registry });
+  }
+
+  const { nodes, edges } = JSON.parse(pickle);
+  return make({ nodes, edges, registry });
+};
+
+/**
+ * Implementation helper for addExtension.
+ */
+const addExtensionImpl = (builder: GraphBuilder, extensions: BuilderExtensions): GraphBuilder => {
+  const internal = builder as GraphBuilderImpl;
+  flattenExtensions(extensions).forEach((extension) => {
+    const extensions = internal._registry.get(internal._extensions);
+    internal._registry.set(internal._extensions, Record.set(extensions, extension.id, extension));
+  });
+  return builder;
+};
+
+/**
+ * Add extensions to the graph builder.
+ */
+export function addExtension(builder: GraphBuilder, extensions: BuilderExtensions): GraphBuilder;
+export function addExtension(extensions: BuilderExtensions): (builder: GraphBuilder) => GraphBuilder;
+export function addExtension(
+  builderOrExtensions: GraphBuilder | BuilderExtensions,
+  extensions?: BuilderExtensions,
+): GraphBuilder | ((builder: GraphBuilder) => GraphBuilder) {
+  if (extensions === undefined) {
+    // Curried: addExtension(extensions)
+    const extensions = builderOrExtensions as BuilderExtensions;
+    return (builder: GraphBuilder) => addExtensionImpl(builder, extensions);
+  } else {
+    // Direct: addExtension(builder, extensions)
+    const builder = builderOrExtensions as GraphBuilder;
+    return addExtensionImpl(builder, extensions);
+  }
+}
+
+/**
+ * Implementation helper for removeExtension.
+ */
+const removeExtensionImpl = (builder: GraphBuilder, id: string): GraphBuilder => {
+  const internal = builder as GraphBuilderImpl;
+  const extensions = internal._registry.get(internal._extensions);
+  internal._registry.set(internal._extensions, Record.remove(extensions, id));
+  return builder;
+};
+
+/**
+ * Remove an extension from the graph builder.
+ */
+export function removeExtension(builder: GraphBuilder, id: string): GraphBuilder;
+export function removeExtension(id: string): (builder: GraphBuilder) => GraphBuilder;
+export function removeExtension(
+  builderOrId: GraphBuilder | string,
+  id?: string,
+): GraphBuilder | ((builder: GraphBuilder) => GraphBuilder) {
+  if (typeof builderOrId === 'string') {
+    // Curried: removeExtension(id)
+    const id = builderOrId;
+    return (builder: GraphBuilder) => removeExtensionImpl(builder, id);
+  } else {
+    // Direct: removeExtension(builder, id)
+    const builder = builderOrId;
+    return removeExtensionImpl(builder, id!);
+  }
+}
+
+/**
+ * Implementation helper for explore.
+ */
+const exploreImpl = async (
+  builder: GraphBuilder,
+  options: GraphBuilderTraverseOptions,
+  path: string[] = [],
+): Promise<void> => {
+  const internal = builder as GraphBuilderImpl;
+  const { registry = Registry.make(), source = Node.RootId, relation, visitor } = options;
+  // Break cycles.
+  if (path.includes(source)) {
+    return;
+  }
+
+  await yieldOrContinue('idle');
+
+  const node = registry.get(internal._graph.nodeOrThrow(source));
+  const shouldContinue = await visitor(node, [...path, node.id]);
+  if (shouldContinue === false) {
+    return;
+  }
+
+  const nodes = Function.pipe(
+    internal._registry.get(internal._extensions),
+    Record.values,
+    Array.map((extension) => extension.connector),
+    Array.filter(isNonNullable),
+    Array.flatMap((connector) => registry.get(connector(internal._graph.node(source)))),
+    qualifyNodeArgs(source),
+  );
+
+  await Promise.all(
+    nodes.map((nodeArg) => {
+      registry.set(internal._graph._node(nodeArg.id), internal._graph._constructNode(nodeArg));
+      return exploreImpl(builder, { registry, source: nodeArg.id, relation, visitor }, [...path, node.id]);
+    }),
+  );
+
+  if (registry !== internal._registry) {
+    registry.reset();
+    registry.dispose();
+  }
+};
+
+/**
+ * Explore the graph by traversing it with the given options.
+ */
+export function explore(builder: GraphBuilder, options: GraphBuilderTraverseOptions, path?: string[]): Promise<void>;
+export function explore(
+  options: GraphBuilderTraverseOptions,
+  path?: string[],
+): (builder: GraphBuilder) => Promise<void>;
+export function explore(
+  builderOrOptions: GraphBuilder | GraphBuilderTraverseOptions,
+  optionsOrPath?: GraphBuilderTraverseOptions | string[],
+  path?: string[],
+): Promise<void> | ((builder: GraphBuilder) => Promise<void>) {
+  if (typeof builderOrOptions === 'object' && 'visitor' in builderOrOptions) {
+    // Curried: explore(options, path?)
+    const options = builderOrOptions as GraphBuilderTraverseOptions;
+    const path = Array.isArray(optionsOrPath) ? optionsOrPath : undefined;
+    return (builder: GraphBuilder) => exploreImpl(builder, options, path);
+  } else {
+    // Direct: explore(builder, options, path?)
+    const builder = builderOrOptions as GraphBuilder;
+    const options = optionsOrPath as GraphBuilderTraverseOptions;
+    const pathArg = path ?? (Array.isArray(optionsOrPath) ? optionsOrPath : undefined);
+    return exploreImpl(builder, options, pathArg);
+  }
+}
+
+/**
+ * Implementation helper for destroy.
+ */
+const destroyImpl = (builder: GraphBuilder): void => {
+  const internal = builder as GraphBuilderImpl;
+  internal._subscriptions.forEach((unsubscribe) => unsubscribe());
+  internal._subscriptions.clear();
+};
+
+/**
+ * Destroy the graph builder and clean up resources.
+ */
+export function destroy(builder: GraphBuilder): void;
+export function destroy(): (builder: GraphBuilder) => void;
+export function destroy(builder?: GraphBuilder): void | ((builder: GraphBuilder) => void) {
+  if (builder === undefined) {
+    // Curried: destroy()
+    return (builder: GraphBuilder) => destroyImpl(builder);
+  } else {
+    // Direct: destroy(builder)
+    return destroyImpl(builder);
+  }
+}
+
+/**
+ * Wait for all pending connector updates to be flushed.
+ */
+export const flush = (builder: GraphBuilder): Promise<void> => {
+  return (builder as GraphBuilderImpl)._flushPromise;
+};
+
+//
+// Extension Creation
+//
+
+/**
+ * A graph builder extension is used to add nodes to the graph.
+ *
+ * @param params.id The unique id of the extension.
+ * @param params.relation The relation the graph is being expanded from the existing node.
+ * @param params.position Affects the order the extensions are processed in.
+ * @param params.resolver A function to add nodes to the graph based on just the node id.
+ * @param params.connector A function to add nodes to the graph based on a connection to an existing node.
+ * @param params.actions A function to add actions to the graph based on a connection to an existing node.
+ * @param params.actionGroups A function to add action groups to the graph based on a connection to an existing node.
+ */
+export type CreateExtensionRawOptions = {
+  id: string;
+  relation?: Node.RelationInput;
+  position?: Position;
+  resolver?: ResolverExtension;
+  connector?: ConnectorExtension;
+  actions?: ActionsExtension;
+  actionGroups?: ActionGroupsExtension;
+};
+
+/**
+ * Validates that a graph extension or surface local ID follows NSID conventions:
+ * the final dot-separated segment must be camelCase (letters and digits only,
+ * starting with a letter — no hyphens or underscores). This mirrors the rule
+ * enforced when the id is appended to a plugin's NSID to form a full DXN path.
+ *
+ * @example Valid:   'about', 'devtools', 'integrationsSection'
+ * @example Invalid: 'integration-article', 'plugin-spec'
+ */
+const validateLocalId = (id: string): void => {
+  const finalSegment = id.split('.').pop()!;
+  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(finalSegment)) {
+    throw new Error(
+      `Invalid extension id: "${id}". The final segment "${finalSegment}" must be camelCase (letters and digits only, starting with a letter — no hyphens or underscores).`,
+    );
+  }
+};
+
+/**
+ * Create a graph builder extension (low-level API that works directly with Atoms).
+ */
+export const createExtensionRaw = (extension: CreateExtensionRawOptions): BuilderExtension[] => {
+  const {
+    id,
+    position,
+    relation = 'child',
+    resolver: _resolver,
+    connector: _connector,
+    actions: _actions,
+    actionGroups: _actionGroups,
+  } = extension;
+  validateLocalId(id);
+  const normalizedRelation = normalizeRelation(relation);
+  const getId = (key: string) => `${id}/${key}`;
+
+  const resolver =
+    _resolver && Atom.family((id: string) => _resolver(id).pipe(Atom.withLabel(`graph-builder:_resolver:${id}`)));
+
+  const connector =
+    _connector &&
+    Atom.family((node: Atom.Atom<Option.Option<Node.Node>>) =>
+      _connector(node).pipe(Atom.withLabel(`graph-builder:_connector:${id}`)),
+    );
+
+  const actionGroups =
+    _actionGroups &&
+    Atom.family((node: Atom.Atom<Option.Option<Node.Node>>) =>
+      _actionGroups(node).pipe(Atom.withLabel(`graph-builder:_actionGroups:${id}`)),
+    );
+
+  const actions =
+    _actions &&
+    Atom.family((node: Atom.Atom<Option.Option<Node.Node>>) =>
+      _actions(node).pipe(Atom.withLabel(`graph-builder:_actions:${id}`)),
+    );
+
+  return [
+    resolver ? { id: getId('resolver'), position, resolver } : undefined,
+    connector
+      ? ({
+          id: getId('connector'),
+          position,
+          relation: normalizedRelation,
+          connector: Atom.family((node) =>
+            Atom.make((get) => {
+              try {
+                return get(connector(node));
+              } catch (error) {
+                log.warn('Error in connector', { id: getId('connector'), node, error });
+                return [];
+              }
+            }).pipe(Atom.withLabel(`graph-builder:connector:${id}`)),
+          ),
+        } satisfies BuilderExtension)
+      : undefined,
+    actionGroups
+      ? ({
+          id: getId('actionGroups'),
+          position,
+          relation: Node.actionRelation(),
+          connector: Atom.family((node) =>
+            Atom.make((get) => {
+              try {
+                return get(actionGroups(node)).map((arg) => ({
+                  ...arg,
+                  data: Node.actionGroupSymbol,
+                  type: Node.ActionGroupType,
+                }));
+              } catch (error) {
+                log.warn('Error in actionGroups', { id: getId('actionGroups'), node, error });
+                return [];
+              }
+            }).pipe(Atom.withLabel(`graph-builder:connector:actionGroups:${id}`)),
+          ),
+        } satisfies BuilderExtension)
+      : undefined,
+    actions
+      ? ({
+          id: getId('actions'),
+          position,
+          relation: Node.actionRelation(),
+          connector: Atom.family((node) =>
+            Atom.make((get) => {
+              try {
+                return get(actions(node)).map((arg) => ({ ...arg, type: Node.ActionType }));
+              } catch (error) {
+                log.warn('Error in actions', { id: getId('actions'), node, error });
+                return [];
+              }
+            }).pipe(Atom.withLabel(`graph-builder:connector:actions:${id}`)),
+          ),
+        } satisfies BuilderExtension)
+      : undefined,
+  ].filter(isNonNullable);
+};
+
+/**
+ * Options for creating a graph builder extension with simplified API.
+ * All callbacks must return Effects for dependency injection.
+ * Effects may fail - errors are caught, logged, and the extension returns empty results.
+ */
+export type CreateExtensionOptions<TMatched = Node.Node, R = never> = {
+  id: string;
+  match: (node: Node.Node) => Option.Option<TMatched>;
+  actions?: (
+    matched: TMatched,
+    get: Atom.Context,
+  ) => Effect.Effect<Omit<Node.NodeArg<Node.ActionData<any>, any>, 'type'>[], Error, R>;
+  connector?: (matched: TMatched, get: Atom.Context) => Effect.Effect<Node.NodeArg<any, any>[], Error, R>;
+  resolver?: (id: string, get: Atom.Context) => Effect.Effect<Node.NodeArg<any, any> | null, Error, R>;
+  relation?: Node.RelationInput;
+  position?: Position;
+};
 
-    get.addFinalizer(() => dispose());
+/**
+ * Run an Effect synchronously with the provided context.
+ * If the effect fails, logs the error and returns the fallback value.
+ * @internal
+ */
+const runEffectSyncWithFallback = <T, R>(
+  effect: Effect.Effect<T, Error, R>,
+  context: Context.Context<R>,
+  extensionId: string,
+  fallback: T,
+): T => {
+  return Effect.runSync(
+    effect.pipe(
+      Effect.provide(context),
+      Effect.catchAll((error) => {
+        log.warn('Extension failed', { extension: extensionId, error });
+        return Effect.succeed(fallback);
+      }),
+    ),
+  );
+};
 
-    return cb();
+/**
+ * Create a graph builder extension with simplified API.
+ * Returns an Effect to allow callbacks to access services via dependency injection.
+ */
+export const createExtension = <TMatched = Node.Node, R = never>(
+  options: CreateExtensionOptions<TMatched, R>,
+): Effect.Effect<BuilderExtension[], never, R> =>
+  Effect.map(Effect.context<R>(), (context) => {
+    const { id, match, actions, connector, resolver, relation, position } = options;
+
+    const connectorExtension = connector ? createConnectorWithRuntime(id, match, connector, context) : undefined;
+
+    const actionsExtension = actions
+      ? (node: Atom.Atom<Option.Option<Node.Node>>) =>
+          Atom.make((get) =>
+            Function.pipe(
+              get(node),
+              Option.flatMap(match),
+              Option.map((matched) =>
+                runEffectSyncWithFallback(actions(matched, get), context, id, []).map((action) => ({
+                  ...action,
+                  // Attach captured context for action execution.
+                  _actionContext: context,
+                })),
+              ),
+              Option.getOrElse(() => []),
+            ),
+          )
+      : undefined;
+
+    const resolverExtension = resolver
+      ? (nodeId: string) =>
+          Atom.make((get) => runEffectSyncWithFallback(resolver(nodeId, get), context, id, null) ?? null)
+      : undefined;
+
+    return createExtensionRaw({
+      id,
+      relation,
+      position,
+      connector: connectorExtension,
+      actions: actionsExtension,
+      resolver: resolverExtension,
+    });
   });
+
+/**
+ * Create a connector extension from a matcher and factory function.
+ * The factory's data type is inferred from the matcher's return type.
+ */
+export const createConnector = <TData>(
+  matcher: (node: Node.Node) => Option.Option<TData>,
+  factory: (data: TData, get: Atom.Context) => Node.NodeArg<any>[],
+): ConnectorExtension => {
+  return (node: Atom.Atom<Option.Option<Node.Node>>) =>
+    Atom.make((get) =>
+      Function.pipe(
+        get(node),
+        Option.flatMap(matcher),
+        Option.map((data) => factory(data, get)),
+        Option.getOrElse(() => []),
+      ),
+    );
 };
 
-const observableFamily = Atom.family((observable: MulticastObservable<any>) => {
-  return Atom.make((get) => {
-    const subscription = observable.subscribe((value) => get.setSelf(value));
+/**
+ * Create a connector extension from a matcher and factory function with Effect support.
+ * The factory must return an Effect. Errors are caught and logged.
+ * @internal
+ */
+const createConnectorWithRuntime = <TData, R>(
+  extensionId: string,
+  matcher: (node: Node.Node) => Option.Option<TData>,
+  factory: (data: TData, get: Atom.Context) => Effect.Effect<Node.NodeArg<any>[], Error, R>,
+  context: Context.Context<R>,
+): ConnectorExtension => {
+  return (node: Atom.Atom<Option.Option<Node.Node>>) =>
+    Atom.make((get) =>
+      Function.pipe(
+        get(node),
+        Option.flatMap(matcher),
+        Option.map((data) => runEffectSyncWithFallback(factory(data, get), context, extensionId, [])),
+        Option.getOrElse(() => []),
+      ),
+    );
+};
 
-    get.addFinalizer(() => subscription.unsubscribe());
+/**
+ * Options for creating a type-based extension.
+ * All callbacks must return Effects for dependency injection.
+ * Effects may fail - errors are caught, logged, and the extension returns empty results.
+ */
+export type CreateTypeExtensionOptions<T extends Type.AnyEntity = Type.AnyEntity, R = never> = {
+  id: string;
+  type: T;
+  actions?: (
+    object: Type.InstanceType<T>,
+    get: Atom.Context,
+  ) => Effect.Effect<Omit<Node.NodeArg<Node.ActionData<any>>, 'type'>[], Error, R>;
+  connector?: (object: Type.InstanceType<T>, get: Atom.Context) => Effect.Effect<Node.NodeArg<any>[], Error, R>;
+  relation?: Node.RelationInput;
+  position?: Position;
+};
 
-    return observable.get();
+/**
+ * Create an extension that matches nodes by schema type.
+ * The entity type is inferred from the schema type and works for both object and relation schemas.
+ * Returns an Effect to allow callbacks to access services via dependency injection.
+ */
+export const createTypeExtension = <T extends Type.AnyEntity, R = never>(
+  options: CreateTypeExtensionOptions<T, R>,
+): Effect.Effect<BuilderExtension[], never, R> => {
+  const { id, type, actions, connector, relation, position } = options;
+  return createExtension<Type.InstanceType<T>, R>({
+    id,
+    match: NodeMatcher.whenEchoType(type),
+    actions,
+    connector,
+    relation,
+    position,
   });
-});
+};
+
+//
+// Extension Utilities
+//
+
+/**
+ * Qualify node IDs by prefixing with the parent path.
+ * Validates that segment IDs do not contain the path separator.
+ * Recursively qualifies inline child nodes.
+ */
+const qualifyNodeArgs =
+  (parentId: string) =>
+  (nodes: Node.NodeArg<any>[]): Node.NodeArg<any>[] =>
+    nodes.map((node) => {
+      validateSegmentId(node.id);
+      const qualified = qualifyId(parentId, node.id);
+      return {
+        ...node,
+        id: qualified,
+        nodes: node.nodes ? qualifyNodeArgs(qualified)(node.nodes) : undefined,
+      };
+    });
 
 /**
- * Creates an Atom.Atom<T> from a MulticastObservable<T>
- * Will return the same atom instance for the same observable.
+ * Recursively collect all inline-descendant IDs (the `nodes` arrays at every level)
+ * from a list of top-level NodeArgs. Top-level IDs are excluded because they are
+ * already tracked via `_connectorPrevious`.
  */
-export const atomFromObservable = <T>(observable: MulticastObservable<T>): Atom.Atom<T> => {
-  return observableFamily(observable) as Atom.Atom<T>;
+const collectAllInlineIds = (nodes: Node.NodeArg<any>[]): string[] =>
+  nodes.flatMap((node) =>
+    node.nodes ? [...node.nodes.map((child) => child.id), ...collectAllInlineIds(node.nodes)] : [],
+  );
+
+const connectorKey = (id: string, relation: Node.RelationInput): string => primaryKey(id, Graph.relationKey(relation));
+
+const relationFromConnectorKey = (key: string): { id: string; relation: Node.Relation } => {
+  const [id, encodedRelation] = primaryParts(key);
+  return { id, relation: Graph.relationFromKey(encodedRelation) };
+};
+
+const subscriptionKey = (id: string, kind: string, detail?: string): string =>
+  detail != null ? primaryKey(id, kind, detail) : primaryKey(id, kind);
+
+export const flattenExtensions = (extension: BuilderExtensions, acc: BuilderExtension[] = []): BuilderExtension[] => {
+  if (Array.isArray(extension)) {
+    return [...acc, ...extension.flatMap((ext) => flattenExtensions(ext, acc))];
+  } else {
+    return [...acc, extension];
+  }
 };