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

package/src/index.ts

@@ -1,27 +1,24 @@
-export * from './components/modals/ClearModal.js';
-export * from './components/modals/HelpModal.js';
-export * from './components/modals/LoadModal.js';
-export * from './components/modals/Modal.js';
-export * from './components/modals/SaveModal.js';
-export * from './components/Controls.js';
-
-export * from './components/AutoSizeInput.js';
-export * from './components/Controls.js';
-export * from './components/InputSocket.js';
-export * from './components/Node.js';
+import './index.css';
+
+export * from './components/sockets/input/index.js';
+export * from './components/nodes/behave/Node.js';
 export * from './components/Flow.js';
-export * from './components/NodeContainer.js';
-export * from './components/NodePicker.js';
-export * from './components/OutputSocket.js';
+export * from './components/FloatingToolbar/index.js';
+export * from './components/nodes/behave/NodeContainer.js';
+export * from './components/contextMenus/NodePicker.js';
+export * from './components/contextMenus/NodePicker.js';
+export * from './components/sockets/output/index.js';
+export * from './components/menubar/menuItem';
+// Presentational panel primitives, exported so plugin packages (e.g. the AI
+// nodes package's conversation panel) can author panels that match the editor.
+export * from './components/panels/base/index.js';
+export * from './components/primitives/icon.js';
 
+//================== Reusable hooks =================//
 export * from './hooks/useChangeNodeData.js';
 export * from './hooks/useOnPressKey.js';
 export * from './hooks/useFlowHandlers.js';
-export * from './hooks/useGraphRunner.js';
 export * from './hooks/useBehaveGraphFlow.js';
-export * from './hooks/useNodeSpecJson.js';
-export * from './hooks/useCustomNodeTypes.js';
-export * from './hooks/useMergeMap.js';
 
 export * from './transformers/behaveToFlow.js';
 export * from './transformers/flowToBehave.js';
@@ -35,3 +32,41 @@ export * from './util/hasPositionMetaData.js';
 export * from './util/isHandleConnected.js';
 export * from './util/isValidConnection.js';
 export * from './util/sleep.js';
+export * from './util/serializeVariables.js';
+export * from './util/downloadJson';
+
+// New metadata types and utilities (v2.0)
+export * from './types/NodeMetadata.js';
+export * from './util/extractNodeMetadata.js';
+
+export * from './system/index.js';
+export * from './components/layoutController/index.js';
+
+export * from './store/controls';
+export * from './store/specific';
+export * from './store/socketGenerator';
+export * from './store/documentation';
+export * from './store/toolbar';
+export * from './store/conversions';
+export * from './store/commands';
+export * from './store/contextMenu';
+export * from './store/settingsSchema';
+export { registerDefaults } from './generators/registerDefaults';
+
+export * from './annotations/index';
+
+export * from './types/graph';
+
+//================== Plugins =================//
+export * from './system/plugin';
+export * from './manifest/index.js';
+export * from './plugin/docs/index.js';
+export * from './plugin/alignment/index.js';
+export * from './plugin/layout/index.js';
+export * from './plugin/notes/index.js';
+export * from './plugin/autosave/index.js';
+export * from './plugin/kitchen-sink/index.js';
+export * from './plugin/graphrunner/index.js';
+export * from './plugin/graphrunner-local/index.js';
+export * from './plugin/graphrunner-webworker/index.js';
+export * from './plugin/realtime/realtimeRunner.js';

package/src/manifest/contributionRegistry.ts

