@dxos/app-graph 0.9.0 → 0.9.1-staging.ee54ba693a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-graph",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "Constructs knowledge graphs for the purpose of building applications on top of",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -41,39 +41,39 @@
   ],
   "dependencies": {
     "main-thread-scheduling": "^14.1.1",
-    "@dxos/async": "0.9.0",
-    "@dxos/debug": "0.9.0",
-    "@dxos/echo": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/util": "0.9.0",
-    "@dxos/keys": "0.9.0"
+    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
+    "@dxos/async": "0.9.1-staging.ee54ba693a",
+    "@dxos/debug": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo": "0.9.1-staging.ee54ba693a",
+    "@dxos/keys": "0.9.1-staging.ee54ba693a",
+    "@dxos/log": "0.9.1-staging.ee54ba693a",
+    "@dxos/util": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
-    "@effect/platform": "0.96.1",
-    "@types/react": "~19.2.7",
+    "@effect/platform": "0.96.2",
+    "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
     "vite": "^8.0.16",
-    "@dxos/random": "0.9.0",
-    "@dxos/react-client": "0.9.0",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/react-ui-list": "0.9.0",
-    "@dxos/react-ui-tabs": "0.9.0",
-    "@dxos/storybook-utils": "0.9.0",
-    "@dxos/ui-theme": "0.9.0"
+    "@dxos/random": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-list": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/storybook-utils": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-tabs": "0.9.1-staging.ee54ba693a"
   },
   "peerDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
