@dxos/plugin-graph 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-graph",
-  "version": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
+  "version": "0.14.0",
   "description": "DXOS Surface plugin for constructing knowledge graphs",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,7 +10,7 @@
   },
   "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "imports": {
     "#hooks": {
@@ -35,20 +35,25 @@
       "types": "./dist/types/src/index.d.ts",
       "import": "./dist/lib/index.mjs"
     },
-    "./hooks": {
-      "source": "./src/hooks/index.ts",
-      "types": "./dist/types/src/hooks/index.d.ts",
-      "import": "./dist/lib/hooks.mjs"
-    },
-    "./testing": {
-      "source": "./src/testing.ts",
-      "types": "./dist/types/src/testing.d.ts",
-      "import": "./dist/lib/testing.mjs"
+    "./GraphAction": {
+      "source": "./src/GraphAction.ts",
+      "types": "./dist/types/src/GraphAction.d.ts",
+      "import": "./dist/lib/ns/GraphAction.mjs"
     },
     "./GraphPlugin": {
       "source": "./src/GraphPlugin.ts",
       "types": "./dist/types/src/GraphPlugin.d.ts",
       "import": "./dist/lib/GraphPlugin.mjs"
+    },
+    "./Hooks": {
+      "source": "./src/Hooks.ts",
+      "types": "./dist/types/src/Hooks.d.ts",
+      "import": "./dist/lib/ns/Hooks.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing.ts",
+      "types": "./dist/types/src/testing.d.ts",
+      "import": "./dist/lib/testing.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -58,26 +63,28 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/app-framework": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/app-graph": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/app-toolkit": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/compute": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/effect": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/graph": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/util": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264"
+    "@dxos/app-framework": "0.14.0",
+    "@dxos/app-graph": "0.14.0",
+    "@dxos/app-toolkit": "0.14.0",
+    "@dxos/compute": "0.14.0",
+    "@dxos/effect": "0.14.0",
+    "@dxos/graph": "0.14.0",
+    "@dxos/react-ui-list": "0.14.0",
+    "@dxos/ui-theme": "0.14.0",
+    "@dxos/util": "0.14.0"
   },
   "devDependencies": {
-    "@effect/atom-react": "4.0.0-rc.108",
+    "@effect/atom-react": "4.0.0",
     "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "effect": "4.0.0-rc.108",
+    "effect": "4.0.0",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "vite": "^8.2.1"
+    "vite": "^8.2.2"
   },
   "peerDependencies": {
-    "@effect/atom-react": "4.0.0-rc.108",
-    "effect": "4.0.0-rc.108",
+    "@effect/atom-react": "4.0.0",
+    "effect": "4.0.0",
     "react": "~19.2.7",
     "react-dom": "~19.2.7"
   },

package/src/GraphAction.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+export { runAction as run } from './action.ts';

package/src/Hooks.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+export * from '#hooks';

package/src/action.ts

@@ -9,7 +9,7 @@ import * as Capability from '@dxos/app-framework/Capability';
 import type * as CapabilityManager from '@dxos/app-framework/CapabilityManager';
 import type * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
 import * as Operation from '@dxos/compute/Operation';
-import { EffectEx } from '@dxos/effect';
+import * as EffectEx from '@dxos/effect/EffectEx';
 
 /**
  * Run an action with required layers: Operation.Service, Capability.Service, and captured context.

package/src/graph.ts

@@ -10,11 +10,12 @@ import * as Capability from '@dxos/app-framework/Capability';
 import * as AppGraph from '@dxos/app-graph/AppGraph';
 import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
 import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as AppNode from '@dxos/app-toolkit/AppNode';
 import * as UrlPath from '@dxos/app-toolkit/UrlPath';
 import * as GraphNode from '@dxos/graph/GraphNode';
 
 // TODO(wittjosiah): Remove or restore graph caching.
-// import { meta } from './meta';
+// import { meta } from './meta.ts';
 
 // const KEY = `${meta.id}.app-graph`;
 
@@ -30,7 +31,8 @@ export default Capability.makeModule(
     // produces their nodes (see `AppGraphBuilder.UrlGrammar`).
     const builder = AppGraphBuilder.from(/* localStorage.getItem(KEY) ?? */ undefined, registry, {
       anchorKey: UrlPath.WORKSPACE_KEY,
-      linkedKey: UrlPath.COMPANION_KEY,
+      linked: { key: UrlPath.COMPANION_KEY, relation: AppNode.companion },
+      tailSeparator: UrlPath.TAIL_SEPARATOR,
     });
     // const interval = setInterval(() => {
     //   localStorage.setItem(KEY, builder.graph.pickle());
