@dxos/plugin-explorer 0.9.1-main.c7dcc2e112 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-explorer",
-  "version": "0.9.1-main.c7dcc2e112",
+  "version": "0.10.0",
   "description": "Braneframe data visualization plugin",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -97,57 +97,61 @@
   "dependencies": {
     "@effect-atom/atom-react": "^0.5.0",
     "@observablehq/plot": "^0.6.11",
+    "@radix-ui/react-context": "1.1.1",
+    "@radix-ui/react-slot": "1.1.2",
     "d3": "^7.9.0",
-    "effect": "3.21.3",
+    "effect": "3.21.4",
     "force-graph": "^1.49.4",
     "react-resize-detector": "^11.0.1",
     "topojson-client": "^3.1.0",
-    "@dxos/app-toolkit": "0.9.1-main.c7dcc2e112",
-    "@dxos/client": "0.9.1-main.c7dcc2e112",
-    "@dxos/app-framework": "0.9.1-main.c7dcc2e112",
-    "@dxos/compute": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo-query": "0.9.1-main.c7dcc2e112",
-    "@dxos/graph": "0.9.1-main.c7dcc2e112",
-    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
-    "@dxos/keys": "0.9.1-main.c7dcc2e112",
-    "@dxos/log": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-space": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-client": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-graph": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-components": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-mosaic": "0.9.1-main.c7dcc2e112",
-    "@dxos/types": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-stack": "0.9.1-main.c7dcc2e112",
-    "@dxos/schema": "0.9.1-main.c7dcc2e112",
-    "@dxos/util": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-client": "0.9.1-main.c7dcc2e112"
+    "@dxos/app-toolkit": "0.10.0",
+    "@dxos/compute": "0.10.0",
+    "@dxos/echo": "0.10.0",
+    "@dxos/echo-query": "0.10.0",
+    "@dxos/graph": "0.10.0",
+    "@dxos/invariant": "0.10.0",
+    "@dxos/keys": "0.10.0",
+    "@dxos/app-framework": "0.10.0",
+    "@dxos/log": "0.10.0",
+    "@dxos/plugin-client": "0.10.0",
+    "@dxos/plugin-graph": "0.10.0",
+    "@dxos/plugin-space": "0.10.0",
+    "@dxos/react-client": "0.10.0",
+    "@dxos/react-ui-attention": "0.10.0",
+    "@dxos/react-ui-graph": "0.10.0",
+    "@dxos/react-ui-components": "0.10.0",
+    "@dxos/react-ui-mosaic": "0.10.0",
+    "@dxos/types": "0.10.0",
+    "@dxos/ui-types": "0.10.0",
+    "@dxos/schema": "0.10.0",
+    "@dxos/client": "0.10.0",
+    "@dxos/util": "0.10.0"
   },
   "devDependencies": {
     "@types/d3": "^7.4.3",
     "@types/d3-hierarchy": "^3.1.6",
     "@types/lodash.defaultsdeep": "^4.6.6",
-    "@types/react": "~19.2.7",
+    "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
     "@types/topojson-client": "^3.1.4",
     "@types/topojson-specification": "^1.0.5",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
     "vite": "^8.0.16",
-    "@dxos/echo-generator": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-preview": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-testing": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/random": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
-    "@dxos/storybook-utils": "0.9.1-main.c7dcc2e112"
+    "@dxos/echo-generator": "0.10.0",
+    "@dxos/plugin-preview": "0.10.0",
+    "@dxos/plugin-testing": "0.10.0",
+    "@dxos/random": "0.10.0",
+    "@dxos/react-ui": "0.10.0",
+    "@dxos/ui-theme": "0.10.0",
+    "@dxos/storybook-utils": "0.10.0"
   },
   "peerDependencies": {
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112"
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "0.10.0",
+    "@dxos/ui-theme": "0.10.0"
   },
   "publishConfig": {
     "access": "public"

package/src/ExplorerPlugin.tsx

@@ -5,7 +5,7 @@
 import { Plugin } from '@dxos/app-framework';
 import { AppPlugin } from '@dxos/app-toolkit';
 
-import { CreateObject, ReactSurface } from '#capabilities';
+import { AppGraphBuilder, CreateObject, ReactSurface } from '#capabilities';
 import { meta } from '#meta';
 import { translations } from '#translations';
 import { Graph } from '#types';
@@ -15,6 +15,7 @@ import pluginSpec from '../PLUGIN.mdl?raw';
 
 export const ExplorerPlugin = Plugin.define(meta).pipe(
   AppPlugin.addCreateObjectModule({ activate: CreateObject }),
+  AppPlugin.addAppGraphModule({ activate: AppGraphBuilder }),
   AppPlugin.addSchemaModule({ schema: [Graph.Graph] }),
   AppPlugin.addSurfaceModule({ activate: ReactSurface }),
   AppPlugin.addTranslationsModule({ translations }),

package/src/capabilities/app-graph-builder.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities, AppNode } from '@dxos/app-toolkit';
+import { GraphBuilder, NodeMatcher } from '@dxos/plugin-graph';
+import { linkedSegment } from '@dxos/react-ui-attention';
+import { Position } from '@dxos/util';
+
+import { meta } from '#meta';
+
+/**
+ * Offers a "Neighborhood" companion on any ECHO object. The matched node is passed through as the
+ * companion's `companionTo` (the active node), which the surface renders as an ego-centric graph.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const extensions = yield* Effect.all([
+      GraphBuilder.createExtension({
+        id: 'neighborhoodCompanion',
+        match: NodeMatcher.whenEchoObjectMatches,
+        connector: () =>
+          Effect.succeed([
+            AppNode.makeCompanion({
+              id: linkedSegment('neighborhood'),
+              label: ['neighborhood-companion.label', { ns: meta.profile.key }],
+              icon: 'ph--share-network--regular',
+              data: 'neighborhood',
+              position: Position.last,
+            }),
+          ]),
+      }),
+    ]);
+
+    return Capability.contributes(AppCapabilities.AppGraphBuilder, extensions);
+  }),
+);

package/src/capabilities/create-object.ts

@@ -21,13 +21,14 @@ export default Capability.makeModule(
       createObject: (props, options) =>
         Effect.gen(function* () {
           const object = yield* Effect.promise(async () => {
-            const { view } = await ViewModel.makeFromDatabase({ db: options.db, typename: props.typename });
+            const view = props.typename
+              ? (await ViewModel.makeFromDatabase({ db: options.db, typename: props.typename })).view
+              : undefined;
             return Graph.make({ name: props.name, view });
           });
           return yield* Operation.invoke(SpaceOperation.AddObject, {
             object,
             target: options.target,
-            hidden: true,
             targetNodeId: options.targetNodeId,
           });
         }),

package/src/capabilities/index.ts

@@ -4,5 +4,6 @@
 
 import { Capability } from '@dxos/app-framework';
 
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));
 export const CreateObject = Capability.lazy('CreateObject', () => import('./create-object'));
 export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));

package/src/capabilities/react-surface.tsx

@@ -9,13 +9,12 @@ import { Capabilities, Capability } from '@dxos/app-framework';
 import { Surface } from '@dxos/app-framework/ui';
 import { AppSurface } from '@dxos/app-toolkit/ui';
 
-import { ExplorerArticle } from '#containers';
+import { ExplorerArticle, NeighborhoodCompanion } from '#containers';
 import { Graph } from '#types';
 
 export default Capability.makeModule(() =>
   Effect.succeed(
-    Capability.contributes(
-      Capabilities.ReactSurface,
+    Capability.contributes(Capabilities.ReactSurface, [
       Surface.create({
         id: 'article',
         // TODO(wittjosiah): Split into multiple surfaces if this filter proves too strict for non-article roles.
@@ -27,6 +26,17 @@ export default Capability.makeModule(() =>
           return <ExplorerArticle role={role} subject={data.subject} attendableId={data.attendableId} />;
         },
       }),
-    ),
+      // Neighborhood companion offered on any ECHO object; `companionTo` is the active node.
+      Surface.create({
+        id: 'neighborhood',
+        filter: AppSurface.allOf(
+          AppSurface.literal(AppSurface.Article, 'neighborhood'),
+          AppSurface.companion(AppSurface.Article),
+        ),
+        component: ({ data, role }) => {
+          return <NeighborhoodCompanion role={role} subject={data.companionTo} />;
+        },
+      }),
+    ]),
   ),
 );

package/src/components/Lattice/Lattice.tsx

@@ -6,11 +6,10 @@ import { select } from 'd3';
 import React, { useEffect, useMemo, useRef } from 'react';
 
 import { Obj } from '@dxos/echo';
+import { type TreeNode, useContainerSize } from '@dxos/react-ui-graph';
 import { type SpaceGraphNode } from '@dxos/schema';
 
 import { getNodeFillForObject } from '../../util/node-color';
-import { useContainerSize } from '../Tree/layout/useContainerSize';
-import { type TreeNode } from '../Tree/types';
 
 const TRANSITION_MS = 350;
 

package/src/components/Tree/EdgeBundling.stories.tsx

@@ -7,18 +7,18 @@ import * as Effect from 'effect/Effect';
 import React, { useEffect, useMemo, useState } from 'react';
 
 import { withPluginManager } from '@dxos/app-framework/testing';
-import { Query } from '@dxos/echo';
+import { type Obj, Query } from '@dxos/echo';
 import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
 import { corePlugins } from '@dxos/plugin-testing';
 import { random } from '@dxos/random';
 import { useSpaces } from '@dxos/react-client/echo';
+import { Tree, type TreeComponentProps, type TreeNode } from '@dxos/react-ui-graph';
 import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ValueGenerator } from '@dxos/schema/testing';
 import { HasConnection, Organization, Person } from '@dxos/types';
 
 import { buildOrgHierarchy, connectionsToEdges, generateConnectedOrgs } from '../../testing';
-import { Tree, type TreeComponentProps } from './Tree';
-import { type TreeNode } from './types';
+import { getNodeFillForObject } from '../../util';
 
 const generator = random as any as ValueGenerator;
 
@@ -61,6 +61,8 @@ const DefaultStory = ({ variant = 'edge', tension }: { variant?: TreeComponentPr
       node: 'fill-neutral-700 dark:fill-neutral-300',
       path: 'stroke-orange-400/40 dark:stroke-orange-500/40',
       text: 'fill-neutral-700 dark:fill-neutral-200 text-xs',
+      // Boundary cast: the generic node `data` is an ECHO object here (carried opaquely by the renderer).
+      nodeFill: (data: unknown) => getNodeFillForObject(data as Obj.Unknown | undefined),
     }),
     [],
   );

package/src/components/Tree/Tree.stories.tsx

@@ -5,11 +5,13 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useMemo } from 'react';
 
+import { type Obj } from '@dxos/echo';
 import { random } from '@dxos/random';
+import { Tree, type TreeComponentProps } from '@dxos/react-ui-graph';
 import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
 
 import { createTree } from '../../testing';
-import { Tree, type TreeComponentProps } from './Tree';
+import { getNodeFillForObject } from '../../util';
 import { treeTypeToTreeNode } from './types';
 
 random.seed(1);
@@ -22,7 +24,10 @@ const DefaultStory = ({ variant }: StoryArgs) => {
     return <Loading />;
   }
 
-  return <Tree data={data} variant={variant} />;
+  // Inject the ECHO-aware leaf fill (radial/edge variants) now that the renderer is domain-agnostic.
+  // Boundary cast: the generic node `data` is an ECHO object here (the renderer carries it opaquely).
+  const slots = { nodeFill: (data: unknown) => getNodeFillForObject(data as Obj.Unknown | undefined) };
+  return <Tree data={data} variant={variant} slots={slots} />;
 };
 
 const meta: Meta<StoryArgs> = {

package/src/components/Tree/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './Tree';
-export * from './layout';
-export { type TreeNode, treeTypeToTreeNode } from './types';
+// The Tree renderer + layouts moved to @dxos/react-ui-graph; this keeps the ECHO `TreeType` schema
+// and the `treeTypeToTreeNode` converter that adapt plugin-explorer data to the renderer.
+export * from './types';

package/src/components/Tree/types/tree.ts

@@ -19,12 +19,12 @@ export const TreeNodeType = Schema.Struct({
 
 export type TreeNodeType = Schema.Schema.Type<typeof TreeNodeType>;
 
-export const TreeType = Schema.Struct({
-  root: Key.EntityId,
-  nodes: Schema.mutable(Schema.Record({ key: Key.EntityId, value: TreeNodeType })),
-}).pipe(Type.makeObject(DXN.make('org.dxos.type.tree', '0.1.0')));
-
-export type TreeType = Type.InstanceType<typeof TreeType>;
+export class TreeType extends Type.makeObject<TreeType>(DXN.make('org.dxos.type.tree', '0.1.0'))(
+  Schema.Struct({
+    root: Key.EntityId,
+    nodes: Schema.mutable(Schema.Record({ key: Key.EntityId, value: TreeNodeType })),
+  }),
+) {}
 
 /**
  * Wrapper object for tree.

package/src/components/Tree/types/types.ts

@@ -3,20 +3,10 @@
 //
 
 import { type Key } from '@dxos/echo';
+import { type TreeNode } from '@dxos/react-ui-graph';
 
 import { type TreeType } from './tree';
 
-/**
- * In-memory tree shape used by the d3 layouts.
- * `data` carries through to layout callbacks (e.g. hover/inspect) — typically an ECHO object on leaves.
- */
-export type TreeNode<TData = unknown> = {
-  id: string;
-  label?: string;
-  data?: TData;
-  children?: TreeNode<TData>[];
-};
-
 /**
  * Convert an ECHO `TreeType` (id-keyed node map) into a nested `TreeNode` hierarchy.
  * Returns `undefined` if the root id is missing — the tree is then incomplete and shouldn't render.

package/src/components/Visualization/Visualization.stories.tsx

@@ -0,0 +1,104 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type SpaceGraphEdge, SpaceGraphModel, type SpaceGraphNode } from '@dxos/schema';
+import '@dxos/react-ui-graph/styles/graph.css';
+
+import { type VisualizationVariantId } from './variants';
+import { Visualization } from './Visualization';
+
+// Synthetic neighbourhood: inbound sources → focus (left), focus → near → far (right, outgoing).
+const NODES: SpaceGraphNode[] = [
+  { id: 'focus', type: 'object', data: { label: 'Focus' } },
+  ...Array.from(
+    { length: 3 },
+    (_, index): SpaceGraphNode => ({
+      id: `src-${index}`,
+      type: 'object',
+      data: { label: `Source ${index}` },
+    }),
+  ),
+  ...Array.from(
+    { length: 5 },
+    (_, index): SpaceGraphNode => ({
+      id: `near-${index}`,
+      type: 'object',
+      data: { label: `Near ${index}` },
+    }),
+  ),
+  ...Array.from(
+    { length: 8 },
+    (_, index): SpaceGraphNode => ({
+      id: `far-${index}`,
+      type: 'object',
+      data: { label: `Far ${index}` },
+    }),
+  ),
+];
+
+const EDGES: SpaceGraphEdge[] = [
+  // Inbound: sources point at the focus (left side, terminal).
+  ...Array.from(
+    { length: 3 },
+    (_, index): SpaceGraphEdge => ({
+      id: `e-src-focus-${index}`,
+      type: 'ref',
+      source: `src-${index}`,
+      target: 'focus',
+      data: { force: true },
+    }),
+  ),
+  // Outgoing: focus → near → far (right side, explored).
+  ...Array.from(
+    { length: 5 },
+    (_, index): SpaceGraphEdge => ({
+      id: `e-focus-near-${index}`,
+      type: 'ref',
+      source: 'focus',
+      target: `near-${index}`,
+      data: { force: true },
+    }),
+  ),
+  ...Array.from(
+    { length: 8 },
+    (_, index): SpaceGraphEdge => ({
+      id: `e-near-far-${index}`,
+      type: 'ref',
+      source: `near-${index % 5}`,
+      target: `far-${index}`,
+      data: { force: true },
+    }),
+  ),
+];
+
+type StoryArgs = { variant: VisualizationVariantId; focus?: string };
+
+const DefaultStory = ({ variant, focus }: StoryArgs) => {
+  const model = useMemo(() => new SpaceGraphModel(Registry.make(), { nodes: NODES, edges: EDGES }), []);
+  return (
+    <Visualization.Root classNames='bg-base-surface' model={model} variant={variant} focus={focus}>
+      <Visualization.Graph debug={false} />
+    </Visualization.Root>
+  );
+};
+
+const meta: Meta<StoryArgs> = {
+  title: 'plugins/plugin-explorer/components/Visualization',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Force: Story = { args: { variant: 'force' } };
+
+export const Neighborhood: Story = { args: { variant: 'neighborhood', focus: 'focus' } };

package/src/components/Visualization/Visualization.tsx

@@ -0,0 +1,209 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import { Slot } from '@radix-ui/react-slot';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+import { composableProps, slottable } from '@dxos/react-ui';
+import {
+  type GraphLayout,
+  type GraphLayoutNode,
+  type GraphProjector,
+  GraphSwarmProjector,
+  type ModelPoint,
+  SVG,
+  type SVGContext,
+  type TreeNode,
+} from '@dxos/react-ui-graph';
+import { type SpaceGraphEdge, type SpaceGraphModel, type SpaceGraphNode } from '@dxos/schema';
+import { type SlottableProps } from '@dxos/ui-types';
+
+import { type VisualizationVariant, type VisualizationVariantId, getVariant } from './variants';
+
+//
+// Context
+//
+
+type VisualizationContextValue = {
+  model: SpaceGraphModel;
+  variant: VisualizationVariant;
+  /** Externally-supplied focus (ego centre); overrides click-driven focus when set. */
+  focus?: string;
+};
+
+const [VisualizationProvider, useVisualizationContext] = createContext<VisualizationContextValue>('Visualization.Root');
+
+//
+// Root
+//
+
+export type VisualizationRootProps = SlottableProps<{
+  model: SpaceGraphModel;
+  variant: VisualizationVariantId;
+  /** Focus node id placed at the centre of ego/plexus layouts (e.g. the active node for the companion). */
+  focus?: string;
+  /** Called when the user clicks the visualization surface (e.g. to dismiss a node preview). */
+  onSurfaceClick?: () => void;
+}>;
+
+/**
+ * Surface for a visualization. Resolves the variant definition and shares it (plus the model and
+ * focus) with the child `Visualization.Graph` via context, so the variant string is set in one
+ * place. The surface element is slottable via `asChild` for composition into a host layout.
+ */
+const VisualizationRoot = slottable<
+  HTMLDivElement,
+  { model: SpaceGraphModel; variant: VisualizationVariantId; focus?: string; onSurfaceClick?: () => void }
+>(({ children, asChild, model, variant, focus, onSurfaceClick, ...props }, forwardedRef) => {
+  const { className, ...rest } = composableProps(props, { classNames: 'dx-expander relative' });
+  const Comp = asChild ? Slot : 'div';
+  return (
+    <VisualizationProvider model={model} variant={getVariant(variant)} focus={focus}>
+      <Comp {...rest} className={className} onClick={onSurfaceClick} ref={forwardedRef}>
+        {children}
+      </Comp>
+    </VisualizationProvider>
+  );
+});
+
+VisualizationRoot.displayName = 'Visualization.Root';
+
+//
+// Graph
+//
+
+export type VisualizationGraphProps = {
+  debug?: boolean;
+  onNodeHover?: (node: TreeNode | null, event?: MouseEvent) => void;
+};
+
+/**
+ * Renders the active variant's projector + node renderer into a zoomable SVG surface. Reads the
+ * model, variant definition, and focus from `Visualization.Root` context; owns the live projector,
+ * click-driven focus, and the layout snapshot that lets each variant swap animate from prior positions.
+ */
+const VisualizationGraph = ({ debug = false, onNodeHover }: VisualizationGraphProps) => {
+  const { model, variant, focus } = useVisualizationContext('Visualization.Graph');
+
+  const svgRef = useRef<SVGContext>(null);
+  const [projector, setProjector] = useState<GraphProjector<SpaceGraphNode> | undefined>();
+  const projectorRef = useRef<GraphProjector<SpaceGraphNode> | undefined>(undefined);
+  projectorRef.current = projector;
+
+  // Click-driven focus for focusable variants (plexus). `undefined` means "no node focused".
+  const [clickFocusId, setClickFocusId] = useState<string | undefined>(undefined);
+
+  // Externally-supplied focus (e.g. the active node for the neighborhood companion) wins; otherwise
+  // the click-driven focus drives focusable variants.
+  const focusId = focus ?? clickFocusId;
+
+  // Latest layout we hand to the next SVG projector as `prev`. Captured from the live
+  // projector when the variant changes so node x/y survive the swap.
+  const lastLayoutRef = useRef<GraphLayout<SpaceGraphNode> | undefined>(undefined);
+
+  // Subscribe to the graph atom — keeps it alive across child unmounts (effect-atom
+  // disposes atoms with no subscribers) and triggers re-renders when query results land.
+  useEffect(() => model?.subscribe(() => undefined), [model]);
+
+  // Clear any click focus when leaving a focusable variant so returning starts from the bundle layout.
+  useEffect(() => {
+    if (!variant.focusable) {
+      setClickFocusId(undefined);
+    }
+  }, [variant]);
+
+  // Recreate the projector when the variant or focus changes; snapshot the live layout
+  // first so the next projector animates from where the previous one left off.
+  useEffect(() => {
+    if (projectorRef.current?.layout) {
+      lastLayoutRef.current = projectorRef.current.layout as GraphLayout<SpaceGraphNode>;
+    }
+    if (!svgRef.current) {
+      return;
+    }
+
+    setProjector(variant.createProjector(svgRef.current, { focusId, prev: lastLayoutRef.current }));
+  }, [variant, focusId]);
+
+  // Focusable variants (plexus): clicking an object node re-focuses on it; clicking the current
+  // focus clears it. Synthetic nodes carry no ECHO object, so their clicks are ignored.
+  const handleSelect = useCallback(
+    (node: GraphLayoutNode<SpaceGraphNode>) => {
+      if (!variant.focusable || !node.data?.data?.object) {
+        return;
+      }
+      setClickFocusId((current) => (current === node.id ? undefined : node.id));
+    },
+    [variant],
+  );
+
+  // Cursor avoidance for the SVG swarm. The Graph component hands us pre-transformed
+  // SVG model coordinates — same space the boids live in.
+  const handlePointerMove = useCallback(
+    (point: ModelPoint) => {
+      if (projector instanceof GraphSwarmProjector) {
+        projector.setCursor(point.x, point.y);
+      }
+    },
+    [projector],
+  );
+
+  const handlePointerLeave = useCallback(() => {
+    if (projector instanceof GraphSwarmProjector) {
+      projector.setCursor(null);
+    }
+  }, [projector]);
+
+  const handleInspect = useCallback(
+    (node: GraphLayoutNode<SpaceGraphNode> | null, event: MouseEvent) => {
+      if (!variant.emitsHover) {
+        return;
+      }
+      onNodeHover?.(node ? { id: node.id, data: node.data?.data?.object } : null, event);
+    },
+    [variant, onNodeHover],
+  );
+
+  // Only attach pointer handlers when the variant tracks the cursor — others don't need them
+  // and we want to avoid the per-move CTM math when it'd be a no-op.
+  const pointerProps = variant.trackPointer
+    ? { onPointerMove: handlePointerMove, onPointerLeave: handlePointerLeave }
+    : undefined;
+
+  return (
+    <SVG.Root ref={svgRef}>
+      <SVG.Zoom extent={[1 / 2, 2]}>
+        {/* Mount only once the variant's projector exists; otherwise SVG.Graph falls back to a
+            force projector for a frame, flashing the wrong layout for non-force variants. */}
+        {projector && (
+          <SVG.Graph<SpaceGraphNode, SpaceGraphEdge>
+            model={model}
+            projector={projector}
+            renderNode={variant.renderNode}
+            applyNode={variant.applyNode}
+            edgeOpacity={variant.edgeOpacity}
+            drag={variant.drag}
+            highlightOnHover={variant.highlightOnHover}
+            onSelect={handleSelect}
+            onInspect={handleInspect}
+            {...pointerProps}
+          />
+        )}
+      </SVG.Zoom>
+      {debug && <SVG.FPS />}
+    </SVG.Root>
+  );
+};
+
+VisualizationGraph.displayName = 'Visualization.Graph';
+
+//
+// Visualization
+//
+
+export const Visualization = {
+  Root: VisualizationRoot,
+  Graph: VisualizationGraph,
+};