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

package/src/plugin/docs/panel/index.tsx

@@ -0,0 +1,21 @@
+import { lazy, Suspense } from 'react';
+import styles from './styles.module.css';
+
+/**
+ * The documentation panel embeds a tiptap/prosemirror editor (~320 KB) to render
+ * node markdown. Load it lazily so that weight only enters the bundle when the
+ * panel is actually opened.
+ */
+const LazyPanel = lazy(() =>
+  import('./DocumentationBrowserPanelImpl').then((m) => ({
+    default: m.DocumentationBrowserPanelImpl
+  }))
+);
+
+export function DocumentationBrowserPanel() {
+  return (
+    <Suspense fallback={<div className={styles.container} />}>
+      <LazyPanel />
+    </Suspense>
+  );
+}

package/src/plugin/docs/panel/styles.module.css

@@ -0,0 +1,174 @@
+.container {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    background: var(--colors-bgCanvas);
+    color: var(--colors-fg);
+    overflow: hidden;
+}
+
+.header {
+    padding: 1rem;
+    border-bottom: 1px solid var(--ds-input-border, var(--colors-borderSubtle));
+    background: var(--colors-bgPanel);
+}
+
+.titleSection {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.75rem;
+    margin-bottom: 0.75rem;
+}
+
+.iconLarge {
+    width: 48px;
+    height: 48px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 0.5rem;
+    border: 1px solid var(--ds-input-border, var(--colors-borderSubtle));
+    background: var(--colors-bgCanvas);
+    flex-shrink: 0;
+}
+
+.iconLarge svg {
+    width: 32px;
+    height: 32px;
+}
+
+.title {
+    margin: 0;
+    font-size: 1.25rem;
+    font-weight: 600;
+    line-height: 1.3;
+}
+
+.nodeType {
+    font-size: 0.75rem;
+    opacity: 0.7;
+    margin-top: 0.25rem;
+    font-family: monospace;
+}
+
+.tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+}
+
+.tag {
+    font-size: 0.75rem;
+    padding: 0.25rem 0.5rem;
+    border-radius: 0.25rem;
+    background: var(--ds-badge-bg, #4d4d4d);
+    color: var(--ds-badge-fg, #ffffff);
+}
+
+.content {
+    flex: 1;
+    overflow-y: auto;
+    padding: 1rem;
+}
+
+.description {
+    font-size: 1rem;
+    line-height: 1.5;
+    margin-bottom: 1.5rem;
+    padding: 0.75rem;
+    background: var(--ds-blockquote-bg, rgba(127, 127, 127, 0.1));
+    border-left: 4px solid var(--ds-blockquote-border, #007acc);
+    border-radius: 0.25rem;
+}
+
+
+.noContent {
+    padding: 2rem;
+    text-align: center;
+    opacity: 0.6;
+}
+
+.section {
+    margin-top: 2rem;
+}
+
+.sectionTitle {
+    font-size: 1rem;
+    font-weight: 600;
+    margin-bottom: 0.75rem;
+    padding-bottom: 0.25rem;
+    border-bottom: 1px solid var(--ds-input-border, var(--colors-borderSubtle));
+}
+
+.socketList {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+}
+
+.socketItem {
+    display: flex;
+    gap: 0.75rem;
+    align-items: center;
+    padding: 0.5rem;
+    background: var(--colors-bgPanel);
+    border-radius: 0.25rem;
+    border: 1px solid var(--ds-input-border, var(--colors-borderSubtle));
+}
+
+.socketIcon {
+    width: 20px;
+    height: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+}
+
+.socketIcon svg {
+    width: 16px;
+    height: 16px;
+}
+
+.socketName {
+    font-weight: 500;
+    flex: 1;
+}
+
+.socketType {
+    font-family: monospace;
+    font-size: 0.85rem;
+    font-weight: 500;
+    padding: 0.125rem 0.5rem;
+    border-radius: 0.25rem;
+    background: rgba(0, 0, 0, 0.2);
+}
+
+.empty {
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 2rem;
+    text-align: center;
+}
+
+.emptyIcon {
+    font-size: 4rem;
+    margin-bottom: 1rem;
+    opacity: 0.3;
+}
+
+.emptyText {
+    font-size: 1.25rem;
+    font-weight: 500;
+    margin-bottom: 0.5rem;
+    opacity: 0.8;
+}
+
+.emptySub {
+    font-size: 0.9rem;
+    opacity: 0.6;
+}

package/src/plugin/graphrunner/actions.ts

@@ -0,0 +1,326 @@
+import type { GraphSession } from '@/system/graphSession';
+import type { GraphRunnerClient } from './client';
+import type { GraphRunner } from './runner';
+import { executing } from '@/annotations';
+import { type ValueJSON } from '@kiberon-labs/behave-graph';
+import type { TraceBatchEvent } from './types';
+
+/**
+ * Per-session batcher for the `executing` node annotation.
+ *
+ * Trace events arrive per node execution (start + end), which at display-rate
+ * ticking means hundreds of events per frame. Writing the annotation straight
+ * through did a full O(nodes) copy-map of the node array per event; instead,
+ * accumulate the net executing state here and apply it once per animation
+ * frame with a single identity-preserving setNodes pass.
+ */
+type ExecutingBatch = {
+  pending: Map<string, boolean>;
+  scheduled: boolean;
+};
+
+const executingBatches = new WeakMap<GraphSession, ExecutingBatch>();
+
+const scheduleFrame = (cb: () => void): void => {
+  if (typeof requestAnimationFrame === 'function') {
+    requestAnimationFrame(cb);
+  } else {
+    setTimeout(cb, 16);
+  }
+};
+
+function flushExecutingState(session: GraphSession, batch: ExecutingBatch) {
+  batch.scheduled = false;
+  if (batch.pending.size === 0) return;
+  const updates = batch.pending;
+  batch.pending = new Map();
+
+  session.nodeStore.getState().setNodes((nodes) => {
+    let changed = false;
+    const next = nodes.map((node) => {
+      if (!('data' in node)) return node;
+      const target = updates.get(node.id);
+      if (target === undefined) return node;
+      if (Boolean(node.data.annotations?.[executing]) === target) return node;
+      changed = true;
+      return {
+        ...node,
+        data: {
+          ...node.data,
+          annotations: {
+            ...node.data.annotations,
+            [executing]: target
+          }
+        }
+      };
+    });
+    // Keep the original array identity when nothing changed so selector-based
+    // subscribers (the React Flow canvas) skip the re-render entirely.
+    return changed ? next : nodes;
+  });
+}
+
+function markExecuting(session: GraphSession, nodeId: string, state: boolean) {
+  let batch = executingBatches.get(session);
+  if (!batch) {
+    batch = { pending: new Map(), scheduled: false };
+    executingBatches.set(session, batch);
+  }
+  batch.pending.set(nodeId, state);
+  if (!batch.scheduled) {
+    batch.scheduled = true;
+    scheduleFrame(() => flushExecutingState(session, batch));
+  }
+}
+
+// Clear executing state from all nodes of a session, dropping any queued
+// per-node updates so a pending flush can't re-highlight after the run ended.
+function clearAllExecutingStates(session: GraphSession) {
+  const batch = executingBatches.get(session);
+  if (batch) batch.pending.clear();
+  session.nodeStore.getState().setNodes((nodes) => {
+    let changed = false;
+    const next = nodes.map((node) => {
+      if ('data' in node && node.data.annotations?.[executing]) {
+        changed = true;
+        return {
+          ...node,
+          data: {
+            ...node.data,
+            annotations: {
+              ...node.data.annotations,
+              [executing]: false
+            }
+          }
+        };
+      }
+      return node;
+    });
+    return changed ? next : nodes;
+  });
+}
+
+/** Apply one trace event to the session's trace spans + executing annotation. */
+function processTraceEvent(session: GraphSession, ev: TraceBatchEvent) {
+  const traceStore = session.traceStore.getState();
+  if (ev.event === 'start') {
+    let name = ev.nodeId;
+    if (ev.data && typeof ev.data === 'object' && 'typeName' in ev.data) {
+      const typeName = (ev.data as { typeName?: unknown }).typeName;
+      if (typeof typeName === 'string') {
+        name = typeName;
+      }
+    }
+    traceStore.addSpan({
+      nodeId: ev.nodeId,
+      name,
+      // `??` not `||`: the worker sends run-relative ms, so 0 is a valid (and
+      // common, for the first node) start , `||` fell back to the main thread's
+      // performance.now(), producing huge, wrong-clock timestamps.
+      start: ev.timestamp ?? performance.now(),
+      // Open span: NaN until the matching `end` event arrives. The store/render
+      // treat NaN as "still running"; a literal end let it render mis-sized.
+      end: Number.NaN
+      // lane omitted: let the store allocate/free lanes so concurrent spans
+      // stack instead of all piling into lane 0.
+    });
+    markExecuting(session, ev.nodeId, true);
+  } else if (ev.event === 'end') {
+    traceStore.updateSpan(ev.nodeId, {
+      end: ev.timestamp ?? performance.now()
+    });
+    markExecuting(session, ev.nodeId, false);
+  }
+}
+
+/**
+ * Clients that already have listeners attached. Guards against double-wiring when
+ * both the plugin's `runner.connect()` and a host (e.g. the webworker runner)
+ * call {@link setupClientEventListeners} on the same client , which would record
+ * every trace span, log and event twice.
+ */
+const wiredClients = new WeakSet<GraphRunnerClient>();
+
+/**
+ * Setup persistent event listeners on the shared client. Registered once when
+ * the client connects; every message is routed to the session that started its
+ * run (via {@link GraphRunner.runIndex}), so concurrent graphs stay isolated.
+ *
+ * Idempotent per client: calling it again with the same client is a no-op.
+ */
+export function setupClientEventListeners(
+  client: GraphRunnerClient,
+  runner: GraphRunner
+) {
+  if (wiredClients.has(client)) return;
+  wiredClients.add(client);
+
+  // Resolve the session that owns a given run id, or null if unknown.
+  const sessionFor = (runId: string): GraphSession | null =>
+    runner.runIndex.get(runId)?.session ?? null;
+
+  // Batched trace events (one message per flush window, many events inside).
+  client.on('traceBatch', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    for (const ev of message.events) {
+      processTraceEvent(session, ev);
+    }
+  });
+
+  // Single trace events , kept for remote servers that predate `traceBatch`.
+  client.on('trace', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    processTraceEvent(session, message);
+  });
+
+  // Listen for log messages
+  client.on('log', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    const formattedMessage = `[${message.runId}/${message.graphId}] ${message.message}${message.data !== undefined ? ` ${JSON.stringify(message.data)}` : ''}`;
+    session.logsStore.getState().append({
+      time: new Date(),
+      data: {
+        message: formattedMessage
+      },
+      type: message.level as any
+    });
+  });
+
+  // Listen for variable change events from server. A tick-driven graph writes
+  // variables every frame, so coalesce to the latest value per variable and
+  // apply once per animation frame instead of one store write per change.
+  const pendingVariableUpdates = new Map<GraphSession, Map<string, unknown>>();
+  let variableFlushScheduled = false;
+
+  const flushVariableUpdates = () => {
+    variableFlushScheduled = false;
+    for (const [session, updates] of pendingVariableUpdates) {
+      const variableStore = session.variableStore.getState();
+      for (const [id, newValue] of updates) {
+        const existingVariable = variableStore.variables[id];
+        if (existingVariable) {
+          variableStore.setVariable(id, {
+            ...existingVariable,
+            initialValue: newValue as ValueJSON
+          });
+        } else {
+          const inferredType = typeof newValue;
+          variableStore.setVariable(id, {
+            id,
+            name: id,
+            valueTypeName: inferredType === 'object' ? 'string' : inferredType,
+            initialValue: newValue as ValueJSON
+          });
+        }
+      }
+    }
+    pendingVariableUpdates.clear();
+  };
+
+  client.on('variableChanged', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    let updates = pendingVariableUpdates.get(session);
+    if (!updates) {
+      updates = new Map();
+      pendingVariableUpdates.set(session, updates);
+    }
+    updates.set(message.variableName, message.newValue);
+    if (!variableFlushScheduled) {
+      variableFlushScheduled = true;
+      scheduleFrame(flushVariableUpdates);
+    }
+  });
+
+  // Run lifecycle events
+  client.on('completed', (message) => {
+    const controller = runner.runIndex.get(message.runId);
+    if (!controller) return;
+    controller.session.editor.notifications.success(
+      `Graph completed: ${message.graphId}`
+    );
+    controller.finishRun();
+    clearAllExecutingStates(controller.session);
+  });
+
+  client.on('error', (message) => {
+    if (!message.runId) return;
+    const controller = runner.runIndex.get(message.runId);
+    if (!controller) return;
+    controller.session.editor.notifications.error(
+      `Graph failed: ${message.graphId}`
+    );
+    controller.finishRun();
+    clearAllExecutingStates(controller.session);
+  });
+
+  client.on('stopped', (message) => {
+    const controller = runner.runIndex.get(message.runId);
+    if (!controller) return;
+    controller.session.editor.notifications.info(
+      `Graph stopped: ${message.graphId}`
+    );
+    controller.finishRun();
+    clearAllExecutingStates(controller.session);
+  });
+
+  // Realtime state change listeners
+  client.on('nodeRemoved', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    session.nodeStore
+      .getState()
+      .setNodes((nodes) => nodes.filter((node) => node.id !== message.nodeId));
+    session.editor.notifications.info(`Node removed: ${message.nodeId}`);
+  });
+
+  client.on('linkCreated', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    session.editor.notifications.info(
+      `Link created: ${message.fromNodeId}/${message.fromSocket} -> ${message.toNodeId}/${message.toSocket}`
+    );
+  });
+
+  client.on('linkRemoved', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    session.editor.notifications.info(
+      `Link removed: ${message.fromNodeId}/${message.fromSocket} -> ${message.toNodeId}/${message.toSocket}`
+    );
+  });
+
+  client.on('nodeParamUpdated', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    session.editor.notifications.info(`Parameter updated on ${message.nodeId}`);
+  });
+
+  client.on('affectedNodes', (message) => {
+    const session = sessionFor(message.runId);
+    if (!session) return;
+    session.nodeStore.getState().setNodes((nodes) =>
+      nodes.map((node) => {
+        if (message.nodeIds.includes(node.id)) {
+          return {
+            ...node,
+            data: {
+              ...node.data,
+              annotations: {
+                ...node.data?.annotations,
+                [executing]: true
+              }
+            }
+          };
+        }
+        return node;
+      })
+    );
+    session.editor.notifications.info(
+      `Executing ${message.reason}: ${message.nodeIds.length} node(s)`
+    );
+  });
+}

