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

package/stories/{components/nodes/comment.stories.tsx → plugins/notes.stories.tsx}

@@ -8,54 +8,38 @@ import {
   useNodesState
 } from 'reactflow';
 import { useMemo } from 'react';
-import { useStore } from 'zustand';
 
 import { DefaultSystemProvider } from '~/defaults/defaultStoryProvider';
-import { useSystem } from '@/system/provider';
-import { CommentNode } from '@/components/nodes/comment/comment';
+import { NoteNode, NOTE_NODE_TYPE } from '@/plugin/notes';
 
-function Canvas({ selectedId }: { selectedId?: string }) {
-  const sys = useSystem();
-  const allSpecs = useStore(sys.specStore, (s) => s.specs);
+const DEFAULT_TEXT =
+  '# Heading\n\nA **markdown** note with `code` and:\n\n- a list\n- of items\n\n> and a quote';
 
-  const specDict = useMemo(() => {
-    const dict: Record<string, (typeof allSpecs)[number]> = {};
-    for (const spec of allSpecs) {
-      dict[spec.type] = spec;
-    }
-    return dict;
-  }, [allSpecs]);
+const VIDEO_TEXT =
+  'An embedded video:\n\n<div data-youtube-video><iframe src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"></iframe></div>';
 
+function Canvas({ selectedId, text }: { selectedId?: string; text?: string }) {
   const nodeTypes = useMemo(() => {
     return {
-      comment: CommentNode
+      [NOTE_NODE_TYPE]: NoteNode
     };
-  }, [allSpecs, specDict]);
+  }, []);
 
   const [nodes, , onNodesChange] = useNodesState([
     {
       id: '0',
-      type: 'comment',
+      type: NOTE_NODE_TYPE,
       position: { x: 0, y: 0 },
       selected: selectedId === '0',
+      style: { width: 320, height: 260 },
       data: {
         annotations: {},
-        configuration: {},
-        type: 'lifecycle/onStart',
-        ports: {}
+        text: text ?? DEFAULT_TEXT
       }
     }
   ]);
 
