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

package/src/plugin/realtime/realtimeRunner.ts

@@ -425,10 +425,46 @@ export class RealtimeRunner {
     if (this.annotatedOutputNodeIds.length === 0) return;
 
     for (const nodeId of this.annotatedOutputNodeIds) {
-      const node = this.engine.nodes?.[nodeId];
-      if (!node) continue;
-      if (!isFunctionNode(node)) continue;
+      await this.evaluateNodeForPreview(nodeId);
+    }
+  }
+
+  /**
+   * Evaluate every node that a UI consumer is actively watching.
+   *
+   * Pure function graphs (e.g. the image nodes) never run during
+   * `executeAllSync()` because nothing pushes a flow fiber through them. They
+   * are normally pulled lazily when a downstream flow/event node reads their
+   * value. In the editor preview there is no such consumer, so the act of a
+   * component calling `watchNodeOutput()` is what drives evaluation: we resolve
+   * the node's upstream function graph and execute the node itself so its
+   * sockets hold a fresh value for `publishWatchedOutputs()` to read.
+   *
+   * This intentionally does not depend on the `ui.realtime` annotation , any
+   * watched output is evaluated.
+   */
+  private async recalculateWatchedOutputs(): Promise<void> {
+    if (!this.engine) return;
+    if (this.watched.size === 0) return;
+
+    for (const nodeId of this.watched.keys()) {
+      await this.evaluateNodeForPreview(nodeId);
+    }
+  }
+
+  /**
+   * Resolve a single function node's inputs (recursively executing its upstream
+   * function graph) and execute it. Non-function nodes keep whatever value their
+   * last real execution produced. Resilient: a failure on one node is logged and
+   * does not abort evaluation of the others.
+   */
+  private async evaluateNodeForPreview(nodeId: string): Promise<void> {
+    if (!this.engine) return;
+    const node = this.engine.nodes?.[nodeId];
+    if (!node) return;
+    if (!isFunctionNode(node)) return;
 
+    try {
       let executionSteps = 0;
       for (const inputSocket of node.inputs) {
         executionSteps += await this.resolveSocketValueForPreview(inputSocket);
@@ -440,6 +476,11 @@ export class RealtimeRunner {
       this.engine.onNodeExecutionEnd.emit(node);
 
       this.engine.executionSteps += executionSteps;
+    } catch (err) {
+      console.error(
+        `RealtimeRunner: failed to evaluate watched node ${nodeId}:`,
+        err
+      );
     }
   }
 
@@ -450,7 +491,12 @@ export class RealtimeRunner {
     const nodes = this.system.nodeStore.getState().nodes;
     const edges = this.system.edgeStore.getState().edges;
 
-    const rawGraphJson = flowToBehave(this.system, nodes, edges, specJson);
+    const rawGraphJson = flowToBehave(
+      this.system.session!,
+      nodes,
+      edges,
+      specJson
+    );
     const graphWithAnnotations = this.mergeNodeAnnotationsIntoMetadata(
       rawGraphJson,
       nodes
@@ -540,6 +586,10 @@ export class RealtimeRunner {
       // Recalculate annotated output nodes to force evaluation of upstream function graphs.
       await this.recalculateAnnotatedOutputNodes();
 
+      // Pull every watched output (e.g. live image node previews) so pure
+      // function graphs are evaluated even without a flow consumer.
+      await this.recalculateWatchedOutputs();
+
       this.publishWatchedOutputs();
     } catch (err) {
       // Keep preview runner resilient; don't crash the editor.
@@ -562,6 +612,10 @@ export class RealtimeRunner {
       // Recalculate annotated output nodes to force evaluation of upstream function graphs.
       await this.recalculateAnnotatedOutputNodes();
 
+      // Pull every watched output (e.g. live image node previews) so pure
+      // function graphs are evaluated even without a flow consumer.
+      await this.recalculateWatchedOutputs();
+
       this.publishWatchedOutputs();
     } catch {
       // ignore

package/src/specifics/CustomEventOnTriggeredSpecific.tsx

@@ -5,7 +5,7 @@ import {
   VscodeSingleSelect
 } from '@vscode-elements/react-elements';
 
-import { useSystem } from '@/system/provider';
+import { useGraph } from '@/system/provider';
 import type { SpecificRenderProps } from '@/store/specific';
 
 const NAME = 'customEvent/onTriggered.customEventId';
@@ -21,7 +21,7 @@ export function getCustomEventOnTriggeredSpecific() {
 const CustomEventOnTriggeredSpecific: React.FC<SpecificRenderProps> = ({
   node
 }) => {
-  const system = useSystem();
+  const system = useGraph();
   const customEvents = useStore(system.eventsStore, (s) => s.customEvents);
 
   const options = useMemo(() => {

package/src/specifics/CustomEventTriggerSpecific.tsx

@@ -5,7 +5,7 @@ import {
   VscodeSingleSelect
 } from '@vscode-elements/react-elements';
 
-import { useSystem } from '@/system/provider';
+import { useGraph } from '@/system/provider';
 import type { SpecificRenderProps } from '@/store/specific';
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 import type { Socket } from '@/types';
@@ -24,7 +24,7 @@ export function getCustomEventTriggerSpecific() {
 const CustomEventTriggerSpecific: React.FC<SpecificRenderProps> = ({
   node
 }) => {
-  const system = useSystem();
+  const system = useGraph();
   const customEvents = useStore(system.eventsStore, (s) => s.customEvents);
 
   const options = useMemo(() => {

package/src/specifics/VariableGetSpecific.tsx

@@ -5,7 +5,7 @@ import {
   VscodeSingleSelect
 } from '@vscode-elements/react-elements';
 
-import { useSystem } from '@/system/provider';
+import { useGraph } from '@/system/provider';
 import type { SpecificRenderProps } from '@/store/specific';
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 
@@ -20,7 +20,7 @@ export function getVariableGetSpecific() {
 }
 
 const VariableGetSpecific: React.FC<SpecificRenderProps> = ({ node }) => {
-  const system = useSystem();
+  const system = useGraph();
   const variables = useStore(system.variableStore, (s) => s.variables);
 
   const options = useMemo(() => {

package/src/specifics/VariableSetSpecific.tsx

@@ -5,7 +5,7 @@ import {
   VscodeSingleSelect
 } from '@vscode-elements/react-elements';
 
-import { useSystem } from '@/system/provider';
+import { useGraph } from '@/system/provider';
 import type { SpecificRenderProps } from '@/store/specific';
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 
@@ -20,7 +20,7 @@ export function getVariableSetSpecific() {
 }
 
 const VariableSetSpecific: React.FC<SpecificRenderProps> = ({ node }) => {
-  const system = useSystem();
+  const system = useGraph();
   const variables = useStore(system.variableStore, (s) => s.variables);
 
   const options = useMemo(() => {

package/src/store/actions.tsx

@@ -1,4 +1,4 @@
-import type { System } from '@/system';
+import type { GraphSession } from '@/system/graphSession';
 import { Graph } from 'graphlib';
 import { create } from 'zustand';
 import copyToClipboard from 'copy-to-clipboard';
@@ -87,7 +87,7 @@ export type ActionStore = {
  * @param sys
  * @returns
  */
-const convertToGraph = (sys: System) => {
+const convertToGraph = (sys: GraphSession) => {
   const nodes = sys.nodeStore.getState().nodes;
   const edges = sys.edgeStore.getState().edges;
 
@@ -119,7 +119,7 @@ const createNodeLookup = (nodes: string[]) => {
   );
 };
 
-const applyFilters = (sys: System, lookup: Record<string, boolean>) => {
+const applyFilters = (sys: GraphSession, lookup: Record<string, boolean>) => {
   sys.nodeStore.getState().setNodes((nodes) => {
     const newNodes = nodes.map((x) => {
       if (!lookup[x.id]) {
@@ -140,13 +140,13 @@ const applyFilters = (sys: System, lookup: Record<string, boolean>) => {
   });
 };
 
-export const actionStoreFactory = (sys: System) =>
+export const actionStoreFactory = (sys: GraphSession) =>
   create<ActionStore>((set, get) => ({
     actions: {
       save: async () => {
         try {
           const uiGraph = buildUIGraphJSON(sys);
-          sys.pubsub.publish('graph:saved', uiGraph);
+          sys.editor.pubsub.publish('graph:saved', uiGraph);
           return uiGraph;
         } catch (err) {
           sys.notifications.error('Failed to save graph');

package/src/store/commands.ts

@@ -0,0 +1,278 @@
+import { createStore, type StoreApi } from 'zustand';
+import type { EdgeChange, XYPosition } from 'reactflow';
+import type { System } from '@/system/system';
+import type { GraphSession } from '@/system/graphSession';
+
+/**
+ * Context handed to a command when it runs. Carries the editor + the graph it
+ * acts on, plus optional targets so the same command works from a context menu,
+ * a hotkey, or a toolbar button.
+ */
+export type CommandContext = {
+  editor: System;
+  session: GraphSession;
+  nodeId?: string;
+  edgeId?: string;
+  sourceId?: string;
+  targetId?: string;
+  position?: XYPosition;
+};
+
+/**
+ * A named, dispatchable action. Decouples *what* (id) from *how* (run), so UI
+ * surfaces (context menus, hotkeys, menubar, toolbar) reference commands by id
+ * instead of reaching into concrete stores.
+ */
+export type Command = {
+  id: string;
+  title?: string;
+  /** When present and false, the command is treated as unavailable. */
+  isEnabled?: (ctx: CommandContext) => boolean;
+  run: (ctx: CommandContext) => void | Promise<void>;
+};
+
+export type CommandStore = {
+  commands: Map<string, Command>;
+  /** Register (or replace) a command. Returns an unregister disposer. */
+  register: (command: Command) => () => void;
+  unregister: (id: string) => void;
+  get: (id: string) => Command | undefined;
+  list: () => Command[];
+  /** Run a command by id; no-ops (with a warning) if unknown or disabled. */
+  run: (id: string, ctx: CommandContext) => void | Promise<void>;
+};
+
+export const commandStoreFactory = (): StoreApi<CommandStore> =>
+  createStore<CommandStore>((set, get) => ({
+    commands: new Map(),
+    register: (command) => {
+      set((s) => {
+        const next = new Map(s.commands);
+        next.set(command.id, command);
+        return { commands: next };
+      });
+      return () => get().unregister(command.id);
+    },
+    unregister: (id) =>
+      set((s) => {
+        if (!s.commands.has(id)) return s;
+        const next = new Map(s.commands);
+        next.delete(id);
+        return { commands: next };
+      }),
+    get: (id) => get().commands.get(id),
+    list: () => Array.from(get().commands.values()),
+    run: (id, ctx) => {
+      const command = get().commands.get(id);
+      if (!command) {
+        console.warn(`[commands] unknown command: ${id}`);
+        return;
+      }
+      if (command.isEnabled && !command.isEnabled(ctx)) return;
+      return command.run(ctx);
+    }
+  }));
+
+// --- Default graph commands --------------------------------------------------
+// Transitional: these delegate to the per-session action store. As actions are
+// decomposed (a later slice), the logic can move into the command handlers and
+// the action store can shrink.
+
+const actionsOf = (ctx: CommandContext) =>
+  ctx.session.actionStore.getState().actions;
+
+const centerOnNode = (session: GraphSession, nodeId: string): void => {
+  const node = session.nodeStore.getState().nodes.find((n) => n.id === nodeId);
+  if (!node) return;
+  const x = node.position.x + (node.width ?? 0) / 2;
+  const y = node.position.y + (node.height ?? 0) / 2;
+  session.refStore
+    .getState()
+    .getRef('reactflow')
+    ?.setCenter(x, y, { duration: 200, zoom: 1 });
+};
+
+const reactFlowOf = (session: GraphSession) =>
+  session.refStore.getState().getRef('reactflow');
+
+/**
+ * Register the built-in editor commands. Hosts may override any of them by
+ * re-registering with the same id, or add their own.
+ */
+export const registerDefaultCommands = (
+  store: StoreApi<CommandStore>
+): void => {
+  const { register } = store.getState();
+
+  register({
+    id: 'node.focus',
+    title: 'Focus',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).focusNode(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'node.traceUpstream',
+    title: 'Trace Upstream',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).traceUpstream(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'node.traceDownstream',
+    title: 'Trace Downstream',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).traceDownstream(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'trace.reset',
+    title: 'Reset Trace',
+    run: (ctx) => actionsOf(ctx).resetTrace()
+  });
+  register({
+    id: 'node.togglePinned',
+    title: 'Pin / Unpin',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).toggleNodePinned(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'node.toggleHidden',
+    title: 'Hide / Show',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).toggleNodeHidden(ctx.nodeId);
+    }
+  });
+
+  register({
+    id: 'edge.findSource',
+    title: 'Find Source',
+    run: (ctx) => {
+      if (ctx.sourceId) centerOnNode(ctx.session, ctx.sourceId);
+    }
+  });
+  register({
+    id: 'edge.findTarget',
+    title: 'Find Target',
+    run: (ctx) => {
+      if (ctx.targetId) centerOnNode(ctx.session, ctx.targetId);
+    }
+  });
+  register({
+    id: 'edge.delete',
+    title: 'Delete',
+    run: (ctx) => {
+      if (!ctx.edgeId) return;
+      const change: EdgeChange = { id: ctx.edgeId, type: 'remove' };
+      ctx.session.edgeStore.getState().applyEdgeChanges([change]);
+    }
+  });
+
+  register({
+    id: 'selection.copy',
+    title: 'Copy',
+    run: (ctx) => actionsOf(ctx).copySelectionToClipboard()
+  });
+  register({
+    id: 'selection.paste',
+    title: 'Paste',
+    run: (ctx) => actionsOf(ctx).pasteFromClipboard()
+  });
+  register({
+    id: 'selection.group',
+    title: 'Group',
+    run: (ctx) => actionsOf(ctx).groupNodes()
+  });
+  register({
+    id: 'selection.selectAll',
+    title: 'Select All',
+    run: (ctx) =>
+      ctx.session.nodeStore
+        .getState()
+        .setNodes((nodes) => nodes.map((n) => ({ ...n, selected: true })))
+  });
+
+  // Editor-level
+  register({
+    id: 'editor.save',
+    title: 'Save Graph',
+    run: (ctx) => {
+      void actionsOf(ctx).save();
+    }
+  });
+  register({
+    id: 'editor.undo',
+    title: 'Undo',
+    run: (ctx) => ctx.session.undoManager.undo()
+  });
+  register({
+    id: 'editor.redo',
+    title: 'Redo',
+    run: (ctx) => ctx.session.undoManager.redo()
+  });
+  register({
+    id: 'editor.find',
+    title: 'Find',
+    run: (ctx) => ctx.editor.tabStore.getState().openTab('find')
+  });
+  // `editor.autoLayout` is contributed by the optional layout plugin
+  // (`@/plugin/layout`), which owns the heavy elkjs/dagre dependencies. When
+  // that plugin is not registered the command is simply unavailable and the
+  // bound hotkey no-ops.
+
+  // View
+  register({
+    id: 'view.fit',
+    title: 'Fit View',
+    run: (ctx) => {
+      reactFlowOf(ctx.session)?.fitView({
+        padding: 0.2,
+        includeHiddenNodes: true
+      });
+    }
+  });
+  register({
+    id: 'view.zoomIn',
+    title: 'Zoom In',
+    run: (ctx) => reactFlowOf(ctx.session)?.zoomIn({ duration: 300 })
+  });
+  register({
+    id: 'view.zoomOut',
+    title: 'Zoom Out',
+    run: (ctx) => reactFlowOf(ctx.session)?.zoomOut({ duration: 300 })
+  });
+  register({
+    id: 'view.zoomReset',
+    title: 'Reset Zoom',
+    run: (ctx) => {
+      const rf = reactFlowOf(ctx.session);
+      if (!rf) return;
+      rf.setViewport({ ...rf.getViewport(), zoom: 1 });
+    }
+  });
+  register({
+    id: 'view.toggleGrid',
+    title: 'Toggle Grid',
+    run: (ctx) => {
+      const s = ctx.editor.systemSettings.getState();
+      s.setShowGrid(!s.showGrid);
+    }
+  });
+  register({
+    id: 'view.toggleMinimap',
+    title: 'Toggle Minimap',
+    run: (ctx) => {
+      const s = ctx.editor.systemSettings.getState();
+      s.setShowMinimap(!s.showMinimap);
+    }
+  });
+  register({
+    id: 'view.toggleSnapGrid',
+    title: 'Toggle Snap to Grid',
+    run: (ctx) => {
+      const s = ctx.editor.systemSettings.getState();
+      s.setSnapGrid(!s.snapGrid);
+    }
+  });
+};

package/src/store/contextMenu.ts

@@ -0,0 +1,192 @@
+import { createStore, type StoreApi } from 'zustand';
+import { hidden, pinned } from '@/annotations';
+import { isBehaveNode } from '@/util/isBehaveNode';
+import type { CommandContext } from './commands';
+
+/** Which canvas target a context-menu item applies to. */
+export type ContextMenuTarget = 'node' | 'edge' | 'selection' | 'pane';
+
+/**
+ * A registrable context-menu entry. Items dispatch either a registered command
+ * (`commandId`) or an inline `onSelect`. `group` controls separator placement;
+ * `order` controls position within a target. `when` hides the item dynamically.
+ */
+export type ContextMenuItem = {
+  id: string;
+  target: ContextMenuTarget;
+  /** Static text, or a function for state-dependent labels (e.g. Pin/Unpin). */
+  label: string | ((ctx: CommandContext) => string);
+  keybinding?: string;
+  /** Ascending sort within the target. */
+  order?: number;
+  /** Items with different adjacent groups get a separator between them. */
+  group?: string | number;
+  when?: (ctx: CommandContext) => boolean;
+  /** Dispatch a registered command by id. */
+  commandId?: string;
+  /** Or run inline (takes precedence over commandId). */
+  onSelect?: (ctx: CommandContext) => void;
+};
+
+export type ContextMenuStore = {
+  items: ContextMenuItem[];
+  /** Register (or replace by id) an item. Returns an unregister disposer. */
+  register: (item: ContextMenuItem) => () => void;
+  unregister: (id: string) => void;
+  /** Items for a target, sorted by `order`. Filtering by `when` is the caller's. */
+  getItems: (target: ContextMenuTarget) => ContextMenuItem[];
+};
+
+export const contextMenuStoreFactory = (): StoreApi<ContextMenuStore> =>
+  createStore<ContextMenuStore>((set, get) => ({
+    items: [],
+    register: (item) => {
+      set((s) => ({
+        items: [...s.items.filter((i) => i.id !== item.id), item]
+      }));
+      return () => get().unregister(item.id);
+    },
+    unregister: (id) =>
+      set((s) => ({ items: s.items.filter((i) => i.id !== id) })),
+    getItems: (target) =>
+      get()
+        .items.filter((i) => i.target === target)
+        .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  }));
+
+// --- Default context menus ---------------------------------------------------
+
+const nodeAt = (ctx: CommandContext) =>
+  ctx.session.nodeStore.getState().nodes.find((n) => n.id === ctx.nodeId);
+
+const nodeFlag = (ctx: CommandContext, key: string): boolean => {
+  const node = nodeAt(ctx);
+  return node && 'data' in node
+    ? Boolean((node.data.annotations as Record<string, unknown>)?.[key])
+    : false;
+};
+
+// The default node items only make sense on behave nodes; presentational node
+// types (notes, groups, ...) register their own `when`-scoped items instead.
+const isBehaveTarget = (ctx: CommandContext): boolean => {
+  const node = nodeAt(ctx);
+  return node !== undefined && isBehaveNode(node);
+};
+
+/**
+ * Register the built-in context-menu items, dispatching the default commands.
+ * Hosts can add/remove/replace items by id without forking the menu components.
+ */
+export const registerDefaultContextMenu = (
+  store: StoreApi<ContextMenuStore>
+): void => {
+  const { register } = store.getState();
+
+  // Node
+  register({
+    id: 'node.focus',
+    target: 'node',
+    label: 'Focus',
+    order: 10,
+    group: 'focus',
+    when: isBehaveTarget,
+    commandId: 'node.focus'
+  });
+  register({
+    id: 'node.traceUpstream',
+    target: 'node',
+    label: 'Trace Upstream',
+    order: 20,
+    group: 'trace',
+    when: isBehaveTarget,
+    commandId: 'node.traceUpstream'
+  });
+  register({
+    id: 'node.traceDownstream',
+    target: 'node',
+    label: 'Trace Downstream',
+    order: 21,
+    group: 'trace',
+    when: isBehaveTarget,
+    commandId: 'node.traceDownstream'
+  });
+  register({
+    id: 'node.resetTrace',
+    target: 'node',
+    label: 'Reset Trace',
+    order: 30,
+    group: 'reset',
+    when: isBehaveTarget,
+    commandId: 'trace.reset'
+  });
+  register({
+    id: 'node.togglePinned',
+    target: 'node',
+    label: (ctx) => (nodeFlag(ctx, pinned) ? 'Unpin' : 'Pin'),
+    order: 40,
+    group: 'visibility',
+    when: isBehaveTarget,
+    commandId: 'node.togglePinned'
+  });
+  register({
+    id: 'node.toggleHidden',
+    target: 'node',
+    label: (ctx) => (nodeFlag(ctx, hidden) ? 'Show' : 'Hide'),
+    order: 41,
+    group: 'visibility',
+    when: isBehaveTarget,
+    commandId: 'node.toggleHidden'
+  });
+
+  // Edge
+  register({
+    id: 'edge.findSource',
+    target: 'edge',
+    label: 'Find Source',
+    order: 10,
+    group: 'find',
+    commandId: 'edge.findSource'
+  });
+  register({
+    id: 'edge.findTarget',
+    target: 'edge',
+    label: 'Find Target',
+    order: 11,
+    group: 'find',
+    commandId: 'edge.findTarget'
+  });
+  register({
+    id: 'edge.delete',
+    target: 'edge',
+    label: 'Delete',
+    order: 20,
+    group: 'delete',
+    commandId: 'edge.delete'
+  });
+
+  // Selection
+  register({
+    id: 'selection.copy',
+    target: 'selection',
+    label: 'Copy',
+    order: 10,
+    group: 'clipboard',
+    commandId: 'selection.copy'
+  });
+  register({
+    id: 'selection.paste',
+    target: 'selection',
+    label: 'Paste',
+    order: 11,
+    group: 'clipboard',
+    commandId: 'selection.paste'
+  });
+  register({
+    id: 'selection.group',
+    target: 'selection',
+    label: 'Group',
+    order: 20,
+    group: 'group',
+    commandId: 'selection.group'
+  });
+};