@@ -0,0 +1,93 @@
+import type { FC } from 'react';
+import type { TabData } from 'rc-dock';
+import {
+  ContributionKind,
+  type ContributionSpec
+} from '@kiberon-labs/behave-graph';
+import type { System } from '@/system/system';
+import type { ControlProps } from '@/store/controls';
+import type { Specific } from '@/store/specific';
+import type { SocketGenerator } from '@/store/socketGenerator';
+import type { ConversionRule } from '@/store/conversions';
+import type { Command } from '@/store/commands';
+import type { ContextMenuItem } from '@/store/contextMenu';
+import type { ValueTypeMetadata } from '@/types/NodeMetadata';
+
+/**
+ * Registers a single resolved contribution into the right editor store. `value`
+ * is whatever the host's resolver loaded for the contribution's `export` (its
+ * concrete shape depends on the kind).
+ */
+export type ContributionApplier = (
+  system: System,
+  contribution: ContributionSpec,
+  value: unknown
+) => void;
+
+/** Dispatch table mapping each {@link ContributionKind} to its store action. */
+export const contributionAppliers: Record<string, ContributionApplier> = {
+  [ContributionKind.Control]: (system, c, value) => {
+    const name = c.bind?.controlName ?? c.bind?.valueType;
+    if (!name) {
+      throw new Error(
+        `control contribution '${c.id}' needs bind.controlName (or bind.valueType)`
+      );
+    }
+    system.controlStore
+      .getState()
+      .registerControl(name, value as FC<ControlProps>);
+  },
+
+  [ContributionKind.Specific]: (system, _c, value) => {
+    system.specificStore.getState().registerSpecific(value as Specific);
+  },
+
+  [ContributionKind.Panel]: (system, c, value) => {
+    // A panel resolves to a tab loader `() => TabData`, registered under the
+    // contribution id (the tab id the host opens).
+    system.tabLoader.register(c.id, value as () => TabData);
+  },
+
+  [ContributionKind.SocketGenerator]: (system, _c, value) => {
+    system.socketGeneratorStore
+      .getState()
+      .registerGenerator(value as SocketGenerator);
+  },
+
+  [ContributionKind.Conversion]: (system, _c, value) => {
+    system.conversionStore
+      .getState()
+      .registerConversion(value as ConversionRule);
+  },
+
+  [ContributionKind.Command]: (system, _c, value) => {
+    system.commandStore.getState().register(value as Command);
+  },
+
+  [ContributionKind.ContextMenu]: (system, _c, value) => {
+    system.contextMenuStore.getState().register(value as ContextMenuItem);
+  },
+
+  [ContributionKind.ValueType]: (system, c, value) => {
+    // Replaces the pass-through value type with the real, function-bearing one.
+    const vt = value as ValueTypeMetadata;
+    const name = c.bind?.valueType ?? vt.name;
+    system.registry.getState().updateValues({ [name]: { ...vt, name } });
+  }
+};
+
+/** Apply a resolved contribution, warning (not throwing) on an unknown kind. */
+export function applyContribution(
+  system: System,
+  contribution: ContributionSpec,
+  value: unknown
+): void {
+  const applier = contributionAppliers[contribution.kind];
+  if (!applier) {
+    console.warn(
+      `[manifest] no applier for contribution kind '${contribution.kind}' (${contribution.id})`
+    );
+    return;
+  }
+  applier(system, contribution, value);
+}

package/src/manifest/index.ts

@@ -0,0 +1,4 @@
+export * from './passthroughValueType';
+export * from './contributionRegistry';
+export * from './loadManifest';
+export * from './manifestPlugin';

package/src/manifest/loadManifest.ts

