@dxos/react-ui-canvas-compute 0.13.0 → 0.14.0

package/src/shapes/common/node-def.tsx

@@ -0,0 +1,117 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// The compute shapes as scene-engine node types: the schema is the shape's with the engine's `z`, the view
+// renders the shape's component under the engine's view props, and the ports come from the shape.
+//
+
+import * as Schema from 'effect/Schema';
+import React, { type ComponentType, type FC } from 'react';
+
+import {
+  type CreateProps,
+  DEFAULT_CELL,
+  type Node,
+  type NodeDef,
+  type NodeViewProps,
+  type Port,
+  type Size,
+  UnknownNodeView,
+  nodeDef,
+} from '@dxos/react-ui-canvas/scene';
+import * as Icon from '@dxos/react-ui/Icon';
+
+import { ComputeNodeDefContext, useComputeContext } from '../../hooks/compute-context.ts';
+import { useControllerUpdates } from '../../hooks/useControllerUpdates.ts';
+import { type ComputeShape } from '../defs.ts';
+
+/** The engine's view props with the node narrowed to the shape. */
+export type ComputeNodeViewProps<S extends ComputeShape> = Omit<NodeViewProps, 'node'> & { node: S };
+
+export type ComputeNodeSpec<S extends ComputeShape> = Pick<
+  NodeDef,
+  'name' | 'icon' | 'group' | 'resizable' | 'openable'
+> & {
+  type: S['type'];
+  /** The shape's schema with `z` (`withZ`), so the node is checked as the shape before its view or ports read it. */
+  schema: Schema.Codec<S & { z: string }, unknown, never, never>;
+  component: FC<ComputeNodeViewProps<S>>;
+  /** The shape's factory; the engine's id, centre, size and z are applied over what it makes. */
+  create: (props: Pick<ComputeShape, 'id' | 'center'>) => S;
+  /** In scene px, as the shapes were designed; defaults to the size the factory gives a new shape. */
+  defaultSize?: Size;
+  ports: (shape: S) => readonly Port[];
+};
+
+/**
+ * A size in scene px as nominal units (major cells) to the nearest half cell, so a new node lands close to that px
+ * size and its edges on the grid.
+ */
+const toNominal = ({ width, height }: Size): Size => ({
+  width: Math.round((width / DEFAULT_CELL) * 2) / 2,
+  height: Math.round((height / DEFAULT_CELL) * 2) / 2,
+});
+
+/** A compute shape's node definition. */
+export const defineComputeNode = <S extends ComputeShape>({
+  schema,
+  component,
+  create,
+  defaultSize,
+  ports,
+  ...rest
+}: ComputeNodeSpec<S>): NodeDef => {
+  const isShape = Schema.is(schema);
+  return {
+    ...rest,
+    schema,
+    component: computeNodeView(isShape, component),
+    create: ({ id, z, center, size }: CreateProps): Node => ({ ...create({ id, center }), z, size }),
+    // The engine sizes a new node in nominal units (major grid cells), so the px size is stated in cells.
+    defaultSize: toNominal(defaultSize ?? create({ id: 'default', center: { x: 0, y: 0 } }).size),
+    ports: (node) => (isShape(node) ? ports(node) : []),
+  };
+};
+
+/**
+ * The shape's component under the engine's view props, re-rendered on every controller update since the
+ * runtime state it reads is not reactive; a node that is not the shape renders as an unknown node.
+ */
+const computeNodeView = <S extends ComputeShape>(
+  isShape: (node: Node) => node is Node & S & { z: string },
+  Component: FC<ComputeNodeViewProps<S>>,
+): ComponentType<NodeViewProps> => {
+  const View = (props: NodeViewProps) => {
+    const { node, registry } = props;
+    const { controller } = useComputeContext();
+    useControllerUpdates(controller);
+    if (!isShape(node)) {
+      return <UnknownNodeView {...props} />;
+    }
+    // A shape with no compute node behind it yet (the ghost of a create or palette drag) has no runtime state to
+    // read, so it shows what it will be rather than mounting the live component.
+    if (!node.node) {
+      const def = nodeDef(registry, node);
+      return (
+        <div className='dx-cover flex flex-col items-center justify-center gap-1 text-fg-muted'>
+          {def?.icon && <Icon.Icon icon={def.icon} size='lg' />}
+          <span className='text-sm truncate'>{def?.name ?? node.type}</span>
+        </div>
+      );
+    }
+
+    // The components lay out as a full-size flex container (centring with `grow` / `w-full`); the engine's
+    // node frame is not one, so the wrapper provides it.
+    return (
+      <ComputeNodeDefContext.Provider value={nodeDef(registry, node)}>
+        <div className='dx-cover flex'>
+          <Component {...props} node={node} />
+        </div>
+      </ComputeNodeDefContext.Provider>
+    );
+  };
+  View.displayName = `ComputeNodeView(${Component.displayName ?? Component.name})`;
+  return View;
+};