-    "@effect/platform": "0.96.1",
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/ui-theme": "0.9.0"
+    "@effect/platform": "0.96.2",
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a"
   },
   "publishConfig": {
     "access": "public"

package/src/graph-builder.test.ts

@@ -609,6 +609,123 @@ describe('GraphBuilder', () => {
 
         expect(Graph.getNode(graph, 'root/parent-node/child/grandchild').pipe(Option.getOrNull)?.data).to.equal('v2');
       });
+
+      describe('NodeArg.actions', () => {
+        const withInlineAction = (actionId = 'delete'): Node.NodeArg<any> => ({
+          id: 'parent-node',
+          type: EXAMPLE_TYPE,
+          data: null,
+          actions: [Node.makeAction({ id: actionId, data: () => Effect.void, properties: { label: 'Delete' } })],
+        });
+
+        test('inline actions appear on connector-produced nodes', async ({ expect }) => {
+          const { registry, builder, graph, nodesAtom } = makeGraph();
+          registry.set(nodesAtom, [withInlineAction()]);
+          await GraphBuilder.flush(builder);
+
+          const actions = registry.get(graph.actions('root/parent-node'));
+          expect(actions).to.have.length(1);
+          expect(actions[0].id).to.equal('root/parent-node/delete');
+        });
+
+        test('inline actions reactively update when connector re-runs', async ({ expect }) => {
+          const { registry, builder, graph, nodesAtom } = makeGraph();
+          registry.set(nodesAtom, [withInlineAction('delete')]);
+          await GraphBuilder.flush(builder);
+
+          expect(registry.get(graph.actions('root/parent-node'))).to.have.length(1);
+
+          registry.set(nodesAtom, [{ ...withInlineAction('delete'), actions: [] }]);
+          await GraphBuilder.flush(builder);
+
+          expect(registry.get(graph.actions('root/parent-node'))).to.have.length(0);
+        });
+
+        test('inline actions appear on inline child nodes (filter pattern)', async ({ expect }) => {
+          const { registry, builder, graph, nodesAtom } = makeGraph();
+
+          const withFilterChild = (): Node.NodeArg<any> => ({
+            id: 'parent-node',
+            type: EXAMPLE_TYPE,
+            data: null,
+            nodes: [
+              {
+                id: 'filter',
+                type: EXAMPLE_TYPE,
+                data: null,
+                actions: [Node.makeAction({ id: 'delete', data: () => Effect.void, properties: { label: 'Delete' } })],
+              },
+            ],
+          });
+
+          registry.set(nodesAtom, [withFilterChild()]);
+          await GraphBuilder.flush(builder);
+
+          const filterNodeId = 'root/parent-node/filter';
+          expect(Graph.getNode(graph, filterNodeId).pipe(Option.getOrNull)).to.not.be.null;
+
+          const actions = registry.get(graph.actions(filterNodeId));
+          expect(actions).to.have.length(1);
+          expect(actions[0].id).to.equal(`${filterNodeId}/delete`);
+        });
+
+        test('inline actions on child nodes are removed when child is removed', async ({ expect }) => {
+          const { registry, builder, graph, nodesAtom } = makeGraph();
+
+          const filterChild: Node.NodeArg<any> = {
+            id: 'filter',
+            type: EXAMPLE_TYPE,
+            data: null,
+            actions: [Node.makeAction({ id: 'delete', data: () => Effect.void, properties: { label: 'Delete' } })],
+          };
+
+          registry.set(nodesAtom, [{ id: 'parent-node', type: EXAMPLE_TYPE, data: null, nodes: [filterChild] }]);
+          await GraphBuilder.flush(builder);
+
+          expect(Graph.getNode(graph, 'root/parent-node/filter/delete').pipe(Option.getOrNull)).to.not.be.null;
+
+          // Remove the filter child entirely.
+          registry.set(nodesAtom, [{ id: 'parent-node', type: EXAMPLE_TYPE, data: null, nodes: [] }]);
+          await GraphBuilder.flush(builder);
+
+          expect(Graph.getNode(graph, 'root/parent-node/filter').pipe(Option.getOrNull)).to.be.null;
+          expect(Graph.getNode(graph, 'root/parent-node/filter/delete').pipe(Option.getOrNull)).to.be.null;
+        });
+      });
+
+      test('are reordered when connector re-runs with different child order', async ({ expect }) => {
+        const makeMultiParent = (childIds: string[]): Node.NodeArg<any> => ({
+          id: 'parent-node',
+          type: EXAMPLE_TYPE,
+          data: null,
+          nodes: childIds.map((cid) => ({ id: cid, type: EXAMPLE_TYPE, data: cid })),
+        });
+
+        const { registry, builder, graph, nodesAtom } = makeGraph();
+        registry.set(nodesAtom, [makeMultiParent(['c1', 'c2', 'c3'])]);
+        await GraphBuilder.flush(builder);
+
+        {
+          const children = registry.get(graph.connections('root/parent-node', 'child'));
+          expect(children.map((n) => n.id)).to.deep.equal([
+            'root/parent-node/c1',
+            'root/parent-node/c2',
+            'root/parent-node/c3',
+          ]);
+        }
+
+        registry.set(nodesAtom, [makeMultiParent(['c3', 'c1', 'c2'])]);
+        await GraphBuilder.flush(builder);
+
+        {
+          const children = registry.get(graph.connections('root/parent-node', 'child'));
+          expect(children.map((n) => n.id)).to.deep.equal([
+            'root/parent-node/c3',
+            'root/parent-node/c1',
+            'root/parent-node/c2',
+          ]);
+        }
+      });
     });
 
     test('sort edges', async () => {
@@ -1208,7 +1325,7 @@ describe('GraphBuilder', () => {
           GraphBuilder.createExtension({
             id: 'failingExtension',
             match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
-            connector: (node, get) => Effect.fail(new Error('Connector failed intentionally')),
+            connector: (node, get) => Effect.die('Connector failed intentionally'),
           }),
         );
 
@@ -1235,7 +1352,7 @@ describe('GraphBuilder', () => {
           GraphBuilder.createExtension({
             id: 'failingActionsExtension',
             match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
-            actions: (node, get) => Effect.fail(new Error('Actions failed intentionally')),
+            actions: (node, get) => Effect.die('Actions failed intentionally'),
           }),
         );
 
@@ -1262,7 +1379,7 @@ describe('GraphBuilder', () => {
           GraphBuilder.createExtension({
             id: 'failingResolverExtension',
             match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
-            resolver: (id, get) => Effect.fail(new Error('Resolver failed intentionally')),
+            resolver: (id, get) => Effect.die('Resolver failed intentionally'),
           }),
         );
 
@@ -1286,7 +1403,7 @@ describe('GraphBuilder', () => {
           GraphBuilder.createExtension({
             id: 'failingExtension',
             match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
-            connector: (node, get) => Effect.fail(new Error('This one fails')),
+            connector: (node, get) => Effect.die('This one fails'),
           }),
         );
 

package/src/graph-builder.ts

@@ -14,7 +14,7 @@ import * as Record from 'effect/Record';
 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, isNonNullable } from '@dxos/util';
+import { type MaybePromise, Position, getDebugName, isNonNullable } from '@dxos/util';
 
 import { scheduleTask, yieldOrContinue } from '#scheduler';
 
@@ -63,7 +63,7 @@ export type ActionGroupsExtension = (
 
 export type BuilderExtension = Readonly<{
   id: string;
-  position?: Position;
+  position?: Position.Position;
   relation?: Node.RelationInput;
   resolver?: ResolverExtension;
   connector?: (node: Atom.Atom<Option.Option<Node.Node>>) => Atom.Atom<Node.NodeArg<any>[]>;
@@ -198,9 +198,7 @@ class GraphBuilderImpl implements GraphBuilder {
     );
     if (ids.length > 0) {
       const sortedIds = [...nodes]
-        .sort((a, b) =>
-          byPosition(a.properties ?? ({} as { position?: Position }), b.properties ?? ({} as { position?: Position })),
-        )
+        .sort((a, b) => Position.compare({ position: a.properties?.position }, { position: b.properties?.position }))
         .map((n) => n.id);
       Graph.sortEdges(this._graph, id, relation, sortedIds);
     }
@@ -233,7 +231,7 @@ class GraphBuilderImpl implements GraphBuilder {
       return Function.pipe(
         get(this._extensions),
         Record.values,
-        Array.sortBy(byPosition),
+        Array.sortBy(Position.compare),
         Array.map(({ resolver }) => resolver),
         Array.filter(isNonNullable),
         Array.map((resolver) => get(resolver(id))),
@@ -256,7 +254,7 @@ class GraphBuilderImpl implements GraphBuilder {
       const extensions = Function.pipe(
         get(this._extensions),
         Record.values,
-        Array.sortBy(byPosition),
+        Array.sortBy(Position.compare),
         Array.filter(
           (ext): ext is BuilderExtension & { connector: NonNullable<BuilderExtension['connector']> } =>
             Graph.relationKey(ext.relation ?? 'child') === Graph.relationKey(relation) && ext.connector != null,
@@ -558,7 +556,7 @@ export const flush = (builder: GraphBuilder): Promise<void> => {
 export type CreateExtensionRawOptions = {
   id: string;
   relation?: Node.RelationInput;
-  position?: Position;
+  position?: Position.Position;
   resolver?: ResolverExtension;
   connector?: ConnectorExtension;
   actions?: ActionsExtension;
@@ -684,28 +682,29 @@ export const createExtensionRaw = (extension: CreateExtensionRawOptions): Builde
 /**
  * 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.
+ * Effects may defect — defects are caught, logged, and the extension returns empty results.
+ * Use Effect.orDie on any failable effects inside callbacks.
  */
 export type CreateExtensionOptions<TMatched = Node.Node, R = never> = {
   id: string;
-  match: (node: Node.Node) => Option.Option<TMatched>;
+  match: (node: Node.Node, get: Atom.Context) => 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>;
+  ) => Effect.Effect<Omit<Node.NodeArg<Node.ActionData<any>, any>, 'type'>[], never, R>;
+  connector?: (matched: TMatched, get: Atom.Context) => Effect.Effect<Node.NodeArg<any, any>[], never, R>;
+  resolver?: (id: string, get: Atom.Context) => Effect.Effect<Node.NodeArg<any, any> | null, never, R>;
   relation?: Node.RelationInput;
-  position?: Position;
+  position?: Position.Position;
 };
 
 /**
  * Run an Effect synchronously with the provided context.
- * If the effect fails, logs the error and returns the fallback value.
+ * Defects are caught, logged, and the fallback value is returned.
  * @internal
  */
 const runEffectSyncWithFallback = <T, R>(
-  effect: Effect.Effect<T, Error, R>,
+  effect: Effect.Effect<T, never, R>,
   context: Context.Context<R>,
   extensionId: string,
   fallback: T,
@@ -713,8 +712,8 @@ const runEffectSyncWithFallback = <T, R>(
   return Effect.runSync(
     effect.pipe(
       Effect.provide(context),
-      Effect.catchAll((error) => {
-        log.warn('Extension failed', { extension: extensionId, error });
+      Effect.catchAllDefect((defect) => {
+        log.warn('Extension failed', { extension: extensionId, defect });
         return Effect.succeed(fallback);
       }),
     ),
@@ -738,7 +737,7 @@ export const createExtension = <TMatched = Node.Node, R = never>(
           Atom.make((get) =>
             Function.pipe(
               get(node),
-              Option.flatMap(match),
+              Option.flatMap((matchedNode) => match(matchedNode, get)),
               Option.map((matched) =>
                 runEffectSyncWithFallback(actions(matched, get), context, id, []).map((action) => ({
                   ...action,
@@ -771,14 +770,14 @@ export const createExtension = <TMatched = Node.Node, R = never>(
  * The factory's data type is inferred from the matcher's return type.
  */
 export const createConnector = <TData>(
-  matcher: (node: Node.Node) => Option.Option<TData>,
+  matcher: (node: Node.Node, get: Atom.Context) => 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.flatMap((matchedNode) => matcher(matchedNode, get)),
         Option.map((data) => factory(data, get)),
         Option.getOrElse(() => []),
       ),
@@ -792,15 +791,15 @@ export const createConnector = <TData>(
  */
 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>,
+  matcher: (node: Node.Node, get: Atom.Context) => Option.Option<TData>,
+  factory: (data: TData, get: Atom.Context) => Effect.Effect<Node.NodeArg<any>[], never, 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.flatMap((matchedNode) => matcher(matchedNode, get)),
         Option.map((data) => runEffectSyncWithFallback(factory(data, get), context, extensionId, [])),
         Option.getOrElse(() => []),
       ),
@@ -818,10 +817,10 @@ export type CreateTypeExtensionOptions<T extends Type.AnyEntity = Type.AnyEntity
   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>;
+  ) => Effect.Effect<Omit<Node.NodeArg<Node.ActionData<any>>, 'type'>[], never, R>;
+  connector?: (object: Type.InstanceType<T>, get: Atom.Context) => Effect.Effect<Node.NodeArg<any>[], never, R>;
   relation?: Node.RelationInput;
-  position?: Position;
+  position?: Position.Position;
 };
 
 /**
@@ -862,6 +861,7 @@ const qualifyNodeArgs =
         ...node,
         id: qualified,
         nodes: node.nodes ? qualifyNodeArgs(qualified)(node.nodes) : undefined,
+        actions: node.actions ? qualifyNodeArgs(qualified)(node.actions) : undefined,
       };
     });
 
@@ -871,9 +871,12 @@ const qualifyNodeArgs =
  * already tracked via `_connectorPrevious`.
  */
 const collectAllInlineIds = (nodes: Node.NodeArg<any>[]): string[] =>
-  nodes.flatMap((node) =>
-    node.nodes ? [...node.nodes.map((child) => child.id), ...collectAllInlineIds(node.nodes)] : [],
-  );
+  nodes.flatMap((node) => {
+    const childNodes = node.nodes ?? [];
+    const actionNodes = node.actions ?? [];
+    const allInline = [...childNodes, ...actionNodes];
+    return allInline.length > 0 ? [...allInline.map((child) => child.id), ...collectAllInlineIds(allInline)] : [];
+  });
 
 const connectorKey = (id: string, relation: Node.RelationInput): string => primaryKey(id, Graph.relationKey(relation));
 

package/src/graph.ts

@@ -861,6 +861,7 @@ const addNodeImpl = <T extends WritableGraph>(graph: T, nodeArg: Node.NodeArg<an
   // Extract known NodeArg fields, preserve any extra fields (like _actionContext) in rest.
   const {
     nodes,
+    actions,
     edges,
     id,
     type,
@@ -917,6 +918,25 @@ const addNodeImpl = <T extends WritableGraph>(graph: T, nodeArg: Node.NodeArg<an
     addNodesImpl(graph, nodes);
     const _edges = nodes.map((node) => ({ source: id, target: node.id, relation: 'child' as const }));
     addEdgesImpl(graph, _edges);
+    sortEdgesImpl(
+      graph,
+      id,
+      'child',
+      nodes.map((n) => n.id),
+    );
+  }
+
+  if (actions) {
+    addNodesImpl(graph, actions);
+    const actionRelation = Node.actionRelation();
+    const _edges = actions.map((node) => ({ source: id, target: node.id, relation: actionRelation }));
+    addEdgesImpl(graph, _edges);
+    sortEdgesImpl(
+      graph,
+      id,
+      actionRelation,
+      actions.map((node) => node.id),
+    );
   }
 
   if (edges) {

package/src/index.ts

@@ -8,7 +8,7 @@ export * as Graph from './graph';
 export * as GraphBuilder from './graph-builder';
 export * as Node from './node';
 export * as NodeMatcher from './node-matcher';
-export { qualifyId, getParentId, getSegmentId } from './util';
+export { getParentId, getSegmentId, qualifyId } from './util';
 
 // TODO(wittjosiah): Direct re-export needed for portable type references.
 export type { BuilderExtensions } from './graph-builder';

package/src/node-matcher.test.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Atom, Registry } from '@effect-atom/atom-react';
 import * as Option from 'effect/Option';
 import { describe, expect, test } from 'vitest';
 
@@ -105,7 +106,7 @@ describe('NodeMatcher', () => {
         data: { name: 'Test' },
       };
       const matcher = NodeMatcher.whenEchoType(TestSchema.Person);
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isNone(result)).to.be.true;
     });
 
@@ -118,7 +119,7 @@ describe('NodeMatcher', () => {
         data: testObject,
       };
       const matcher = NodeMatcher.whenEchoType(TestSchema.Person);
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isSome(result)).to.be.true;
       expect(Option.getOrNull(result)).to.equal(testObject);
     });
@@ -159,7 +160,7 @@ describe('NodeMatcher', () => {
         data: testObject,
       };
       const matcher = NodeMatcher.whenEchoTypeMatches(TestSchema.Person);
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isSome(result)).to.be.true;
       expect(Option.getOrNull(result)).to.equal(node);
     });
@@ -172,7 +173,7 @@ describe('NodeMatcher', () => {
         data: { name: 'Test' },
       };
       const matcher = NodeMatcher.whenEchoTypeMatches(TestSchema.Person);
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isNone(result)).to.be.true;
     });
   });
@@ -212,7 +213,7 @@ describe('NodeMatcher', () => {
         data: null,
       };
       const matcher = NodeMatcher.whenNot(NodeMatcher.whenRoot);
-      const result = matcher(rootNode);
+      const result = matcher(rootNode, get);
       expect(Option.isNone(result)).to.be.true;
     });
 
@@ -224,7 +225,7 @@ describe('NodeMatcher', () => {
         data: null,
       };
       const matcher = NodeMatcher.whenNot(NodeMatcher.whenRoot);
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isSome(result)).to.be.true;
       expect(Option.getOrNull(result)).to.equal(node);
     });
@@ -242,7 +243,7 @@ describe('NodeMatcher', () => {
         NodeMatcher.whenEchoObjectMatches,
         NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(TestSchema.Person)),
       );
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isNone(result)).to.be.true;
     });
   });
@@ -256,7 +257,7 @@ describe('NodeMatcher', () => {
         data: null,
       };
       const matcher = NodeMatcher.whenAll(NodeMatcher.whenId('test-id'), NodeMatcher.whenNodeType('test-type'));
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isSome(result)).to.be.true;
     });
 
@@ -268,7 +269,7 @@ describe('NodeMatcher', () => {
         data: null,
       };
       const matcher = NodeMatcher.whenAll(NodeMatcher.whenId('test-id'), NodeMatcher.whenNodeType('other-type'));
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isNone(result)).to.be.true;
     });
   });
@@ -282,7 +283,7 @@ describe('NodeMatcher', () => {
         data: null,
       };
       const matcher = NodeMatcher.whenAny(NodeMatcher.whenId('other-id'), NodeMatcher.whenNodeType('test-type'));
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isSome(result)).to.be.true;
     });
 