@@ -56,6 +58,13 @@ export default Capability.makeModule(
       { immediate: true },
     );
 
+    const retentionAtom = yield* Capability.atom(AppCapabilities.AppGraphRetention);
+    const unsubscribeRetention = registry.subscribe(
+      retentionAtom,
+      (retentions) => AppGraphBuilder.setRetention(builder, retentions),
+      { immediate: true },
+    );
+
     // await builder.initialize();
     void AppGraph.expandSync(builder.graph, GraphNode.RootId, 'child');
 
@@ -65,6 +74,9 @@ export default Capability.makeModule(
       Effect.sync(() => {
         // clearInterval(interval);
         unsubscribe();
+        unsubscribeRetention();
+        AppGraphBuilder.setRetention(builder, []);
+        AppGraphBuilder.destroy(builder);
       }),
     );
     return Capability.contribute(AppCapabilities.AppGraph, builder);

package/src/hooks/graph-tree-model.test.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Atom from 'effect/reactivity/Atom';
+import { describe, test } from 'vitest';
+
+import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
+import { setupGraphBuilder } from '@dxos/app-graph/testing';
+import * as EffectEx from '@dxos/effect/EffectEx';
+import * as GraphNode from '@dxos/graph/GraphNode';
+import * as GraphNodeMatcher from '@dxos/graph/GraphNodeMatcher';
+import { Path } from '@dxos/react-ui-list';
+
+import { createGraphTreeModel } from './useGraphTreeModel.ts';
+
+describe('createGraphTreeModel', () => {
+  const setup = async () => {
+    const extensions = await EffectEx.runPromise(
+      AppGraphBuilder.createExtension({
+        id: 'test',
+        match: GraphNodeMatcher.whenRoot,
+        connector: () =>
+          Effect.succeed([
+            { id: 'a', type: 'page', data: 'a', properties: { label: 'A' } },
+            { id: 'hidden', type: 'page', data: 'h', properties: { label: 'H', disposition: 'hidden' } },
+            {
+              id: 'group',
+              type: 'group',
+              data: null,
+              properties: { label: 'G', disposition: 'group' },
+              nodes: [{ id: 'b', type: 'page', data: 'b', properties: { label: 'B' } }],
+            },
+          ]),
+      }),
+    );
+    const context = setupGraphBuilder({ extensions });
+    await context.expand(GraphNode.RootId);
+    await context.expand(`${GraphNode.RootId}/group`);
+    const openPaths = new Set<string>();
+    const openAtom = Atom.make(openPaths);
+    const model = createGraphTreeModel(context.graph, GraphNode.RootId, {
+      itemOpen: (path) => Atom.make((get) => get(openAtom).has(Path.create(...path))),
+      itemCurrent: (path) => Atom.make(() => Path.last(Path.create(...path)) === `${GraphNode.RootId}/b`),
+    });
+    return { ...context, model };
+  };
+
+  test('lists visible children of the root, dropping hidden nodes', async ({ expect }) => {
+    const { registry, model } = await setup();
+    expect(registry.get(model.childIds())).toEqual([`${GraphNode.RootId}/a`, `${GraphNode.RootId}/group`]);
+  });
+
+  test('maps node properties to row props; groups are disabled, undraggable, not branches', async ({ expect }) => {
+    const { registry, model } = await setup();
+    const group = registry.get(model.itemProps([GraphNode.RootId, `${GraphNode.RootId}/group`]));
+    expect(group.disposition).toBe('group');
+    expect(group.disabled).toBe(true);
+    expect(group.draggable).toBe(false);
+    expect(group.parentOf).toBeUndefined();
+    const page = registry.get(model.itemProps([GraphNode.RootId, `${GraphNode.RootId}/a`]));
+    expect(page.label).toBe('A');
+  });
+
+  test('current comes from the caller', async ({ expect }) => {
+    const { registry, model } = await setup();
+    expect(
+      registry.get(model.itemCurrent([GraphNode.RootId, `${GraphNode.RootId}/group`, `${GraphNode.RootId}/b`])),
+    ).toBe(true);
+    expect(registry.get(model.itemCurrent([GraphNode.RootId, `${GraphNode.RootId}/a`]))).toBe(false);
+  });
+});