@@ -0,0 +1,82 @@
+import type {
+  ContributionSpec,
+  ManifestJSON,
+  PackageRequirement
+} from '@kiberon-labs/behave-graph';
+import type { System } from '@/system/system';
+import type { ValueTypeMetadata } from '@/types/NodeMetadata';
+import { passthroughValueType } from './passthroughValueType';
+import { applyContribution } from './contributionRegistry';
+
+/**
+ * Resolves a contribution's declarative `export` (e.g. `"./ui.js#ImageControl"`)
+ * to its actual value. The host owns this because a bundler must know the
+ * concrete module — so loading code contributions is always host-mediated and
+ * gated behind {@link LoadManifestOptions.trust}.
+ */
+export type ContributionResolver = (
+  contribution: ContributionSpec,
+  manifest: ManifestJSON
+) => unknown | Promise<unknown>;
+
+export type LoadManifestOptions = {
+  /**
+   * Gate for executing code contributions. Default `false`: only nodes and
+   * pass-through value types load (no package code runs). Set true together
+   * with {@link LoadManifestOptions.resolve} once the package is trusted.
+   */
+  trust?: boolean;
+  /** Required to load contributions; without it only the static parts load. */
+  resolve?: ContributionResolver;
+  /**
+   * Called for each declared host requirement (persistent backend, config,
+   * ...). Lets the host surface a badge or run a backend. No code executes here.
+   */
+  onRequirement?: (
+    requirement: PackageRequirement,
+    manifest: ManifestJSON
+  ) => void;
+};
+
+/**
+ * Load a package manifest into the editor.
+ *
+ * Always (no code execution): registers the node specs and pass-through value
+ * types, so the palette is fully populated from JSON alone. Only under explicit
+ * `trust` + a `resolve`r does it import and register the package's code
+ * contributions. Declared host requirements are surfaced via `onRequirement`.
+ */
+export async function loadManifest(
+  system: System,
+  manifest: ManifestJSON,
+  options: LoadManifestOptions = {}
+): Promise<void> {
+  // 1. Static: nodes + pass-through value types. No package code runs.
+  const values: Record<string, ValueTypeMetadata> = {};
+  for (const value of manifest.values) {
+    values[value.name] = passthroughValueType(value);
+  }
+  system.registry.getState().updateRegistry({ specs: manifest.nodes, values });
+
+  // 2. Surface host requirements (no code execution).
+  if (options.onRequirement && manifest.requirements) {
+    for (const requirement of manifest.requirements) {
+      options.onRequirement(requirement, manifest);
+    }
+  }
+
+  // 3. Code contributions — only when explicitly trusted and a resolver exists.
+  if (!options.trust || !options.resolve) return;
+  for (const contribution of manifest.contributions) {
+    try {
+      const value = await options.resolve(contribution, manifest);
+      if (value === null || value === undefined) continue;
+      applyContribution(system, contribution, value);
+    } catch (err) {
+      console.error(
+        `[manifest] failed to load contribution '${contribution.id}'`,
+        err
+      );
+    }
+  }
+}

package/src/manifest/manifestPlugin.ts

@@ -0,0 +1,29 @@
+import type { ManifestJSON } from '@kiberon-labs/behave-graph';
+import { plugin } from '@/system/plugin';
+import type { System } from '@/system/system';
+import { loadManifest, type LoadManifestOptions } from './loadManifest';
+
+export interface ManifestPluginOptions extends LoadManifestOptions {
+  /** Manifests to load, in order (later ones override earlier node types). */
+  manifests: ManifestJSON[];
+}
+
+export async function manifestPluginLoader(
+  system: System,
+  options: ManifestPluginOptions
+): Promise<void> {
+  const { manifests, ...loadOptions } = options;
+  for (const manifest of manifests) {
+    await loadManifest(system, manifest, loadOptions);
+  }
+}
+
+/**
+ * Register one or more package manifests as a single plugin. The static parts
+ * (nodes + value types) always load; code contributions load only under
+ * `trust` + `resolve` (see {@link LoadManifestOptions}).
+ */
+export const manifestPlugin = plugin<ManifestPluginOptions>(
+  manifestPluginLoader,
+  { name: 'manifest' }
+);

package/src/manifest/passthroughValueType.ts

@@ -0,0 +1,40 @@
+import type { ValueTypeSpecJSON } from '@kiberon-labs/behave-graph';
+import type { ValueTypeMetadata } from '@/types/NodeMetadata';
+
+const clone = <T>(value: T): T => {
+  if (value === null || typeof value !== 'object') return value;
+  try {
+    return structuredClone(value);
+  } catch {
+    return JSON.parse(JSON.stringify(value)) as T;
+  }
+};
+
+/**
+ * Build a function-bearing {@link ValueTypeMetadata} from a function-free
+ * {@link ValueTypeSpecJSON} carried in a manifest.
+ *
+ * The editor calls `creator`/`serialize`/`deserialize` at author time (creating
+ * variables, editing events, deserializing a graph's variables). A manifest can
+ * only ship JSON, so we synthesise pass-through behaviour: the value is already
+ * its own JSON form, so (de)serialize are identity and `creator` returns a clone
+ * of the declared default. This keeps every existing UI call site working with
+ * **zero code execution**. When the package is later trusted-loaded, a
+ * `valueType` contribution can replace this with the real implementation.
+ */
+export function passthroughValueType(
+  spec: ValueTypeSpecJSON
+): ValueTypeMetadata {
+  return {
+    name: spec.name,
+    creator: () =>
+      spec.defaultJSON === null || spec.defaultJSON === undefined
+        ? undefined
+        : clone(spec.defaultJSON),
+    serialize: (value: unknown) => value,
+    deserialize: (value: unknown) => value,
+    clone: (value: unknown) => clone(value),
+    equals: (a: unknown, b: unknown) =>
+      a === b || JSON.stringify(a) === JSON.stringify(b)
+  };
+}