package/src/shapes/common/ports.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { VoidInput, VoidOutput } from '@dxos/conductor';
+import * as SchemaAST from '@dxos/effect/SchemaAST';
+import { DEFAULT_GRID, type Point, type Port, type Size } from '@dxos/react-ui-canvas/scene';
+
+import { createAnchorId, parseAnchorId } from '../defs.ts';
+import { footerHeight, headerHeight } from './box-defs.ts';
+
+// Kept out of `FunctionBody.tsx`: react-refresh only fast-refreshes a module whose
+// exports are all components, so values exported beside them force a full page reload on every edit.
+
+/**
+ * Height of one property row, two minor grid cells: with the rows centred in a body that is a whole number of rows,
+ * every row's centre, and so every port, lands on a minor grid line.
+ */
+export const rowHeight = 2 * DEFAULT_GRID;
+
+/** A function shape's height: the chrome plus one row per input (at least one), each a whole number of rows. */
+export const getHeight = (input: Schema.Schema<any>) => {
+  const properties = SchemaAST.getPropertySignatures(input.ast);
+  return headerHeight + footerHeight + Math.max(properties.length, 1) * rowHeight;
+};
+
+/** `n` points one row apart, centred on `center`. */
+export const getRowPoints = (center: Point, n: number): Point[] => {
+  const span = (n - 1) * rowHeight;
+  return [...Array(n)].map((_, index) => ({ x: center.x, y: center.y - span / 2 + index * rowHeight }));
+};
+
+/** A port at a point relative to the node's centre, in px. */
+export type PortPoint = { id: string; pos: Point };
+
+/**
+ * The ports at the given points: each sits on whichever edge it is nearer to, at its offset along it; the
+ * id's `input.` / `output.` prefix says which way a link may run.
+ */
+export const pointsToPorts = (points: readonly PortPoint[], size: Size): Port[] =>
+  points.map(({ id, pos }) => {
+    const [kind] = parseAnchorId(id);
+    const half = { x: size.width / 2, y: size.height / 2 };
+    // Ties go to the vertical edges (the input / output sides).
+    const vertical = Math.abs(Math.abs(pos.x) - half.x) <= Math.abs(Math.abs(pos.y) - half.y);
+    const side = vertical ? (pos.x < 0 ? 'w' : 'e') : pos.y < 0 ? 'n' : 's';
+    const along = vertical ? (pos.y + half.y) / size.height : (pos.x + half.x) / size.width;
+    return {
+      id,
+      side,
+      offset: Math.min(Math.max(along, 0), 1),
+      ...(kind === 'input' ? { accepts: 'in' as const } : kind === 'output' ? { accepts: 'out' as const } : {}),
+    };
+  });
+
+/** Ports at points given in half-sizes from the centre (`{ x: 1, y: 0 }` is the middle of the east side). */
+export const createPorts = (size: Size, points: Record<string, Point>): Port[] =>
+  pointsToPorts(
+    Object.entries(points).map(([id, { x, y }]) => ({
+      id,
+      pos: { x: (x * size.width) / 2, y: (y * size.height) / 2 },
+    })),
+    size,
+  );
+
+/** Inputs stacked one row apart down the west side and outputs down the east, centred on `center`. */
+export const createRowPorts = ({
+  size,
+  inputs,
+  outputs,
+  center = { x: 0, y: 0 },
+}: {
+  size: Size;
+  inputs: readonly string[];
+  outputs: readonly string[];
+  center?: Point;
+}): Port[] =>
+  pointsToPorts(
+    [
+      ...getRowPoints({ x: center.x - size.width / 2, y: center.y }, inputs.length).map((pos, index) => ({
+        id: inputs[index],
+        pos,
+      })),
+      ...getRowPoints({ x: center.x + size.width / 2, y: center.y }, outputs.length).map((pos, index) => ({
+        id: outputs[index],
+        pos,
+      })),
+    ],
+    size,
+  );
+
+/** A function shape's ports: one per property of its input and output schemas, level with the body's rows. */
+export const createFunctionPorts = (
+  size: Size,
+  input: Schema.Schema<any> = VoidInput,
+  output: Schema.Schema<any> = VoidOutput,
+): Port[] => {
+  // TODO(burdon): Set type.
+  const inputs = SchemaAST.getPropertySignatures(input.ast).map(({ name }) => createAnchorId('input', name.toString()));
+  const outputs = SchemaAST.getPropertySignatures(output.ast).map(({ name }) =>
+    createAnchorId('output', name.toString()),
+  );
+  // The rows are centred in the body, between the header and the footer.
+  return createRowPorts({ size, inputs, outputs, center: { x: 0, y: (headerHeight - footerHeight) / 2 } });
+};

