@kiberon-labs/behave-graph-flow 1.0.0 → 3.0.0

package/src/types/NodeMetadata.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure metadata types for visual graph editor
+ * NO execution code, NO node factories, NO runtime dependencies
+ */
+
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+
+export interface ValueTypeMetadata {
+  name: string;
+  creator: () => any;
+  deserialize?: (value: any) => any;
+  serialize?: (value: any) => any;
+  lerp?: (start: any, end: any, t: number) => any;
+  equals?: (a: any, b: any) => boolean;
+  clone?: (value: any) => any;
+}
+
+/**
+ * Pure metadata registry - no execution capabilities
+ * Used by the visual graph editor for rendering nodes
+ */
+export interface INodeRegistry {
+  readonly values: Record<string, ValueTypeMetadata>;
+  readonly specs: NodeSpecJSON[];
+}
+
+export type NodeMetadata = Record<string, string>;

package/src/types/graph.ts

@@ -0,0 +1,49 @@
+import type { GraphJSON } from '@kiberon-labs/behave-graph';
+import type { Edge, Node } from 'reactflow';
+import type { SerializedLayers } from '@/store/layers';
+
+export type UIGraphData = Record<string, unknown> & {
+  layers?: SerializedLayers;
+};
+
+export type UIGraphJSON = {
+  /**
+   * Version of the graph
+   */
+  v: string;
+  name: string;
+  /**
+   * Graph annotations as metadata
+   */
+  annotations: Record<string, unknown>;
+
+  /** User specific */
+  user?: {
+    viewport: {
+      x: number;
+      y: number;
+      zoom: number;
+    };
+    /**
+     * Saved viewports for multiple positions
+     */
+    viewports?: {
+      x: number;
+      y: number;
+      zoom: number;
+    }[];
+  };
+
+  /**
+   * Arbitrary data associated with the graph.
+   * Expected to be used with plugins/extensions. This is seperate from graph annotations
+   */
+  data: UIGraphData;
+  /**
+   * The serialized graph data.
+   * This is currently the embedded JSON format from behave-graph
+   */
+  flow: GraphJSON;
+  nodes: Node[];
+  edges: Edge[];
+};

package/src/types/nodes.ts

@@ -0,0 +1,50 @@
+import type { DynamicPorts } from '@/types';
+import type { Node } from 'reactflow';
+
+/**
+ * These are the behave nodes in the scene
+ */
+export type IBehaveNode = Omit<Node, 'data' | 'type'> & {
+  type: 'behaveNode';
+  data: {
+    annotations?: Record<string, any>;
+    type: string;
+    dynamicPorts: DynamicPorts;
+    ports?: Record<string, any>;
+    configuration: Record<string, any>;
+  };
+};
+
+/**
+ * Presentational markdown note, contributed by the notes plugin
+ * (`@/plugin/notes`). `commentNode` is the legacy type string notes carried
+ * when they lived in the core editor.
+ */
+export type INoteNode = Omit<Node, 'data' | 'type'> & {
+  type: 'noteNode' | 'commentNode';
+  data: {
+    annotations?: Record<string, any>;
+    text: string;
+    fontSize?: string;
+  };
+};
+
+export type IGroupNode = Omit<Node, 'data' | 'type'> & {
+  type: 'group';
+  data: {
+    color: string;
+  };
+};
+
+export type IAINode = Omit<Node, 'data' | 'type'> & {
+  type: 'behaveNode:ai';
+  data: {
+    annotations?: Record<string, any>;
+    type: string;
+    ports?: DynamicPorts;
+    configuration: Record<string, any>;
+  };
+};
+
+export type AnyNode = IBehaveNode | INoteNode | IAINode | IGroupNode;
+export type AnyNodeType = AnyNode['type'];

package/src/types.ts

@@ -0,0 +1,18 @@
+import type { ChoiceJSON } from '@kiberon-labs/behave-graph';
+
+export interface SocketBase {
+  name: string;
+  key: string;
+  /** Optional display label; falls back to `name` when absent. */
+  label?: string;
+  choices?: ChoiceJSON;
+  valueType: string;
+  defaultValue?: any;
+}
+
+export type Socket = SocketBase;
+
+export interface DynamicPorts {
+  inputs?: SocketBase[];
+  outputs?: SocketBase[];
+}

package/src/util/autoConvert.ts