package/src/plugin/graphrunner/buttons.tsx

@@ -0,0 +1,95 @@
+import { VscodeButton } from '@vscode-elements/react-elements';
+import { useStore, type StoreApi } from 'zustand';
+import { Play, PauseWindow, Square, ArrowRight } from 'iconoir-react';
+import { useGraph } from '@/system/provider';
+import type { GraphRunnerClientStore } from './store';
+import type { GraphRunController } from './runController';
+
+/**
+ * Execution controls for the graph in the surrounding tab. Connection state
+ * comes from the shared runner connection; run state comes from this graph's own
+ * run controller, so each open graph has independent controls.
+ */
+export const GraphRunnerButtons = () => {
+  const session = useGraph();
+  const controller = session.runController;
+  if (!controller) return null;
+  return (
+    <Buttons
+      controller={controller}
+      connectionStore={session.editor.runner.store}
+    />
+  );
+};
+
+const Buttons = ({
+  controller,
+  connectionStore
+}: {
+  controller: GraphRunController;
+  connectionStore: StoreApi<GraphRunnerClientStore>;
+}) => {
+  const connectionState = useStore(connectionStore, (s) => s.connectionState);
+  const isExecuting = useStore(controller.store, (s) => s.isExecuting);
+  const isPaused = useStore(controller.store, (s) => s.isPaused);
+
+  const isConnected = connectionState === 'connected';
+
+  return (
+    <>
+      {!isExecuting && (
+        <VscodeButton
+          secondary
+          iconOnly
+          title="Play Graph"
+          onClick={() => controller.play()}
+          disabled={!isConnected}
+        >
+          <Play />
+        </VscodeButton>
+      )}
+      {isExecuting && !isPaused && (
+        <VscodeButton
+          secondary
+          iconOnly
+          title="Pause Graph"
+          onClick={() => controller.pause()}
+          disabled={!isConnected}
+        >
+          <PauseWindow />
+        </VscodeButton>
+      )}
+      {isExecuting && isPaused && (
+        <>
+          <VscodeButton
+            secondary
+            iconOnly
+            title="Resume Graph"
+            onClick={() => controller.resume()}
+            disabled={!isConnected}
+          >
+            <Play />
+          </VscodeButton>
+          <VscodeButton
+            secondary
+            iconOnly
+            title="Step Forward"
+            onClick={() => controller.step()}
+            disabled={!isConnected}
+          >
+            <ArrowRight />
+          </VscodeButton>
+        </>
+      )}
+      <VscodeButton
+        secondary
+        iconOnly
+        title="Stop Graph"
+        onClick={() => controller.stop()}
+        disabled={!isExecuting}
+      >
+        <Square />
+      </VscodeButton>
+    </>
+  );
+};