-  const [edges, , onEdgesChange] = useEdgesState([
-    {
-      id: 'e0-1',
-      source: '0',
-      sourceHandle: 'flow',
-      target: '1',
-      targetHandle: 'flow'
-    }
-  ]);
+  const [edges, , onEdgesChange] = useEdgesState([]);
 
   return (
     <div style={{ width: 900, height: 520 }}>
@@ -78,7 +62,7 @@ function Canvas({ selectedId }: { selectedId?: string }) {
 }
 
 const meta: Meta<typeof Canvas> = {
-  title: 'Components/Nodes/Comment',
+  title: 'Plugins/Notes',
   component: Canvas
 };
 
@@ -99,7 +83,17 @@ export const Selected: Story = {
   render: () => (
     <DefaultSystemProvider>
       <ReactFlowProvider>
-        <Canvas selectedId="1" />
+        <Canvas selectedId="0" />
+      </ReactFlowProvider>
+    </DefaultSystemProvider>
+  )
+};
+
+export const WithVideo: Story = {
+  render: () => (
+    <DefaultSystemProvider>
+      <ReactFlowProvider>
+        <Canvas text={VIDEO_TEXT} />
       </ReactFlowProvider>
     </DefaultSystemProvider>
   )

package/tests/autoConvert.test.ts

@@ -0,0 +1,329 @@
+import { describe, it, expect } from 'vitest';
+import type { Node, Connection } from 'reactflow';
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+import {
+  findConverterSpec,
+  resolveConverter,
+  buildConverterInsertion
+} from '../src/util/autoConvert.js';
+
+const specs = [
+  {
+    type: 'src',
+    label: '',
+    category: '',
+    inputs: [],
+    outputs: [{ name: 'out', valueType: 'integer' }]
+  },
+  {
+    type: 'dst',
+    label: '',
+    category: '',
+    inputs: [{ name: 'in', valueType: 'string' }],
+    outputs: []
+  },
+  {
+    type: 'math/toString/integer',
+    label: 'To String',
+    category: 'Logic',
+    inputs: [{ name: 'a', valueType: 'integer' }],
+    outputs: [{ name: 'result', valueType: 'string' }]
+  }
+] as unknown as NodeSpecJSON[];
+
+const node = (id: string, type: string, x: number): Node => ({
+  id,
+  type: 'behaveNode',
+  position: { x, y: 0 },
+  data: { type, configuration: {}, ports: {} } as any
+});
+
+const conn = (
+  source: string,
+  sourceHandle: string,
+  target: string,
+  targetHandle: string
+): Connection => ({ source, sourceHandle, target, targetHandle });
+
+describe('findConverterSpec', () => {
+  it('finds a single-in/single-out converter for the type pair', () => {
+    expect(findConverterSpec(specs, 'integer', 'string')?.type).toBe(
+      'math/toString/integer'
+    );
+  });
+
+  it('ignores nodes that have flow sockets', () => {
+    const flowNode = [
+      {
+        type: 'fn',
+        inputs: [
+          { name: 'flow', valueType: 'flow' },
+          { name: 'a', valueType: 'integer' }
+        ],
+        outputs: [{ name: 'result', valueType: 'string' }]
+      }
+    ] as unknown as NodeSpecJSON[];
+    expect(findConverterSpec(flowNode, 'integer', 'string')).toBeUndefined();
+  });
+
+  it('returns undefined when no converter exists', () => {
+    expect(findConverterSpec(specs, 'string', 'boolean')).toBeUndefined();
+  });
+});
+
+describe('resolveConverter (configurable rules)', () => {
+  const customSpecs = [
+    ...specs,
+    {
+      type: 'custom/intToStr',
+      inputs: [{ name: 'x', valueType: 'integer' }],
+      outputs: [{ name: 'y', valueType: 'string' }]
+    }
+  ] as unknown as NodeSpecJSON[];
+
+  it('prefers a registered custom rule over the spec heuristic', () => {
+    const rules = [
+      { from: 'integer', to: 'string', nodeType: 'custom/intToStr' }
+    ];
+    expect(resolveConverter(customSpecs, 'integer', 'string', rules)).toEqual({
+      nodeType: 'custom/intToStr',
+      inputName: 'x',
+      outputName: 'y'
+    });
+  });
+
+  it('falls back to the spec heuristic when no rule matches', () => {
+    expect(resolveConverter(specs, 'integer', 'string', [])?.nodeType).toBe(
+      'math/toString/integer'
+    );
+  });
+
+  it('honours explicit inputKey/outputKey from the rule', () => {
+    const rules = [
+      {
+        from: 'integer',
+        to: 'string',
+        nodeType: 'whatever',
+        inputKey: 'in',
+        outputKey: 'out'
+      }
+    ];
+    expect(resolveConverter([], 'integer', 'string', rules)).toEqual({
+      nodeType: 'whatever',
+      inputName: 'in',
+      outputName: 'out'
+    });
+  });
+
+  // A converter node with several inputs/outputs (e.g. value + config ports).
+  const multiPortSpecs = [
+    {
+      type: 'multi',
+      inputs: [
+        { name: 'flow', valueType: 'flow' },
+        { name: 'label', valueType: 'string' }, // first non-flow, wrong type
+        { name: 'n', valueType: 'integer' } // the actual source port
+      ],
+      outputs: [
+        { name: 'flag', valueType: 'boolean' }, // first non-flow, wrong type
+        { name: 'text', valueType: 'string' } // the actual target port
+      ]
+    }
+  ] as unknown as NodeSpecJSON[];
+
+  it('resolves a multi-port converter by type when keys are omitted', () => {
+    const rules = [{ from: 'integer', to: 'string', nodeType: 'multi' }];
+    expect(
+      resolveConverter(multiPortSpecs, 'integer', 'string', rules)
+    ).toEqual({ nodeType: 'multi', inputName: 'n', outputName: 'text' });
+  });
+
+  it('honours explicit keys to pick a specific port among several of a type', () => {
+    const twoEachSpecs = [
+      {
+        type: 'multi2',
+        inputs: [
+          { name: 'a', valueType: 'integer' },
+          { name: 'b', valueType: 'integer' }
+        ],
+        outputs: [
+          { name: 'x', valueType: 'string' },
+          { name: 'y', valueType: 'string' }
+        ]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const rules = [
+      {
+        from: 'integer',
+        to: 'string',
+        nodeType: 'multi2',
+        inputKey: 'b',
+        outputKey: 'y'
+      }
+    ];
+    expect(resolveConverter(twoEachSpecs, 'integer', 'string', rules)).toEqual({
+      nodeType: 'multi2',
+      inputName: 'b',
+      outputName: 'y'
+    });
+  });
+});
+
+describe('buildConverterInsertion', () => {
+  const nodes = [node('s', 'src', 0), node('t', 'dst', 100)];
+
+  it('uses a custom conversion rule when provided', () => {
+    const customSpecs = [
+      ...specs,
+      {
+        type: 'custom/intToStr',
+        inputs: [{ name: 'x', valueType: 'integer' }],
+        outputs: [{ name: 'y', valueType: 'string' }]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      customSpecs,
+      [{ from: 'integer', to: 'string', nodeType: 'custom/intToStr' }]
+    );
+    expect(insertion!.node.data.type).toBe('custom/intToStr');
+    expect(insertion!.edges[0]!.targetHandle).toBe('x');
+    expect(insertion!.edges[1]!.sourceHandle).toBe('y');
+  });
+
+  it('splices a converter between mismatched-but-convertible sockets', () => {
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      specs
+    );
+    expect(insertion).not.toBeNull();
+    expect(insertion!.node.data.type).toBe('math/toString/integer');
+    expect(insertion!.node.position).toEqual({ x: 50, y: 0 });
+    expect(insertion!.edges).toHaveLength(2);
+    expect(insertion!.edges[0]).toMatchObject({
+      source: 's',
+      sourceHandle: 'out',
+      target: insertion!.node.id,
+      targetHandle: 'a'
+    });
+    expect(insertion!.edges[1]).toMatchObject({
+      source: insertion!.node.id,
+      sourceHandle: 'result',
+      target: 't',
+      targetHandle: 'in'
+    });
+  });
+
+  it('wires the type-matched output port of a multi-output converter', () => {
+    // Converter emits both a boolean and a string; from→to is integer→string,
+    // so the splice must use the `string` output (`text`), not the first output.
+    const multiOutSpecs = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dst',
+        inputs: [{ name: 'in', valueType: 'string' }],
+        outputs: []
+      },
+      {
+        type: 'multiOut',
+        inputs: [{ name: 'a', valueType: 'integer' }],
+        outputs: [
+          { name: 'flag', valueType: 'boolean' },
+          { name: 'text', valueType: 'string' }
+        ]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      multiOutSpecs,
+      [{ from: 'integer', to: 'string', nodeType: 'multiOut' }]
+    );
+    expect(insertion!.node.data.type).toBe('multiOut');
+    expect(insertion!.edges[0]!.targetHandle).toBe('a');
+    // The converter→target edge leaves the string output, not the boolean one.
+    expect(insertion!.edges[1]!.sourceHandle).toBe('text');
+  });
+
+  it('honours an explicit outputKey to pin a specific output port', () => {
+    const twoStrOutSpecs = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dst',
+        inputs: [{ name: 'in', valueType: 'string' }],
+        outputs: []
+      },
+      {
+        type: 'twoOut',
+        inputs: [{ name: 'a', valueType: 'integer' }],
+        outputs: [
+          { name: 'x', valueType: 'string' },
+          { name: 'y', valueType: 'string' }
+        ]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      twoStrOutSpecs,
+      [
+        {
+          from: 'integer',
+          to: 'string',
+          nodeType: 'twoOut',
+          inputKey: 'a',
+          outputKey: 'y'
+        }
+      ]
+    );
+    expect(insertion!.edges[1]!.sourceHandle).toBe('y');
+  });
+
+  it('returns null for same-type connections', () => {
+    const sameSpecs = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dstI',
+        inputs: [{ name: 'in', valueType: 'integer' }],
+        outputs: []
+      }
+    ] as unknown as NodeSpecJSON[];
+    const ns = [node('s', 'src', 0), node('t', 'dstI', 100)];
+    expect(
+      buildConverterInsertion(conn('s', 'out', 't', 'in'), ns, sameSpecs)
+    ).toBeNull();
+  });
+
+  it('returns null when no converter is available', () => {
+    const noConv = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dstB',
+        inputs: [{ name: 'in', valueType: 'boolean' }],
+        outputs: []
+      }
+    ] as unknown as NodeSpecJSON[];
+    const ns = [node('s', 'src', 0), node('t', 'dstB', 100)];
+    expect(
+      buildConverterInsertion(conn('s', 'out', 't', 'in'), ns, noConv)
+    ).toBeNull();
+  });
+});