package/src/hooks/index.ts

@@ -5,5 +5,6 @@
 // TODO(wittjosiah): Hooks should not be exported from the plugin package at all.
 //   Either refactor callers to not need them or factor them out to a shared package.
 
-export * from './useActionRunner';
-export * from './useNode';
+export * from './useActionRunner.ts';
+export * from './useGraphTreeModel.ts';
+export * from './useNode.ts';

package/src/hooks/useActionRunner.ts

@@ -4,18 +4,19 @@
 
 import { useCallback } from 'react';
 
-import { useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
+import * as Hooks from '@dxos/app-framework/Hooks';
+import * as PluginManagerProvider from '@dxos/app-framework/PluginManagerProvider';
 import type * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
 
-import { runAction } from '../action';
+import { runAction } from '../action.ts';
 
 /**
  * Hook that returns a function to run action Effects.
  * Provides Operation.Service, PluginContextService, and captured plugin context.
  */
 export const useActionRunner = () => {
-  const invoker = useOperationInvoker();
-  const pluginManager = usePluginManager();
+  const invoker = Hooks.useOperationInvoker();
+  const pluginManager = PluginManagerProvider.usePluginManager();
 
   return useCallback(
     (action: AppGraphNode.Action, params: AppGraphNode.InvokeProps = {}) =>

package/src/hooks/useGraphTreeModel.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as Atom from 'effect/reactivity/Atom';
+import { useMemo } from 'react';
+
+import type * as AppGraph from '@dxos/app-graph/AppGraph';
+import * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
+import * as Hooks from '@dxos/app-toolkit/Hooks';
+import { Path, type TreeModel } from '@dxos/react-ui-list';
+import { mx } from '@dxos/ui-theme';
+
+export type GraphTreeState = {
+  /** Open state keyed by the joined path (`Path.create`). */
+  itemOpen: (path: string[]) => Atom.Atom<boolean>;
+  /** Selected state keyed by the joined path. */
+  itemCurrent: (path: string[]) => Atom.Atom<boolean>;
+};
+
+/** Rows the tree lists: not hidden, and either a plain node or an action the graph marks as an item. */
+const isItem = (node: AppGraphNode.Node): boolean =>
+  !AppGraphNode.hasDisposition(node, 'hidden') &&
+  (!AppGraphNode.isAction(node) || AppGraphNode.hasDisposition(node, 'item'));
+
+/**
+ * A `TreeModel` over the app graph: topology and row props come from the graph, open/current state
+ * from the caller, so one mapping serves the navtree (persisted state) and any other tree host.
+ */
+export const createGraphTreeModel = (
+  graph: AppGraph.ReadableGraph,
+  rootId: string,
+  { itemOpen, itemCurrent }: GraphTreeState,
+): TreeModel<AppGraphNode.Node> => {
+  const isVisibleChild = (node: AppGraphNode.Node) => !AppGraphNode.hasDisposition(node, 'hidden');
+
+  const itemPropsFamily = Atom.family((pathKey: string) => {
+    const path = Path.parts(pathKey);
+    const id = Path.last(pathKey);
+    return Atom.make((get) => {
+      const node = Option.getOrUndefined(get(graph.node(id)));
+      if (!node) {
+        return { id, label: id };
+      }
+      const safeChildren = get(graph.connections(node.id, 'child')).filter((child) => !path.includes(child.id));
+      const visibleChildren = safeChildren.filter(isVisibleChild);
+      const parentOf =
+        visibleChildren.length > 0
+          ? visibleChildren.map((child) => child.id)
+          : node.properties.role === 'branch'
+            ? []
+            : undefined;
+      const parentId = path.length >= 2 ? path[path.length - 2] : undefined;
+      const parentNode = parentId ? Option.getOrUndefined(get(graph.node(parentId))) : undefined;
+      const droppable =
+        node.properties.droppable === false || parentNode?.properties.childrenDroppable === false ? false : undefined;
+      const disposition = node.properties.disposition as string | undefined;
+      const isGroup = disposition === 'group';
+      return {
+        id: node.id,
+        parentOf: isGroup ? undefined : parentOf,
+        disposition,
+        disabled: isGroup || node.properties.disabled,
+        draggable: isGroup ? false : node.properties.draggable,
+        droppable: isGroup ? false : droppable,
+        label: node.properties.label ?? node.id,
+        className: mx(node.properties.className, node.properties.modified && 'italic'),
+        headingClassName: node.properties.headingClassName,
+        icon: node.properties.icon,
+        iconHue: node.properties.iconHue,
+        testId: node.properties.testId,
+        count: node.properties.count,
+        modifiedCount: node.properties.modifiedCount,
+      };
+    }).pipe(Atom.keepAlive);
+  });
+
+  const childIdsFamily = Atom.family((id: string) =>
+    Atom.make((get) =>
+      get(graph.connections(id, 'child'))
+        .filter(isVisibleChild)
+        .map((child) => child.id),
+    ).pipe(Atom.keepAlive),
+  );
+
+  const itemFamily = Atom.family((id: string) =>
+    Atom.make((get) => {
+      const node = Option.getOrUndefined(get(graph.node(id)));
+      return node && isItem(node) ? node : undefined;
+    }).pipe(Atom.keepAlive),
+  );
+
+  const itemOpenFamily = Atom.family((pathKey: string) => itemOpen(Path.parts(pathKey)));
+  const itemCurrentFamily = Atom.family((pathKey: string) => itemCurrent(Path.parts(pathKey)));
+
+  return {
+    item: (id) => itemFamily(id),
+    itemProps: (path) => itemPropsFamily(Path.create(...path)),
+    itemOpen: (path) => itemOpenFamily(Path.create(...path)),
+    itemCurrent: (path) => itemCurrentFamily(Path.create(...path)),
+    childIds: (parentId) => childIdsFamily(parentId ?? rootId),
+  };
+};
+
+/** {@link createGraphTreeModel} over the app graph capability, memoised on its inputs. */
+export const useGraphTreeModel = (rootId: string, options: GraphTreeState): TreeModel<AppGraphNode.Node> => {
+  const { graph } = Hooks.useAppGraph();
+  const { itemOpen, itemCurrent } = options;
+  return useMemo(
+    () => createGraphTreeModel(graph, rootId, { itemOpen, itemCurrent }),
+    [graph, rootId, itemOpen, itemCurrent],
+  );
+};

package/src/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * as GraphPlugin from './GraphPlugin';
-export * from './action';
-export * from '#meta';
+export * as GraphAction from './GraphAction.ts';
+export * as GraphPlugin from './GraphPlugin.ts';
+export * as Hooks from './Hooks.ts';

package/src/meta.ts

@@ -4,6 +4,6 @@
 
 import * as Plugin from '@dxos/app-framework/Plugin';
 
-import config from '../dx.config';
+import config from '../dx.config.ts';
 
 export const meta = Plugin.getMetaFromConfig(config);

package/src/plugin.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, test } from 'vitest';
 
-import { ProcessManagerPlugin } from '@dxos/app-framework';
+import * as ProcessManagerPlugin from '@dxos/app-framework/ProcessManagerPlugin';
 import { createTestApp } from '@dxos/app-framework/testing';
 
 import { meta } from '#meta';
@@ -16,7 +16,7 @@ describe('GraphPlugin', () => {
   test('modules activate on the expected events', async ({ expect }) => {
     // Use createTestApp directly — createComposerTestApp already includes GraphPlugin.
     await using harness = await createTestApp({
-      plugins: [GraphPlugin(), ProcessManagerPlugin()],
+      plugins: [GraphPlugin(), ProcessManagerPlugin.make()],
     });
 
     // Graph activates on Startup; fires SetupAppGraph + SetupMetadata before, AppGraphReady after.

package/src/plugin.ts

@@ -12,7 +12,7 @@ import { meta } from '#meta';
 const Graph = Capability.lazyModule(
   'Graph',
   { requires: [Capabilities.AtomRegistry], provides: [AppCapabilities.AppGraph] },
-  () => import('./graph'),
+  () => import('./graph.ts'),
 );
 
 /**

package/src/testing.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * as GraphPlugin from './GraphPlugin.testing';
+export * as GraphPlugin from './GraphPlugin.testing.ts';