@@ -294,8 +295,13 @@ describe('NodeMatcher', () => {
         data: null,
       };
       const matcher = NodeMatcher.whenAny(NodeMatcher.whenId('other-id'), NodeMatcher.whenNodeType('other-type'));
-      const result = matcher(node);
+      const result = matcher(node, get);
       expect(Option.isNone(result)).to.be.true;
     });
   });
 });
+
+// Real reactive context for matchers that take `get`. The matchers under test
+// inspect only the node, so the context is never read — it satisfies the arity.
+const captureContext = (): Atom.Context => Registry.make().get(Atom.make((context): Atom.Context => context));
+const get = captureContext();

package/src/node-matcher.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Atom } from '@effect-atom/atom-react';
 import * as Option from 'effect/Option';
 
 import { Entity, Obj, type Type } from '@dxos/echo';
@@ -12,10 +13,15 @@ import * as Node from './node';
  * Type for a node matcher function that returns an Option of the matched data.
  * Matchers are used to filter and transform nodes in the app graph.
  *
+ * Matchers receive the reactive atom context (`get`) so a match decision can
+ * depend on reactive state (e.g. an ECHO query for related objects). Reading an
+ * atom via `get` subscribes the extension to it, so the match re-runs when that
+ * state changes. Matchers that only inspect the node itself simply ignore `get`.
+ *
  * @template TData - The type of data returned when the matcher succeeds.
  *   Defaults to Node.Node, but can be a more specific type (e.g., an ECHO entity).
  */