package/tests/autosavePlugin.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  registerCoreProfile,
+  writeNodeSpecsToJSON
+} from '@kiberon-labs/behave-graph';
+import { System } from '../src/system/system.js';
+import type { GraphSession } from '../src/system/graphSession.js';
+import {
+  autosavePlugin,
+  BackupStorage,
+  AUTOSAVE_ENABLED,
+  AUTOSAVE_INTERVAL_SECONDS,
+  AUTOSAVE_MAX_COPIES
+} from '../src/plugin/autosave/index.js';
+import type { BackupController } from '../src/plugin/autosave/index.js';
+
+/** In-memory get/set storage so backups never touch real localStorage. */
+const makeStorage = () => {
+  const backing: Record<string, string> = {};
+  return {
+    backing,
+    adapter: {
+      getItem: (k: string) => backing[k] ?? null,
+      setItem: (k: string, v: string) => {
+        backing[k] = v;
+      }
+    }
+  };
+};
+
+const NODE = (id: string, x = 0, y = 0) => ({
+  id,
+  type: 'behaveNode',
+  position: { x, y },
+  data: {
+    type: 'lifecycle/onStart',
+    configuration: {},
+    ports: {},
+    annotations: {}
+  }
+});
+
+describe('autosave plugin', () => {
+  let system: System;
+  let session: GraphSession;
+  let controller: BackupController;
+  let storage: ReturnType<typeof makeStorage>;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+
+    const coreRegistry = registerCoreProfile({
+      nodes: {},
+      values: {},
+      dependencies: {}
+    });
+    const registry = {
+      values: coreRegistry.values,
+      specs: writeNodeSpecsToJSON(coreRegistry)
+    };
+
+    storage = makeStorage();
+    system = new System(registry);
+    await system.registerPlugin(autosavePlugin, {
+      storage: storage.adapter,
+      addMenuItem: false
+    });
+    controller = system.backups as BackupController;
+    session = system.createSession('graph');
+  });
+
+  afterEach(() => {
+    controller.dispose();
+    vi.useRealTimers();
+  });
+
+  const dirty = (nodes = [NODE('a')], edges: any[] = []) => {
+    session.nodeStore.getState().setNodes(nodes);
+    session.edgeStore.getState().setEdges(edges);
+  };
+
+  it('registers the autosave settings and seeds defaults', () => {
+    const keys = system.settingsSchema.getState().settings.map((s) => s.key);
+    expect(keys).toContain(AUTOSAVE_ENABLED);
+    expect(keys).toContain(AUTOSAVE_INTERVAL_SECONDS);
+    expect(keys).toContain(AUTOSAVE_MAX_COPIES);
+    expect(system.getSetting(AUTOSAVE_ENABLED)).toBe(false);
+  });
+
+  it('installs the controller on the system', () => {
+    expect(system.backups).toBeInstanceOf(Object);
+    expect(typeof controller.backupNow).toBe('function');
+  });
+
+  it('captures a forced snapshot of the focused graph', () => {
+    dirty([NODE('a'), NODE('b')]);
+    const snap = controller.backupNow();
+    expect(snap).not.toBeNull();
+    expect(snap?.nodeCount).toBe(2);
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+    // Persisted to storage.
+    expect(new BackupStorage(storage.adapter).listAll()).toHaveLength(1);
+  });
+
+  it('does not capture an empty graph', () => {
+    expect(controller.backupNow()).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+
+  it('does not capture an inconsistent graph (edge to missing node)', () => {
+    dirty(
+      [NODE('a')],
+      [
+        {
+          id: 'e',
+          source: 'a',
+          target: 'ghost',
+          sourceHandle: 'f',
+          targetHandle: 'f'
+        }
+      ]
+    );
+    expect(controller.backupNow()).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+
+  it('skips a forced capture that duplicates the previous one', () => {
+    dirty([NODE('a')]);
+    expect(controller.backupNow()).not.toBeNull();
+    // No change since the last capture: identical, so skipped.
+    expect(controller.backupNow()).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+  });
+
+  it('does not capture while suspended', () => {
+    dirty([NODE('a')]);
+    controller.suspend();
+    expect(controller.backupNow()).toBeNull();
+    controller.resume();
+    expect(controller.backupNow()).not.toBeNull();
+  });
+
+  it('runExclusive brackets a region with no capture', () => {
+    dirty([NODE('a')]);
+    const inside = controller.runExclusive(() => controller.backupNow());
+    expect(inside).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+
+  it('trims each graph to the max-copies ring', () => {
+    system.setSetting(AUTOSAVE_MAX_COPIES, 3);
+    for (let i = 0; i < 5; i++) {
+      dirty([NODE('a', i, 0)]); // move node so each snapshot differs
+      controller.backupNow();
+    }
+    expect(controller.store.getState().snapshots).toHaveLength(3);
+  });
+
+  it('restores a snapshot into a new tab without touching the source graph', () => {
+    dirty([NODE('a'), NODE('b')]);
+    const snap = controller.backupNow()!;
+    const sessionsBefore = Object.keys(
+      system.activeGraph.getState().sessions
+    ).length;
+
+    const restored = controller.restore(snap.id);
+    expect(restored).toBeDefined();
+    expect(restored!.id).not.toBe(session.id);
+    expect(restored!.nodeStore.getState().nodes).toHaveLength(2);
+    expect(Object.keys(system.activeGraph.getState().sessions).length).toBe(
+      sessionsBefore + 1
+    );
+    // Source graph untouched.
+    expect(session.nodeStore.getState().nodes).toHaveLength(2);
+  });
+
+  it('runs the timer only while enabled and captures dirty, settled graphs', () => {
+    system.setSetting(AUTOSAVE_INTERVAL_SECONDS, 5);
+    system.setSetting(AUTOSAVE_ENABLED, true);
+    expect(controller.store.getState().running).toBe(true);
+
+    dirty([NODE('a')]);
+    // Advance past the interval AND the quiescence window.
+    vi.advanceTimersByTime(6000);
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+
+    system.setSetting(AUTOSAVE_ENABLED, false);
+    expect(controller.store.getState().running).toBe(false);
+  });
+
+  it('deletes a single snapshot and clears all', () => {
+    dirty([NODE('a')]);
+    const snap = controller.backupNow()!;
+    dirty([NODE('a'), NODE('b')]);
+    controller.backupNow();
+    expect(controller.store.getState().snapshots).toHaveLength(2);
+
+    controller.deleteSnapshot(snap.id);
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+
+    controller.clearAll();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+});