package/src/shapes/constant-def.tsx

@@ -6,11 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 import React from 'react';
 
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
-import { createAnchorMap } from '@dxos/react-ui-canvas-editor';
-
+import { createPorts, defineComputeNode } from './common/index.ts';
 import { ConstantComponent } from './Constant.tsx';
-import { ComputeShape, type CreateShapeProps, createAnchorId, createShape } from './defs.ts';
+import { ComputeShape, type CreateShapeProps, createAnchorId, createShape, withZ } from './defs.ts';
 
 // Kept out of `Constant.tsx`: react-refresh only fast-refreshes a module whose
 // exports are all components, so values exported beside them force a full page reload on every edit.
@@ -37,12 +35,14 @@ export type CreateConstantProps = CreateShapeProps<ConstantShape>;
 export const createConstant = (props: CreateConstantProps) =>
   createShape<ConstantShape>({ type: 'constant', size: { width: 192, height: 128 }, ...props });
 
-export const constantShape: ShapeDef<ConstantShape> = {
+export const constantNodeDef = defineComputeNode<ConstantShape>({
   type: 'constant',
   name: 'Value',
   icon: 'ph--dots-three-circle--regular',
+  group: 'Inputs',
+  schema: withZ(ConstantShape),
   component: (props) => <ConstantComponent {...props} placeholder={'Constant'} />,
-  createShape: createConstant,
-  getAnchors: (shape) => createAnchorMap(shape, { [createAnchorId('output')]: { x: 1, y: 0 } }),
+  create: createConstant,
+  ports: (shape) => createPorts(shape.size, { [createAnchorId('output')]: { x: 1, y: 0 } }),
   resizable: true,
-};
+});

package/src/shapes/database-def.ts

@@ -5,11 +5,9 @@
 import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
-import { createAnchorMap } from '@dxos/react-ui-canvas-editor';
-
+import { createPorts, defineComputeNode } from './common/index.ts';
 import { DatabaseComponent } from './Database.tsx';
-import { ComputeShape, type CreateShapeProps, createAnchorId, createShape } from './defs.ts';
+import { ComputeShape, type CreateShapeProps, createAnchorId, createShape, withZ } from './defs.ts';
 
 // Kept out of `Database.tsx`: react-refresh only fast-refreshes a module whose
 // exports are all components, so values exported beside them force a full page reload on every edit.
@@ -27,11 +25,13 @@ export type CreateDatabaseProps = CreateShapeProps<DatabaseShape>;
 export const createDatabase = (props: CreateDatabaseProps) =>
   createShape<DatabaseShape>({ type: 'database', size: { width: 128, height: 64 }, ...props });
 
