@dxos/app-graph 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/graph-builder.ts

@@ -11,17 +11,26 @@ import * as Option from 'effect/Option';
 import * as Pipeable from 'effect/Pipeable';
 import * as Record from 'effect/Record';
 import type * as Schema from 'effect/Schema';
-import { scheduleTask, yieldOrContinue } from 'main-thread-scheduling';
 
 import { type CleanupFn, type Trigger } from '@dxos/async';
 import { type Entity, type Type } from '@dxos/echo';
 import { log } from '@dxos/log';
 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 { Separators, nodeArgsUnchanged, normalizeRelation, qualifyId, validateSegmentId } from './util';
+import {
+  getParentId,
+  nodeArgsUnchanged,
+  normalizeRelation,
+  primaryKey,
+  primaryParts,
+  qualifyId,
+  validateSegmentId,
+} from './util';
 
 //
 // Extension Types
@@ -55,7 +64,7 @@ export type ActionGroupsExtension = (
 
 export type BuilderExtension = Readonly<{
   id: string;
-  position: Position;
+  position?: Position;
   relation?: Node.RelationInput;
   resolver?: ResolverExtension;
   connector?: (node: Atom.Atom<Option.Option<Node.Node>>) => Atom.Atom<Node.NodeArg<any>[]>;
@@ -117,6 +126,8 @@ class GraphBuilderImpl implements GraphBuilder {
   >();
   /** 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. */
@@ -170,6 +181,12 @@ class GraphBuilderImpl implements GraphBuilder {
     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 })),
@@ -295,7 +312,6 @@ class GraphBuilderImpl implements GraphBuilder {
     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);
@@ -304,17 +320,24 @@ class GraphBuilderImpl implements GraphBuilder {
       resolver,
       (node) => {
         const trigger = this._initialized[id];
+        const connectorOwned = [...this._connectorPrevious.values()].some((ids) => ids.includes(id));
         Option.match(node, {
           onSome: (node) => {
-            const connectorOwned = [...this._connectorPrevious.values()].some((ids) => ids.includes(id));
             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();
-            Graph.removeNodes(this._graph, [id]);
+            if (!connectorOwned) {
+              Graph.removeNodes(this._graph, [id]);
+            }
           },
         });
       },
@@ -325,9 +348,8 @@ class GraphBuilderImpl implements GraphBuilder {
   }
 
   private _onRemoveNode(id: string): void {
-    const prefix = `${id}${Separators.primary}`;
     for (const [key, cleanup] of this._subscriptions) {
-      if (key.startsWith(prefix)) {
+      if (primaryParts(key)[0] === id) {
         cleanup();
         this._subscriptions.delete(key);
       }
@@ -550,7 +572,7 @@ export type CreateExtensionRawOptions = {
 export const createExtensionRaw = (extension: CreateExtensionRawOptions): BuilderExtension[] => {
   const {
     id,
-    position = 'static',
+    position,
     relation = 'child',
     resolver: _resolver,
     connector: _connector,
@@ -828,19 +850,25 @@ const qualifyNodeArgs =
       };
     });
 
-const connectorKey = (id: string, relation: Node.RelationInput): string =>
-  `${id}${Separators.primary}${Graph.relationKey(relation)}`;
+/**
+ * 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`.
+ */
+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 separatorIndex = key.indexOf(Separators.primary);
-  const id = key.slice(0, separatorIndex);
-  return { id, relation: Graph.relationFromKey(key.slice(separatorIndex + 1)) };
+  const [id, encodedRelation] = primaryParts(key);
+  return { id, relation: Graph.relationFromKey(encodedRelation) };
 };
 
 const subscriptionKey = (id: string, kind: string, detail?: string): string =>
-  detail != null
-    ? `${id}${Separators.primary}${kind}${Separators.primary}${detail}`
-    : `${id}${Separators.primary}${kind}`;
+  detail != null ? primaryKey(id, kind, detail) : primaryKey(id, kind);
 
 export const flattenExtensions = (extension: BuilderExtensions, acc: BuilderExtension[] = []): BuilderExtension[] => {
   if (Array.isArray(extension)) {

package/src/graph.ts

@@ -15,7 +15,7 @@ import { log } from '@dxos/log';
 import { type MakeOptional, isNonNullable } from '@dxos/util';
 
 import * as Node from './node';
-import { Separators, normalizeRelation, shallowEqual } from './util';
+import { normalizeRelation, primaryKey, primaryParts, secondaryKey, secondaryParts, shallowEqual } from './util';
 
 const graphSymbol = Symbol('graph');
 
@@ -183,7 +183,10 @@ class GraphImpl implements WritableGraph {
   // TODO(wittjosiah): Atom feature request, support for something akin to `ComplexMap` to allow for complex arguments.
   readonly _connections = Atom.family<string, Atom.Atom<Node.Node[]>>((key) => {
     return Atom.make((get) => {
-      if (!key || key.indexOf(Separators.primary) <= 0) {
+      const parts = key ? primaryParts(key) : [];
+      // Empty id (e.g. from `useConnections(graph, undefined, ...)`) yields a key like `\u0001child\u0002outbound`,
+      // which has 2 parts but an empty id — treat as no connections rather than throwing.
+      if (parts.length < 2 || !parts[0]) {
         return [];
       }
       const { id, relation } = relationFromConnectionKey(key);
@@ -706,7 +709,7 @@ const expandImpl = <T extends ExpandableGraph | WritableGraph>(
 ): T => {
   const internal = getInternal(graph);
   const normalizedRelation = normalizeRelation(relation);
-  const key = `${id}${Separators.primary}${relationKey(normalizedRelation)}`;
+  const key = primaryKey(id, relationKey(normalizedRelation));
   const nodeOpt = internal._registry.get(internal._node(id));
   if (Option.isNone(nodeOpt)) {
     // Node not yet in graph: record expand to run when the node is added.
@@ -900,11 +903,10 @@ const addNodeImpl = <T extends WritableGraph>(graph: T, nodeArg: Node.NodeArg<an
       graph.onNodeChanged.emit({ id, node: newNode });
 
       // Apply any expands that were deferred because this node did not exist yet.
-      const prefix = `${id}${Separators.primary}`;
-      const toApply = [...internal._pendingExpands].filter((k) => k.startsWith(prefix));
+      const toApply = [...internal._pendingExpands].filter((k) => primaryParts(k)[0] === id);
       for (const pendingKey of toApply) {
         internal._pendingExpands.delete(pendingKey);
-        const relation = relationFromKey(pendingKey.slice(prefix.length));
+        const relation = relationFromKey(primaryParts(pendingKey)[1]);
         Record.set(internal._expanded, pendingKey, true);
         internal._onExpand?.(id, relation);
       }
@@ -1226,26 +1228,22 @@ export const make = (params?: GraphProps): Graph => {
 
 export const relationKey = (relation: Node.RelationInput): string => {
   const normalized = normalizeRelation(relation);
-  return `${normalized.kind}${Separators.secondary}${normalized.direction}`;
+  return secondaryKey(normalized.kind, normalized.direction);
 };
 
 export const relationFromKey = (encoded: string): Node.Relation => {
-  const separatorIndex = encoded.lastIndexOf(Separators.secondary);
-  invariant(separatorIndex > 0 && separatorIndex < encoded.length - 1, `Invalid relation key: ${encoded}`);
-  const kind = encoded.slice(0, separatorIndex);
-  const directionRaw = encoded.slice(separatorIndex + 1);
+  const parts = secondaryParts(encoded);
+  invariant(parts.length === 2 && parts[0].length > 0 && parts[1].length > 0, `Invalid relation key: ${encoded}`);
+  const [kind, directionRaw] = parts;
   invariant(directionRaw === 'outbound' || directionRaw === 'inbound', `Invalid relation direction: ${directionRaw}`);
   return Node.relation(kind, directionRaw);
 };
 
-const connectionKey = (id: string, relation: Node.RelationInput): string =>
-  `${id}${Separators.primary}${relationKey(relation)}`;
+const connectionKey = (id: string, relation: Node.RelationInput): string => primaryKey(id, relationKey(relation));
 
 const relationFromConnectionKey = (key: string): { id: string; relation: Node.Relation } => {
-  const separatorIndex = key.indexOf(Separators.primary);
-  invariant(separatorIndex > 0 && separatorIndex < key.length - 1, `Invalid connection key: ${key}`);
-  const id = key.slice(0, separatorIndex);
-  const encodedRelation = key.slice(separatorIndex + 1);
+  const [id, encodedRelation] = primaryParts(key);
+  invariant(id && encodedRelation, `Invalid connection key: ${key}`);
   return { id, relation: relationFromKey(encodedRelation) };
 };
 

package/src/index.ts

@@ -8,6 +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';
 
 // TODO(wittjosiah): Direct re-export needed for portable type references.
 export type { BuilderExtensions } from './graph-builder';

package/src/node-matcher.ts

@@ -106,7 +106,10 @@ export const whenNodeType =
  * });
  * ```
  *
- * @see {@link whenEchoTypeMatches} - Use instead when composing with whenAll/whenAny.
+ * Can be composed directly with {@link whenAll}/{@link whenAny}/{@link whenNot} while
+ * preserving the typed entity data in the result.
+ *
+ * @see {@link whenEchoTypeMatches} - Returns the node instead of data for legacy composition.
  */
 export const whenEchoType =
   <T extends Type.AnyEntity>(type: T): NodeMatcher<Entity.Entity<Schema.Schema.Type<T>>> =>
@@ -124,7 +127,7 @@ export const whenEchoType =
  * @example
  * ```ts
  * GraphBuilder.createExtension({
- *   id: 'object-settings',
+ *   id: 'object-properties',
  *   match: NodeMatcher.whenEchoObject,
  *   connector: (object) => {
  *     // `object` is typed as Obj.Unknown
@@ -134,7 +137,10 @@ export const whenEchoType =
  * });
  * ```
  *
- * @see {@link whenEchoObjectMatches} - Use instead when composing with whenAll/whenAny.
+ * Can be composed directly with {@link whenAll}/{@link whenAny}/{@link whenNot} while
+ * preserving the `Obj.Unknown` data type in the result.
+ *
+ * @see {@link whenEchoObjectMatches} - Returns the node instead of data for legacy composition.
  */
 export const whenEchoObject = (node: Node.Node): Option.Option<Obj.Unknown> =>
   Obj.isObject(node.data) ? Option.some(node.data) : Option.none();
@@ -145,53 +151,75 @@ export const whenEchoObject = (node: Node.Node): Option.Option<Obj.Unknown> =>
 
 /**
  * Composes multiple matchers with AND logic - all matchers must match for success.
- * Returns the **node** (not the matched data) to enable further composition.
+ * The result data type is the intersection of all matchers' data types.
+ * Filter matchers like {@link whenNot} return `unknown`, making them transparent
+ * in the intersection (since `T & unknown = T`).
  *
  * @param matchers - The matchers to combine. All must return Option.some for success.
- * @returns A matcher that returns Option.some(node) if all match, Option.none() otherwise.
+ * @returns A matcher whose data type is the intersection of all input matchers' data types.
+ *   Returns the first matcher's value when all match, Option.none() otherwise.
  *
  * @example
  * ```ts
- * // Match ECHO objects that are NOT Channels
+ * // Match ECHO objects that are NOT Channels — result is NodeMatcher<Obj.Unknown>.
  * const whenCommentable = NodeMatcher.whenAll(
- *   NodeMatcher.whenEchoObjectMatches,
+ *   NodeMatcher.whenEchoObject,
  *   NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(Channel.Channel)),
  * );
  * ```
  */
-export const whenAll =
-  (...matchers: NodeMatcher[]): NodeMatcher =>
-  (node: Node.Node): Option.Option<Node.Node> => {
+export const whenAll: {
+  <A>(a: NodeMatcher<A>, b: NodeMatcher<unknown>): NodeMatcher<A>;
+  <A>(a: NodeMatcher<unknown>, b: NodeMatcher<A>): NodeMatcher<A>;
+  <A, B>(a: NodeMatcher<A>, b: NodeMatcher<B>): NodeMatcher<A & B>;
+  <A, B, C>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>): NodeMatcher<A & B & C>;
+  <A, B, C, D>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>, d: NodeMatcher<D>): NodeMatcher<A & B & C & D>;
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any>;
+} =
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any> =>
+  (node: Node.Node) => {
+    let first: Option.Option<any> = Option.none();
     for (const candidate of matchers) {
-      if (Option.isNone(candidate(node))) {
+      const result = candidate(node);
+      if (Option.isNone(result)) {
         return Option.none();
       }
+      if (Option.isNone(first)) {
+        first = result;
+      }
     }
-    return Option.some(node);
+    return first;
   };
 
 /**
  * Composes multiple matchers with OR logic - at least one matcher must match.
- * Returns the **node** (not the matched data) to enable further composition.
+ * The result data type is the union of all matchers' data types.
  *
  * @param matchers - The matchers to combine. At least one must return Option.some.
- * @returns A matcher that returns Option.some(node) if any match, Option.none() otherwise.
+ * @returns A matcher whose data type is the union of all input matchers' data types.
+ *   Returns the first matching matcher's value, or Option.none() if none match.
  *
  * @example
  * ```ts
- * // Match nodes that are either Sequences or Prompts
+ * // Match nodes that are either Sequences or Routines
  * const whenInvocable = NodeMatcher.whenAny(
  *   NodeMatcher.whenEchoTypeMatches(Sequence),
- *   NodeMatcher.whenEchoTypeMatches(Prompt.Prompt),
+ *   NodeMatcher.whenEchoTypeMatches(Routine.Routine),
  * );
  * ```
  */
-export const whenAny =
-  (...matchers: NodeMatcher[]): NodeMatcher =>
-  (node: Node.Node): Option.Option<Node.Node> => {
+export const whenAny: {
+  <A, B>(a: NodeMatcher<A>, b: NodeMatcher<B>): NodeMatcher<A | B>;
+  <A, B, C>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>): NodeMatcher<A | B | C>;
+  <A, B, C, D>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>, d: NodeMatcher<D>): NodeMatcher<A | B | C | D>;
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any>;
+} =
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any> =>
+  (node: Node.Node) => {
     for (const candidate of matchers) {
-      if (Option.isSome(candidate(node))) {
-        return Option.some(node);
+      const result = candidate(node);
+      if (Option.isSome(result)) {
+        return result;
       }
     }
     return Option.none();
@@ -260,15 +288,19 @@ export const whenEchoObjectMatches = (node: Node.Node): Option.Option<Node.Node>
  * Negates a matcher - matches when the given matcher does NOT match.
  * Useful for exclusion patterns like "any object EXCEPT type X".
  *
+ * Returns `NodeMatcher<unknown>` because negation is a filter — it doesn't provide
+ * typed data. This makes it transparent in {@link whenAll} intersections
+ * (since `T & unknown = T`).
+ *
  * @param matcher - The matcher to negate.
  * @returns A matcher that returns Option.some(node) if the input matcher returns none,
  *   and Option.none() if the input matcher returns some.
  *
  * @example
  * ```ts
- * // Match any ECHO object that is NOT a Channel
+ * // Match any ECHO object that is NOT a Channel — result is NodeMatcher<Obj.Unknown>.
  * const whenCommentable = NodeMatcher.whenAll(
- *   NodeMatcher.whenEchoObjectMatches,
+ *   NodeMatcher.whenEchoObject,
  *   NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(Channel.Channel)),
  * );
  *
@@ -277,6 +309,6 @@ export const whenEchoObjectMatches = (node: Node.Node): Option.Option<Node.Node>
  * ```
  */
 export const whenNot =
-  (matcher: NodeMatcher): NodeMatcher =>
-  (node: Node.Node): Option.Option<Node.Node> =>
+  (matcher: NodeMatcher<any>): NodeMatcher<unknown> =>
+  (node: Node.Node): Option.Option<unknown> =>
     Option.isNone(matcher(node)) ? Option.some(node) : Option.none();

package/src/node.ts

@@ -15,17 +15,17 @@ export const RootId = 'root';
 /**
  * Root node type.
  */
-export const RootType = 'org.dxos.type.graph-root';
+export const RootType = 'org.dxos.type.graphRoot';
 
 /**
  * Action node type.
  */
-export const ActionType = 'org.dxos.type.graph-action';
+export const ActionType = 'org.dxos.type.graphAction';
 
 /**
  * Action group node type.
  */
-export const ActionGroupType = 'org.dxos.type.graph-action-group';
+export const ActionGroupType = 'org.dxos.type.graphActionGroup';
 
 /**
  * Represents a node in the graph.
@@ -150,3 +150,29 @@ export const isActionGroup = (data: unknown): data is ActionGroup =>
 export type ActionLike = Action | ActionGroup;
 
 export const isActionLike = (data: unknown): data is Action | ActionGroup => isAction(data) || isActionGroup(data);
+
+//
+// Node Factories
+//
+
+/** Typed factory for constructing a NodeArg. Provides auto-complete and type validation. */
+export const make = <TData = any, TProperties extends Record<string, any> = Record<string, any>>(
+  arg: NodeArg<TData, TProperties>,
+): NodeArg<TData, TProperties> => arg;
+
+/** Create an action node. Automatically sets `type: ActionType`. */
+export const makeAction = <R = never>(
+  arg: Omit<NodeArg<ActionData<R>>, 'type' | 'nodes' | 'edges'>,
+): NodeArg<ActionData<R>> => ({
+  ...arg,
+  type: ActionType,
+});
+
+/** Create an action group node. Automatically sets `type` and `data`. */
+export const makeActionGroup = (
+  arg: Omit<NodeArg<typeof actionGroupSymbol>, 'type' | 'data' | 'nodes' | 'edges'>,
+): NodeArg<typeof actionGroupSymbol> => ({
+  ...arg,
+  type: ActionGroupType,
+  data: actionGroupSymbol,
+});

package/src/scheduler.browser.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { scheduleTask, yieldOrContinue } from 'main-thread-scheduling';

package/src/scheduler.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// CF Workers / Node fallback: there is no main thread to yield to.
+// scheduleTask runs the callback on the next microtask; yieldOrContinue is a microtask hop.
+
+type ScheduleOptions = { strategy?: 'smooth' | 'interactive' | 'idle'; signal?: AbortSignal };
+
+export const scheduleTask = async <T>(callback: () => T | Promise<T>, _options?: ScheduleOptions): Promise<T> => {
+  await Promise.resolve();
+  return callback();
+};
+
+export const yieldOrContinue = async (_priority: 'smooth' | 'interactive' | 'idle'): Promise<void> => {
+  await Promise.resolve();
+};

package/src/stories/EchoGraph.stories.tsx

@@ -8,16 +8,16 @@ import * as Function from 'effect/Function';
 import * as Option from 'effect/Option';
 import React, { type PropsWithChildren, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
-import { Filter, type Space, SpaceState, isSpace } from '@dxos/client/echo';
-import { Obj, Query } from '@dxos/echo';
-import { TestSchema } from '@dxos/echo/testing';
+import { type Space, SpaceState, isSpace } from '@dxos/client/echo';
+import { Filter, Obj, Query } from '@dxos/echo';
 import { AtomObj, AtomQuery } from '@dxos/echo-atom';
-import { faker } from '@dxos/random';
+import { TestSchema } from '@dxos/echo/testing';
+import { random } from '@dxos/random';
 import { type Client, useClient } from '@dxos/react-client';
 import { withClientProvider } from '@dxos/react-client/testing';
 import { Icon, IconButton, Input, Select } from '@dxos/react-ui';
-import { withTheme } from '@dxos/react-ui/testing';
 import { Path, Tree, type TreeModel } from '@dxos/react-ui-list';
+import { withTheme } from '@dxos/react-ui/testing';
 import { getSize, mx } from '@dxos/ui-theme';
 import { safeParseInt } from '@dxos/util';
 
@@ -25,7 +25,6 @@ import * as CreateAtom from '../atoms';
 import * as Graph from '../graph';
 import * as GraphBuilder from '../graph-builder';
 import * as Node from '../node';
-
 import { JsonTree } from './Tree';
 
 const DEFAULT_PERIOD = 500;
@@ -146,8 +145,8 @@ const runAction = async (client: Client, action: Action) => {
     case Action.RENAME_SPACE: {
       const space = getRandomSpace(client);
       if (space) {
-        Obj.change(space.properties, (p) => {
-          p.name = faker.commerce.productName();
+        Obj.update(space.properties, (obj) => {
+          obj.name = random.commerce.productName();
         });
       }
       break;
@@ -157,7 +156,7 @@ const runAction = async (client: Client, action: Action) => {
       getRandomSpace(client)?.db.add(
         Obj.make(TestSchema.Expando, {
           type: 'test',
-          name: faker.commerce.productName(),
+          name: random.commerce.productName(),
         }),
       );
       break;
@@ -176,8 +175,8 @@ const runAction = async (client: Client, action: Action) => {
       if (space) {
         const objects = await space.db.query(Filter.type(TestSchema.Expando, { type: 'test' })).run();
         const object = objects[Math.floor(Math.random() * objects.length)];
-        Obj.change(object, (o) => {
-          o.name = faker.commerce.productName();
+        Obj.update(object, (object) => {
+          object.name = random.commerce.productName();
         });
       }
       break;
@@ -216,7 +215,6 @@ const Controls = ({ children }: PropsWithChildren) => {
           <Input.Root>
             <Input.TextInput
               autoComplete='off'
-              size={5}
               classNames='w-[100px] text-right pe-[22px]'
               placeholder='Interval'
               value={actionInterval}

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './setup-graph-builder';

package/src/testing/setup-graph-builder.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom-react';
+import * as Option from 'effect/Option';
+
+import * as Graph from '../graph';
+import * as GraphBuilder from '../graph-builder';
+import * as Node from '../node';
+
+export type SetupGraphBuilderOptions = {
+  registry?: Registry.Registry;
+  extensions?: GraphBuilder.BuilderExtensions;
+};
+
+export const setupGraphBuilder = ({ registry = Registry.make(), extensions }: SetupGraphBuilderOptions = {}) => {
+  const builder = GraphBuilder.make({ registry });
+  const graph = builder.graph;
+
+  if (extensions) {
+    GraphBuilder.addExtension(builder, extensions);
+  }
+
+  return {
+    registry,
+    builder,
+    graph,
+    addExtensions: (nextExtensions: GraphBuilder.BuilderExtensions) => {
+      GraphBuilder.addExtension(builder, nextExtensions);
+    },
+    expand: async (id: string, relation: Node.RelationInput = 'child') => {
+      Graph.expand(graph, id, relation);
+      await GraphBuilder.flush(builder);
+    },
+    flush: () => GraphBuilder.flush(builder),
+    getConnections: (id: string, relation: Node.RelationInput = 'child') =>
+      registry.get(graph.connections(id, relation)),
+    getNode: (id: string) => Graph.getNode(graph, id).pipe(Option.getOrNull),
+  };
+};