-export type NodeMatcher<TData = Node.Node> = (node: Node.Node) => Option.Option<TData>;
+export type NodeMatcher<TData = Node.Node> = (node: Node.Node, get: Atom.Context) => Option.Option<TData>;
 
 //
 // Basic Node Matchers
@@ -176,10 +182,10 @@ export const whenAll: {
   (...matchers: NodeMatcher<any>[]): NodeMatcher<any>;
 } =
   (...matchers: NodeMatcher<any>[]): NodeMatcher<any> =>
-  (node: Node.Node) => {
+  (node: Node.Node, get: Atom.Context) => {
     let first: Option.Option<any> = Option.none();
     for (const candidate of matchers) {
-      const result = candidate(node);
+      const result = candidate(node, get);
       if (Option.isNone(result)) {
         return Option.none();
       }
@@ -214,9 +220,9 @@ export const whenAny: {
   (...matchers: NodeMatcher<any>[]): NodeMatcher<any>;
 } =
   (...matchers: NodeMatcher<any>[]): NodeMatcher<any> =>
-  (node: Node.Node) => {
+  (node: Node.Node, get: Atom.Context) => {
     for (const candidate of matchers) {
-      const result = candidate(node);
+      const result = candidate(node, get);
       if (Option.isSome(result)) {
         return result;
       }
@@ -309,5 +315,5 @@ export const whenEchoObjectMatches = (node: Node.Node): Option.Option<Node.Node>
  */
 export const whenNot =
   (matcher: NodeMatcher<any>): NodeMatcher<unknown> =>
-  (node: Node.Node): Option.Option<unknown> =>
-    Option.isNone(matcher(node)) ? Option.some(node) : Option.none();
+  (node: Node.Node, get: Atom.Context): Option.Option<unknown> =>
+    Option.isNone(matcher(node, get)) ? Option.some(node) : Option.none();

package/src/node.ts

@@ -95,6 +95,9 @@ export type NodeArg<TData, TProperties extends Record<string, any> = Record<stri
   /** Will automatically add nodes with an edge from this node to each. */
   nodes?: NodeArg<unknown>[];
 
+  /** Will automatically add actions with an edge from this node to each. */
+  actions?: NodeArg<ActionData<any>>[];
+
   /** Will automatically add specified edges. */
   edges?: [string, RelationInput][];
 };

package/src/util.ts

@@ -67,7 +67,8 @@ export const nodeArgsUnchanged = (prev: Node.NodeArg<any>[], next: Node.NodeArg<
       prevNode.type === nextNode.type &&
       shallowEqual(prevNode.data, nextNode.data) &&
       shallowEqual(prevNode.properties, nextNode.properties) &&
-      nodeArgsUnchanged(prevNode.nodes ?? [], nextNode.nodes ?? [])
+      nodeArgsUnchanged(prevNode.nodes ?? [], nextNode.nodes ?? []) &&
+      nodeArgsUnchanged(prevNode.actions ?? [], nextNode.actions ?? [])
     );
   });
 };