-export const databaseShape: ShapeDef<DatabaseShape> = {
+export const databaseNodeDef = defineComputeNode<DatabaseShape>({
   type: 'database',
   name: 'ECHO',
   icon: 'ph--database--regular',
+  group: 'Transform',
+  schema: withZ(DatabaseShape),
   component: DatabaseComponent,
-  createShape: createDatabase,
-  getAnchors: (shape) => createAnchorMap(shape, { [createAnchorId('output')]: { x: 1, y: 0 } }),
-};
+  create: createDatabase,
+  ports: (shape) => createPorts(shape.size, { [createAnchorId('output')]: { x: 1, y: 0 } }),
+});

package/src/shapes/defs.ts

@@ -8,9 +8,11 @@ import * as Struct from 'effect/Struct';
 import { DEFAULT_INPUT, DEFAULT_OUTPUT } from '@dxos/conductor';
 import { Obj } from '@dxos/echo';
 import * as SchemaAST from '@dxos/effect/SchemaAST';
-import { Polygon } from '@dxos/react-ui-canvas-editor';
+import { Point, Size } from '@dxos/react-ui-canvas/scene';
 import { type MakeOptional } from '@dxos/util';
 
+import { CanvasBoard } from '../types/index.ts';
+
 //
 // Properties
 //
@@ -32,17 +34,30 @@ export const parseAnchorId = (id: string): [PropertyKind | undefined, string] =>
 // Shapes
 //
 
-export type CreateShapeProps<S extends Polygon> = Omit<MakeOptional<S, 'id' | 'size'>, 'type' | 'node'>;
+export type CreateShapeProps<S extends ComputeShape> = Omit<MakeOptional<S, 'id' | 'size'>, 'type' | 'node'>;
 
-export const ComputeShape = Polygon.mapFields(
+// The board's stored shape (a closed shape with a centre and size, every key mutable), so boards the editor wrote
+// still decode.
+export const ComputeShape = CanvasBoard.Shape.mapFields(
   Struct.assign({
-    // TODO(burdon): Rename computeNode?
-    node: Schema.mutableKey(Schema.optional(Obj.ID.annotate({ description: 'Compute node id' }))),
+    center: Point,
+    size: Size.mapFields(Struct.map(Schema.mutableKey)),
   }),
-);
+)
+  .mapFields(Struct.map(Schema.mutableKey))
+  .mapFields(
+    Struct.assign({
+      // TODO(burdon): Rename computeNode?
+      node: Schema.mutableKey(Schema.optional(Obj.ID.annotate({ description: 'Compute node id' }))),
+    }),
+  );
 
 export type ComputeShape = Schema.Schema.Type<typeof ComputeShape>;
 
+/** The shape's schema with the engine's z-order key, so it is a node schema. */
+export const withZ = <Fields extends Schema.Struct.Fields>(shape: Schema.Struct<Fields>) =>
+  shape.mapFields(Struct.assign({ z: Schema.String }));
+
 export const createShape = <S extends ComputeShape>({ id, ...rest }: CreateShapeProps<S> & { type: string }): S => {
   return {
     id: id ?? Obj.ID.random(),

package/src/shapes/feed-def.ts

@@ -6,10 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
 import { QueueInput, QueueOutput } from '@dxos/conductor';
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
 
-import { createFunctionAnchors } from './common/index.ts';
-import { ComputeShape, type CreateShapeProps, createShape } from './defs.ts';
+import { createFunctionPorts, defineComputeNode } from './common/index.ts';
+import { ComputeShape, type CreateShapeProps, createShape, withZ } from './defs.ts';
 import { FeedComponent } from './Feed.tsx';
 
 // Kept out of `Feed.tsx`: react-refresh only fast-refreshes a module whose
@@ -32,13 +31,15 @@ export const createFeed = (props: CreateFeedProps) =>
     ...props,
   });
 