@@ -0,0 +1,200 @@
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+import type { Connection, Edge, Node, XYPosition } from 'reactflow';
+import { v4 as uuidv4 } from 'uuid';
+import { getSocketsByNodeTypeAndHandleType } from './getSocketsByNodeTypeAndHandleType.js';
+import { mergeSockets } from './mergeSockets.js';
+import type { ConversionRule } from '@/store/conversions';
+import type { IBehaveNode } from '@/types/nodes.js';
+
+/**
+ * Find a node spec that converts `sourceType` to `targetType` , a pure value
+ * function with exactly one value input of the source type and one value output
+ * of the target type, and no flow sockets (e.g. `math/toString/integer`).
+ */
+export const findConverterSpec = (
+  specs: NodeSpecJSON[],
+  sourceType: string,
+  targetType: string
+): NodeSpecJSON | undefined =>
+  specs.find((spec) => {
+    const valueIns = spec.inputs.filter((i) => i.valueType !== 'flow');
+    const valueOuts = spec.outputs.filter((o) => o.valueType !== 'flow');
+    const hasFlow =
+      spec.inputs.some((i) => i.valueType === 'flow') ||
+      spec.outputs.some((o) => o.valueType === 'flow');
+    return (
+      !hasFlow &&
+      valueIns.length === 1 &&
+      valueOuts.length === 1 &&
+      valueIns[0]!.valueType === sourceType &&
+      valueOuts[0]!.valueType === targetType
+    );
+  });
+
+export type ResolvedConverter = {
+  nodeType: string;
+  inputName: string;
+  outputName: string;
+};
+
+const firstValueSocketName = (
+  sockets: { name: string; valueType: string }[]
+): string | undefined => sockets.find((s) => s.valueType !== 'flow')?.name;
+
+/**
+ * Pick the socket that should carry a value of `valueType`: prefer one whose type
+ * matches exactly (so multi-port converter nodes resolve the *right* port), then
+ * fall back to the first non-flow socket for single-port nodes.
+ */
+const socketNameForType = (
+  sockets: { name: string; valueType: string }[],
+  valueType: string
+): string | undefined =>
+  sockets.find((s) => s.valueType === valueType)?.name ??
+  firstValueSocketName(sockets);
+
+/**
+ * Resolve which converter to use for `from`→`to`. A registered
+ * {@link ConversionRule} (e.g. from a custom profile) takes precedence; otherwise
+ * fall back to scanning the specs for a generic single-in/single-out converter.
+ *
+ * A rule's `inputKey`/`outputKey` pin the exact ports to wire (required for
+ * converter nodes with more than one input or output). When omitted they are
+ * resolved by matching the port's value type to `from`/`to`.
+ */
+export const resolveConverter = (
+  specs: NodeSpecJSON[],
+  from: string,
+  to: string,
+  conversions?: ConversionRule[]
+): ResolvedConverter | undefined => {
+  const rule = conversions?.find((c) => c.from === from && c.to === to);
+  if (rule) {
+    const spec = specs.find((s) => s.type === rule.nodeType);
+    const inputName =
+      rule.inputKey ?? socketNameForType(spec?.inputs ?? [], from);
+    const outputName =
+      rule.outputKey ?? socketNameForType(spec?.outputs ?? [], to);
+    if (inputName && outputName) {
+      return { nodeType: rule.nodeType, inputName, outputName };
+    }
+    return undefined;
+  }
+
+  const spec = findConverterSpec(specs, from, to);
+  if (!spec) return undefined;
+  const inputName = firstValueSocketName(spec.inputs);
+  const outputName = firstValueSocketName(spec.outputs);
+  if (!inputName || !outputName) return undefined;
+  return { nodeType: spec.type, inputName, outputName };
+};
+
+/** Resolve a node socket's value type (spec sockets merged with dynamic ports). */
+const getSocketValueType = (
+  node: IBehaveNode,
+  handleId: string | null | undefined,
+  handleType: 'source' | 'target',
+  specs: NodeSpecJSON[]
+): string | undefined => {
+  if (!handleId) return undefined;
+  const specSockets = getSocketsByNodeTypeAndHandleType(
+    specs,
+    node.data?.type,
+    handleType
+  );
+  if (!specSockets) return undefined;
+  const dynamic =
+    handleType === 'source'
+      ? node.data.dynamicPorts?.outputs
+      : node.data.dynamicPorts?.inputs;
+  const sockets = mergeSockets(specSockets, dynamic);
+  return sockets.find((s) => s.name === handleId)?.valueType;
+};
+
+export type ConverterInsertion = { node: IBehaveNode; edges: Edge[] };
+
+/**
+ * If a connection joins different-but-convertible value types, build the
+ * converter node and the two edges needed to splice it in between source and
+ * target. Returns null when the types match, can't be resolved, or no converter
+ * is registered.
+ */
+export const buildConverterInsertion = (
+  connection: Connection,
+  nodes: Node[],
+  specs: NodeSpecJSON[],
+  conversions?: ConversionRule[]
+): ConverterInsertion | null => {
+  if (!connection.source || !connection.target) return null;
+
+  const sourceNode = nodes.find((n) => n.id === connection.source) as
+    | IBehaveNode
+    | undefined;
+  const targetNode = nodes.find((n) => n.id === connection.target) as
+    | IBehaveNode
+    | undefined;
+  if (!sourceNode || !targetNode) return null;
+
+  const sourceType = getSocketValueType(
+    sourceNode,
+    connection.sourceHandle,
+    'source',
+    specs
+  );
+  const targetType = getSocketValueType(
+    targetNode,
+    connection.targetHandle,
+    'target',
+    specs
+  );
+  if (!sourceType || !targetType) return null;
+  if (sourceType === targetType) return null;
+  if (sourceType === 'flow' || targetType === 'flow') return null;
+
+  const converter = resolveConverter(
+    specs,
+    sourceType,
+    targetType,
+    conversions
+  );
+  if (!converter) return null;
+
+  const { nodeType, inputName: inName, outputName: outName } = converter;
+
+  const position: XYPosition = {
+    x: (sourceNode.position.x + targetNode.position.x) / 2,
+    y: (sourceNode.position.y + targetNode.position.y) / 2
+  };
+
+  const convId = uuidv4();
+  const node: IBehaveNode = {
+    id: convId,
+    type: 'behaveNode',
+    position,
+    data: {
+      type: nodeType,
+      configuration: {},
+      ports: {},
+      dynamicPorts: {}
+    }
+  };
+
+  const edges: Edge[] = [
+    {
+      id: uuidv4(),
+      source: connection.source,
+      sourceHandle: connection.sourceHandle ?? undefined,
+      target: convId,
+      targetHandle: inName
+    },
+    {
+      id: uuidv4(),
+      source: convId,
+      sourceHandle: outName,
+      target: connection.target,
+      targetHandle: connection.targetHandle ?? undefined
+    }
+  ];
+
+  return { node, edges };
+};