package/src/plugin/alignment/index.ts

@@ -0,0 +1,91 @@
+import { align, distribute, ALIGNMENT } from '@/components/panels/alignment';
+import type { GraphSession } from '@/system/graphSession';
+import type { Node } from 'reactflow';
+import { plugin } from '@/system/plugin';
+import type { System } from '@/system/system';
+import { pinned } from '@/annotations';
+
+const partitionSelectedNodes = (nodes: Node[]) => {
+  return nodes.reduce(
+    (acc, node) => {
+      if (node.selected && !node.data?.metadata?.[pinned]) {
+        acc.selectedNodes.push(node);
+      } else {
+        acc.unselectedNodes.push(node);
+      }
+      return acc;
+    },
+    {
+      selectedNodes: [] as Node[],
+      unselectedNodes: [] as Node[]
+    }
+  );
+};
+
+export type AlignmentAxis = 'x' | 'y';
+export type AlignmentType = 'start' | 'center' | 'end';
+
+declare module '@/system/system' {
+  interface GraphPubSys {
+    'alignment:align': {
+      type: AlignmentType;
+      axis: AlignmentAxis;
+    };
+    'alignment:distribute': {
+      type: AlignmentType;
+      axis: AlignmentAxis;
+    };
+  }
+}
+
+export const setupSessionActions = (session: GraphSession) => {
+  // Subscribe to alignment events
+  session.pubsub.subscribe('alignment:align', (_, data) => {
+    const { nodes, setNodes } = session.nodeStore.getState();
+    const { selectedNodes, unselectedNodes } = partitionSelectedNodes(nodes);
+
+    const alignmentType =
+      data.type === 'start'
+        ? ALIGNMENT.START
+        : data.type === 'center'
+          ? ALIGNMENT.CENTER
+          : ALIGNMENT.END;
+
+    align(alignmentType, data.axis)(selectedNodes);
+    setNodes([...unselectedNodes, ...selectedNodes]);
+  });
+
+  // Subscribe to distribution events
+  session.pubsub.subscribe('alignment:distribute', (_, data) => {
+    const { nodes, setNodes } = session.nodeStore.getState();
+    const { selectedNodes, unselectedNodes } = partitionSelectedNodes(nodes);
+
+    const alignmentType =
+      data.type === 'start'
+        ? ALIGNMENT.START
+        : data.type === 'center'
+          ? ALIGNMENT.CENTER
+          : ALIGNMENT.END;
+
+    distribute(alignmentType, data.axis)(selectedNodes);
+    setNodes([...unselectedNodes, ...selectedNodes]);
+  });
+};
+
+/**
+ * Adds node alignment + distribution to the editor. The behaviour is opt-in: it
+ * subscribes each graph's pubsub (via a session extension, so it covers graphs
+ * already open and any opened later) to the `alignment:align` /
+ * `alignment:distribute` events the FloatingToolbar and Alignment panel publish.
+ *
+ * Register it directly or via the kitchen-sink plugin. Without it those events
+ * have no subscriber and the alignment controls simply no-op.
+ */
+export const alignmentPlugin = plugin(
+  (system: System) => {
+    system.registerSessionExtension((session) => {
+      setupSessionActions(session);
+    });
+  },
+  { name: 'alignment' }
+);