-export const feedShape: ShapeDef<FeedShape> = {
+export const feedNodeDef = defineComputeNode<FeedShape>({
   // Must match the shape's `type` literal ('queue') so the registry resolves it; the registry is keyed by this.
   type: 'queue',
   name: 'Feed',
   icon: 'ph--queue--regular',
+  group: 'Outputs',
+  schema: withZ(FeedShape),
   component: FeedComponent,
-  createShape: createFeed,
-  getAnchors: (shape) => createFunctionAnchors(shape, QueueInput, QueueOutput),
+  create: createFeed,
+  ports: (shape) => createFunctionPorts(shape.size, QueueInput, QueueOutput),
   resizable: true,
-};
+});

package/src/shapes/function-def.ts

@@ -6,10 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
 import { AnyOutput, FunctionInput } from '@dxos/conductor';
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
 
-import { createFunctionAnchors } from './common/index.ts';
-import { ComputeShape, type CreateShapeProps, createShape } from './defs.ts';
+import { createFunctionPorts, defineComputeNode } from './common/index.ts';
+import { ComputeShape, type CreateShapeProps, createShape, withZ } from './defs.ts';
 import { FunctionShapeComponent } from './Function.tsx';
 
 // Kept out of `Function.tsx`: react-refresh only fast-refreshes a module whose
@@ -36,11 +35,13 @@ export const createFunction = (props: CreateFunctionProps) =>
 // Defs
 //
 
-export const functionShape: ShapeDef<FunctionShape> = {
+export const functionNodeDef = defineComputeNode<FunctionShape>({
   type: 'function',
   name: 'Function',
   icon: 'ph--function--regular',
+  group: 'Transform',
+  schema: withZ(FunctionShape),
   component: FunctionShapeComponent,
-  createShape: createFunction,
-  getAnchors: (shape) => createFunctionAnchors(shape, FunctionInput, AnyOutput),
-};
+  create: createFunction,
+  ports: (shape) => createFunctionPorts(shape.size, FunctionInput, AnyOutput),
+});

package/src/shapes/gpt-def.ts

@@ -6,10 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
 import { GptInput, GptOutput } from '@dxos/conductor';
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
 
-import { createFunctionAnchors, getHeight } from './common/index.ts';
-import { ComputeShape, type CreateShapeProps, createShape } from './defs.ts';
+import { createFunctionPorts, defineComputeNode, getHeight } from './common/index.ts';
+import { ComputeShape, type CreateShapeProps, createShape, withZ } from './defs.ts';
 import { GptComponent } from './Gpt.tsx';
 
 // Kept out of `Gpt.tsx`: react-refresh only fast-refreshes a module whose
@@ -32,12 +31,14 @@ export const createGpt = (props: CreateGptProps) =>
     ...props,
   });
 
-export const gptShape: ShapeDef<GptShape> = {
+export const gptNodeDef = defineComputeNode<GptShape>({
   type: 'gpt',
   name: 'GPT',
   icon: 'ph--brain--regular',
+  group: 'Transform',
+  schema: withZ(GptShape),
   component: GptComponent,
-  createShape: createGpt,
-  getAnchors: (shape) => createFunctionAnchors(shape, GptInput, GptOutput),
+  create: createGpt,
+  ports: (shape) => createFunctionPorts(shape.size, GptInput, GptOutput),
   openable: true,
-};
+});

package/src/shapes/gpt-realtime-def.ts

@@ -5,10 +5,8 @@
 import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
-
-import { createFunctionAnchors } from './common/index.ts';
-import { ComputeShape, type CreateShapeProps, createShape } from './defs.ts';
+import { createFunctionPorts, defineComputeNode } from './common/index.ts';
+import { ComputeShape, type CreateShapeProps, createShape, withZ } from './defs.ts';
 import { GptRealtimeComponent } from './GptRealtime.tsx';
 
 // Kept out of `GptRealtime.tsx`: react-refresh only fast-refreshes a module whose
@@ -27,20 +25,22 @@ export type CreateGptRealtimeProps = CreateShapeProps<GptRealtimeShape>;
 export const createGptRealtime = (props: CreateGptRealtimeProps) =>
   createShape<GptRealtimeShape>({ type: 'gpt-realtime', size: { width: 256, height: 256 }, ...props });
 