package/src/util/colors.ts

@@ -1,34 +1,6 @@
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 
-export type color =
-  | 'red'
-  | 'green'
-  | 'lime'
-  | 'purple'
-  | 'blue'
-  | 'gray'
-  | 'white';
-
-export const colors: Record<color, [string, string, string]> = {
-  red: ['bg-orange-700', 'border-orange-700', 'text-white'],
-  green: ['bg-green-600', 'border-green-600', 'text-white'],
-  lime: ['bg-lime-500', 'border-lime-500', 'text-gray-900'],
-  purple: ['bg-purple-500', 'border-purple-500', 'text-white'],
-  blue: ['bg-cyan-600', 'border-cyan-600', 'text-white'],
-  gray: ['bg-gray-500', 'border-gray-500', 'text-white'],
-  white: ['bg-white', 'border-white', 'text-gray-700']
-};
-
-export const valueTypeColorMap: Record<string, string> = {
-  flow: 'white',
-  number: 'green',
-  float: 'green',
-  integer: 'lime',
-  boolean: 'red',
-  string: 'purple'
-};
-
-export const categoryColorMap: Record<NodeSpecJSON['category'], color> = {
+export const categoryColorMap: Record<NodeSpecJSON['category'], string> = {
   Event: 'red',
   Logic: 'green',
   Variable: 'purple',

package/src/util/downloadJson.ts

@@ -0,0 +1,18 @@
+/**
+ * Use this on a subscription to the graph:save event to trigger a download of the graph JSON data. This is useful for users who want to keep a local backup of their graphs, or for debugging purposes.
+ * @param filename
+ * @param data
+ */
+export function downloadJson(filename: string, data: unknown) {
+  const blob = new Blob([JSON.stringify(data, null, 2)], {
+    type: 'application/json'
+  });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  URL.revokeObjectURL(url);
+}

package/src/util/extractNodeMetadata.ts

@@ -0,0 +1,16 @@
+import {
+  writeNodeSpecsToJSON,
+  type IRegistry
+} from '@kiberon-labs/behave-graph';
+import type { INodeRegistry } from '../types/NodeMetadata.js';
+
+/**
+ * Extract pure node metadata from a behave-graph registry.
+ * Used by the visual graph editor to initialize a System without execution dependencies.
+ */
+export function extractNodeMetadata(registry: IRegistry): INodeRegistry {
+  return {
+    values: registry.values,
+    specs: writeNodeSpecsToJSON(registry)
+  };
+}

package/src/util/getPickerFilters.ts

@@ -1,6 +1,6 @@
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 import type { Node, OnConnectStartParams } from 'reactflow';
-import type { NodePickerFilters } from '../components/NodePicker.js';
+import type { NodePickerFilters } from '../components/contextMenus/NodePicker.js';
 import { getSocketsByNodeTypeAndHandleType } from './getSocketsByNodeTypeAndHandleType.js';
 
 export const getNodePickerFilters = (

package/src/util/isBehaveNode.ts

@@ -0,0 +1,6 @@
+import type { IBehaveNode } from '@/types/nodes';
+import type { Node } from 'reactflow';
+
+export function isBehaveNode(node: Node): node is IBehaveNode {
+  return typeof node.type === 'string' && node.type.startsWith('behaveNode');
+}

package/src/util/isValidConnection.ts

@@ -1,40 +1,56 @@
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 import type { Connection, ReactFlowInstance } from 'reactflow';
-
 import { getSocketsByNodeTypeAndHandleType } from './getSocketsByNodeTypeAndHandleType.js';
 import { isHandleConnected } from './isHandleConnected.js';
+import { mergeSockets } from './mergeSockets.js';
+import { resolveConverter } from './autoConvert.js';
+import type { ConversionRule } from '@/store/conversions';
+import type { IBehaveNode } from '@/types/nodes.js';
 
 export const isValidConnection = (
   connection: Connection,
   instance: ReactFlowInstance,
-  specJSON: NodeSpecJSON[]
+  specJSON: NodeSpecJSON[],
+  options?: { autoConvert?: boolean; conversions?: ConversionRule[] }
 ) => {
   if (connection.source === null || connection.target === null) return false;
 
-  const sourceNode = instance.getNode(connection.source);
-  const targetNode = instance.getNode(connection.target);
+  const sourceNode = instance.getNode(connection.source) as IBehaveNode;
+  const targetNode = instance.getNode(connection.target) as IBehaveNode;
   const edges = instance.getEdges();
 
   if (sourceNode === undefined || targetNode === undefined) return false;
 
-  const sourceSockets = getSocketsByNodeTypeAndHandleType(
+  // Get spec sockets
+  const sourceSpecSockets = getSocketsByNodeTypeAndHandleType(
     specJSON,
-    sourceNode.type,
+    sourceNode.data?.type,
     'source'
   );
-
-  const sourceSocket = sourceSockets?.find(
-    (socket) => socket.name === connection.sourceHandle
-  );
-
-  const targetSockets = getSocketsByNodeTypeAndHandleType(
+  const targetSpecSockets = getSocketsByNodeTypeAndHandleType(
     specJSON,
-    targetNode.type,
+    targetNode.data?.type,
     'target'
   );
 
-  const targetSocket = targetSockets?.find(
-    (socket) => socket.name === connection.targetHandle
+  if (sourceSpecSockets === undefined || targetSpecSockets === undefined)
+    return false;
+
+  // Merge spec sockets with dynamic ports
+  const sourceSockets = mergeSockets(
+    sourceSpecSockets,
+    sourceNode.data.dynamicPorts?.outputs
+  );
+  const targetSockets = mergeSockets(
+    targetSpecSockets,
+    targetNode.data.dynamicPorts?.inputs
+  );
+
+  const sourceSocket = sourceSockets.find(
+    (s) => s.name === connection.sourceHandle
+  );
+  const targetSocket = targetSockets.find(
+    (s) => s.name === connection.targetHandle
   );
 
   if (sourceSocket === undefined || targetSocket === undefined) return false;
@@ -42,10 +58,28 @@ export const isValidConnection = (
   // only flow sockets can have two inputs
   if (
     targetSocket.valueType !== 'flow' &&
-    isHandleConnected(edges, targetNode.id, targetSocket.name, 'target')
+    isHandleConnected(edges, targetNode.id, targetSocket.key, 'target')
   ) {
     return false;
   }
 
-  return sourceSocket.valueType === targetSocket.valueType;
+  if (sourceSocket.valueType === targetSocket.valueType) return true;
+
+  // Different value types are allowed when auto-convert can splice in a
+  // converter node (handled on connect).
+  if (
+    options?.autoConvert &&
+    sourceSocket.valueType !== 'flow' &&
+    targetSocket.valueType !== 'flow' &&
+    resolveConverter(
+      specJSON,
+      sourceSocket.valueType,
+      targetSocket.valueType,
+      options.conversions
+    )
+  ) {
+    return true;
+  }
+
+  return false;
 };

package/src/util/mergeSockets.ts

@@ -0,0 +1,29 @@
+import type {
+  InputSocketSpecJSON,
+  OutputSocketSpecJSON
+} from '@kiberon-labs/behave-graph';
+import type { SocketBase } from '../types.js';
+
+type SpecSocket = InputSocketSpecJSON | OutputSocketSpecJSON;
+
+function toSocketBase(socket: SpecSocket): SocketBase {
+  return { ...socket, key: socket.name };
+}
+
+/**
+ * Merges spec sockets with dynamic port overrides.
+ * Spec sockets use 'name' as identifier, dynamic ports use 'key'.
+ * Dynamic ports can override spec sockets when their key matches the spec socket's name.
+ */
+export function mergeSockets(
+  specSockets: SpecSocket[],
+  dynamicPorts?: SocketBase[]
+): SocketBase[] {
+  const socketsMap = new Map(specSockets.map((s) => [s.name, toSocketBase(s)]));
+
+  if (dynamicPorts) {
+    dynamicPorts.forEach((s) => socketsMap.set(s.key, s));
+  }
+
+  return Array.from(socketsMap.values());
+}

package/src/util/serializeVariables.ts

@@ -0,0 +1,66 @@
+/**
+ * Serialize variables to JSON using pure metadata
+ * This replaces the need for WriteVariablesToJSON from @kiberon-labs/behave-graph
+ */
+
+import type { INodeRegistry } from '../types/NodeMetadata';
+
+export interface VariableJSON {
+  id: string;
+  name: string;
+  valueTypeName: string;
+  initialValue: any;
+  label?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface Variable {
+  id: string;
+  name: string;
+  valueTypeName: string;
+  initialValue: any;
+  label?: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Serialize a single variable to JSON
+ */
+export function serializeVariable(
+  variable: Variable,
+  registry: INodeRegistry
+): VariableJSON {
+  const valueType = registry.values[variable.valueTypeName];
+  const serializedValue = valueType?.serialize
+    ? valueType.serialize(variable.initialValue)
+    : variable.initialValue;
+
+  const variableJson: VariableJSON = {
+    id: variable.id,
+    name: variable.name,
+    valueTypeName: variable.valueTypeName,
+    initialValue: serializedValue
+  };
+
+  if (variable.label && variable.label.length > 0) {
+    variableJson.label = variable.label;
+  }
+
+  if (variable.metadata && Object.keys(variable.metadata).length > 0) {
+    variableJson.metadata = variable.metadata;
+  }
+
+  return variableJson;
+}
+
+/**
+ * Serialize multiple variables to JSON array
+ */
+export function writeVariablesToJSON(
+  registry: INodeRegistry,
+  variables: Record<string, Variable>
+): VariableJSON[] {
+  return Object.values(variables).map((variable) =>
+    serializeVariable(variable, registry)
+  );
+}

package/src/util/sockets.ts

@@ -0,0 +1,43 @@
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+
+import type { SocketBase, DynamicPorts } from '../types.js';
+import { mergeSockets } from './mergeSockets.js';
+
+const getPairs = <T, U>(arr1: T[], arr2: U[]) => {
+  const max = Math.max(arr1.length, arr2.length);
+  const pairs = [];
+  for (let i = 0; i < max; i++) {
+    const pair: [T | undefined, U | undefined] = [arr1[i], arr2[i]];
+    pairs.push(pair);
+  }
+  return pairs;
+};
+
+type Configuration = Record<string, any>;
+
+export function configureSockets(
+  config: Configuration,
+  spec: NodeSpecJSON,
+  ports?: DynamicPorts
+) {
+  const configInputs = config?.socketInputs || [];
+
+  const configOutputs = config?.socketOutputs || [];
+
+  // Merge spec sockets with ports overrides (specifics can override subset of sockets)
+  const baseInputs = mergeSockets(spec.inputs, ports?.inputs);
+  const baseOutputs = mergeSockets(spec.outputs, ports?.outputs);
+
+  const inputs: SocketBase[] = [...baseInputs, ...configInputs];
+  const outputs: SocketBase[] = [...baseOutputs, ...configOutputs];
+
+  const flowInputs = inputs.filter((input) => input.valueType === 'flow');
+  const flowOutputs = outputs.filter((output) => output.valueType === 'flow');
+
+  const valueInputs = inputs.filter((input) => input.valueType !== 'flow');
+  const valueOutputs = outputs.filter((output) => output.valueType !== 'flow');
+
+  const pairs = getPairs(flowInputs, [...flowOutputs, ...valueOutputs]);
+
+  return { pairs, valueInputs, valueOutputs, flowInputs, flowOutputs };
+}