-export const gptRealtimeShape: ShapeDef<GptRealtimeShape> = {
+export const gptRealtimeNodeDef = defineComputeNode<GptRealtimeShape>({
   type: 'gpt-realtime',
   name: 'GPT Realtime',
   icon: 'ph--pulse--regular',
+  group: 'Transform',
+  schema: withZ(GptRealtimeShape),
   component: GptRealtimeComponent,
-  createShape: createGptRealtime,
+  create: createGptRealtime,
   // TODO(dmaretskyi): Can we fetch the schema dynamically?
-  getAnchors: (shape) =>
-    createFunctionAnchors(
-      shape,
+  ports: (shape) =>
+    createFunctionPorts(
+      shape.size,
       Schema.Struct({
         audio: Schema.Any,
       }),
       Schema.Struct({}),
     ),
   resizable: true,
-};
+});

package/src/shapes/json-def.ts

@@ -6,11 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
 import { DefaultOutput, JsonTransformInput } from '@dxos/conductor';
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
-import { createAnchorMap } from '@dxos/react-ui-canvas-editor';
 
-import { createFunctionAnchors, getHeight } from './common/index.ts';
-import { ComputeShape, type CreateShapeProps, createAnchorId, createShape } from './defs.ts';
+import { createFunctionPorts, createPorts, defineComputeNode, getHeight } from './common/index.ts';
+import { ComputeShape, type CreateShapeProps, createAnchorId, createShape, withZ } from './defs.ts';
 import { JsonComponent, JsonTransformComponent } from './Json.tsx';
 
 // Kept out of `Json.tsx`: react-refresh only fast-refreshes a module whose
@@ -45,19 +43,21 @@ export type CreateJsonProps = CreateShapeProps<JsonShape>;
 export const createJson = (props: CreateJsonProps) =>
   createShape<JsonShape>({ type: 'json', size: { width: 256, height: 256 }, ...props });
 
-export const jsonShape: ShapeDef<JsonShape> = {
+export const jsonNodeDef = defineComputeNode<JsonShape>({
   type: 'json',
   name: 'JSON',
   icon: 'ph--code--regular',
+  group: 'Outputs',
+  schema: withZ(JsonShape),
   component: JsonComponent,
-  createShape: createJson,
-  getAnchors: (shape) =>
-    createAnchorMap(shape, {
+  create: createJson,
+  ports: (shape) =>
+    createPorts(shape.size, {
       [createAnchorId('input')]: { x: -1, y: 0 },
       [createAnchorId('output')]: { x: 1, y: 0 },
     }),
   resizable: true,
-};
+});
 
 export type CreateJsonTransformProps = CreateShapeProps<JsonTransformShape> & { expression?: string };
 
@@ -68,12 +68,14 @@ export const createJsonTransform = (props: CreateJsonTransformProps) =>
     ...props,
   });
 
-export const jsonTransformShape: ShapeDef<JsonTransformShape> = {
+export const jsonTransformNodeDef = defineComputeNode<JsonTransformShape>({
   type: 'json-transform',
   name: 'Transform',
   icon: 'ph--shuffle-simple--regular',
+  group: 'Operations',
+  schema: withZ(JsonTransformShape),
   component: JsonTransformComponent,
-  createShape: createJsonTransform,
-  getAnchors: (shape) => createFunctionAnchors(shape, JsonTransformInput, DefaultOutput),
+  create: createJsonTransform,
+  ports: (shape) => createFunctionPorts(shape.size, JsonTransformInput, DefaultOutput),
   resizable: true,
-};
+});

package/src/shapes/logic-def.ts

@@ -6,10 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
 import { IfElseInput, IfElseOutput, IfInput, IfOutput } from '@dxos/conductor';
-import { type ShapeDef } from '@dxos/react-ui-canvas-editor';
 
-import { createFunctionAnchors, getHeight } from './common/index.ts';
-import { ComputeShape, type CreateShapeProps, createShape } from './defs.ts';
+import { createFunctionPorts, defineComputeNode, getHeight } from './common/index.ts';
+import { ComputeShape, type CreateShapeProps, createShape, withZ } from './defs.ts';
 import { IfComponent, IfElseComponent } from './Logic.tsx';
 
 // Kept out of `Logic.tsx`: react-refresh only fast-refreshes a module whose
@@ -44,25 +43,29 @@ export type CreateIfProps = CreateShapeProps<IfShape> & { if?: string };
 export const createIf = (props: CreateIfProps) =>
   createShape<IfShape>({ type: 'if', size: { width: 192, height: getHeight(IfInput) }, ...props });
 
-export const ifShape: ShapeDef<IfShape> = {
+export const ifNodeDef = defineComputeNode<IfShape>({
   type: 'if',
   name: 'IF',
   icon: 'ph--arrows-split--regular',
+  group: 'Operations',
+  schema: withZ(IfShape),
   component: IfComponent,
-  createShape: createIf,
-  getAnchors: (shape) => createFunctionAnchors(shape, IfInput, IfOutput),
-};
+  create: createIf,
+  ports: (shape) => createFunctionPorts(shape.size, IfInput, IfOutput),
+});
 
 export type CreateIfElseProps = CreateShapeProps<IfShape> & { if?: string };
 
 export const createIfElse = (props: CreateIfElseProps) =>
   createShape<IfElseShape>({ type: 'if-else', size: { width: 192, height: getHeight(IfElseInput) }, ...props });
 
-export const ifElseShape: ShapeDef<IfElseShape> = {
+export const ifElseNodeDef = defineComputeNode<IfElseShape>({
   type: 'if-else',
   name: 'IF/ELSE',
   icon: 'ph--arrows-merge--regular',
+  group: 'Operations',
+  schema: withZ(IfElseShape),
   component: IfElseComponent,
-  createShape: createIfElse,
-  getAnchors: (shape) => createFunctionAnchors(shape, IfElseInput, IfElseOutput),
-};
+  create: createIfElse,
+  ports: (shape) => createFunctionPorts(shape.size, IfElseInput, IfElseOutput),
+});

package/src/shapes/ports.test.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { DEFAULT_GRID, nominalSize } from '@dxos/react-ui-canvas/scene';
+
+import { computeNodeDefs } from '../registry.ts';
+
+describe('compute ports', () => {
+  test('every port of a new shape sits on a minor grid line', ({ expect }) => {
+    for (const def of computeNodeDefs) {
+      const size = nominalSize(def.defaultSize);
+      const node = def.create({ id: 'n', z: 'a0', center: { x: size.width / 2, y: size.height / 2 }, size });
+      for (const port of def.ports?.(node) ?? []) {
+        const along = port.side === 'w' || port.side === 'e' ? size.height : size.width;
+        // Distance from the node's top (or left) edge, which snaps to the grid.
+        expect(`${def.type} ${port.id} ${(port.offset * along) % DEFAULT_GRID}`).toBe(`${def.type} ${port.id} 0`);
+      }
+    }
+  });
+});

package/src/shapes/rng-def.ts

@@ -5,9 +5,8 @@
 import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
-import { type ShapeDef, createAnchorMap } from '@dxos/react-ui-canvas-editor';
-
-import { ComputeShape, type CreateShapeProps, createAnchorId, createShape } from './defs.ts';
+import { createPorts, defineComputeNode } from './common/index.ts';
+import { ComputeShape, type CreateShapeProps, createAnchorId, createShape, withZ } from './defs.ts';
 import { RandomComponent } from './RNG.tsx';
 
 // Kept out of `RNG.tsx`: react-refresh only fast-refreshes a module whose
@@ -32,11 +31,13 @@ export const createRandom = (props: CreateRandomProps) =>
     ...props,
   });
 
-export const randomShape: ShapeDef<RandomShape> = {
+export const randomNodeDef = defineComputeNode<RandomShape>({
   type: 'rng',
   name: 'Random',
   icon: 'ph--dice-six--regular',
+  group: 'Inputs',
+  schema: withZ(RandomShape),
   component: RandomComponent,
-  createShape: createRandom,
-  getAnchors: (shape) => createAnchorMap(shape, { [createAnchorId('output')]: { x: 1, y: 0 } }),
-};
+  create: createRandom,
+  ports: (shape) => createPorts(shape.size, { [createAnchorId('output')]: { x: 1, y: 0 } }),
+});