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

package/src/plugin/autosave/settings.ts

@@ -0,0 +1,65 @@
+import type { SettingDescriptor } from '@/store/settingsSchema';
+
+/**
+ * Setting keys owned by the autosave plugin. Namespaced (`autosave.*`) so they
+ * never collide with the built-in flat setting keys.
+ */
+export const AUTOSAVE_ENABLED = 'autosave.enabled';
+export const AUTOSAVE_INTERVAL_SECONDS = 'autosave.intervalSeconds';
+export const AUTOSAVE_MAX_COPIES = 'autosave.maxCopies';
+
+/** Shipped defaults, also used by the controller when a value is missing. */
+export const AUTOSAVE_DEFAULTS = {
+  enabled: false,
+  intervalSeconds: 60,
+  maxCopies: 20
+} as const;
+
+/** Lower bound on the timer so a typo can't spin the loop every frame. */
+export const MIN_INTERVAL_SECONDS = 5;
+
+/**
+ * The Settings-panel rows this plugin contributes. Registered via
+ * `system.registerSettings(...)`, which also seeds each default into the value
+ * store, so `system.getSetting(AUTOSAVE_*)` is populated the moment the plugin
+ * loads.
+ */
+export const AUTOSAVE_SETTINGS: SettingDescriptor[] = [
+  {
+    key: AUTOSAVE_ENABLED,
+    section: 'Autosave',
+    order: 0,
+    type: 'boolean',
+    default: AUTOSAVE_DEFAULTS.enabled,
+    title: 'Enable local backups',
+    description:
+      'Periodically snapshot open graphs into local storage so a crash or a bad edit is recoverable. Purely client-side; nothing leaves the browser.'
+  },
+  {
+    key: AUTOSAVE_INTERVAL_SECONDS,
+    section: 'Autosave',
+    order: 1,
+    type: 'number',
+    default: AUTOSAVE_DEFAULTS.intervalSeconds,
+    min: MIN_INTERVAL_SECONDS,
+    step: 5,
+    title: 'Backup frequency (seconds)',
+    description:
+      'How often a snapshot is taken. A copy is only written when the graph has actually changed and is in a consistent state.',
+    when: (values) => values[AUTOSAVE_ENABLED] === true
+  },
+  {
+    key: AUTOSAVE_MAX_COPIES,
+    section: 'Autosave',
+    order: 2,
+    type: 'number',
+    default: AUTOSAVE_DEFAULTS.maxCopies,
+    min: 1,
+    max: 200,
+    step: 1,
+    title: 'Copies to keep per graph',
+    description:
+      'The oldest snapshots are discarded once a graph has this many. Higher values use more local storage.',
+    when: (values) => values[AUTOSAVE_ENABLED] === true
+  }
+];

package/src/plugin/autosave/storage.ts

@@ -0,0 +1,147 @@
+import type { UIGraphJSON } from '@/types/graph';
+import type { SettingsStorage } from '@/system/system';
+
+/** Single local-storage key holding every graph's backup ring. */
+export const AUTOSAVE_STORAGE_KEY = 'behave-graph:autosave';
+
+/** A single point-in-time copy of one graph. */
+export type BackupSnapshot = {
+  /** Unique id for this snapshot (used by the panel to restore/delete). */
+  id: string;
+  /** Session id of the graph this snapshot came from. */
+  graphId: string;
+  /** Graph display name captured at snapshot time (for the panel list). */
+  name: string;
+  /** Epoch milliseconds when the snapshot was taken. */
+  timestamp: number;
+  /** Node count, shown in the panel without deserializing the whole graph. */
+  nodeCount: number;
+  /** The full, restorable graph document. */
+  graph: UIGraphJSON;
+};
+
+/** Per-graph ring buffer of snapshots, newest last. */
+type GraphBackups = {
+  name: string;
+  snapshots: BackupSnapshot[];
+};
+
+/** The persisted shape: graph id -> its backups. */
+type BackupStore = Record<string, GraphBackups>;
+
+/**
+ * localStorage-or-nothing accessor. The whole backup set lives under a single
+ * key as a JSON object, so a plain get/set storage adapter (the same shape the
+ * settings persistence uses) is all we need , no `key(i)`/`length` scanning.
+ */
+const defaultStorage = (): SettingsStorage | undefined => {
+  try {
+    if (typeof localStorage !== 'undefined') return localStorage;
+  } catch {
+    // localStorage can throw in sandboxed / SSR contexts.
+  }
+  return undefined;
+};
+
+const readStore = (storage: SettingsStorage): BackupStore => {
+  try {
+    const raw = storage.getItem(AUTOSAVE_STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? (parsed as BackupStore) : {};
+  } catch {
+    return {};
+  }
+};
+
+const writeStore = (storage: SettingsStorage, store: BackupStore): void => {
+  try {
+    storage.setItem(AUTOSAVE_STORAGE_KEY, JSON.stringify(store));
+  } catch {
+    // Quota exceeded / serialization error: drop this write rather than throw.
+    // The next successful snapshot will re-establish the ring.
+  }
+};
+
+/**
+ * Thin persistence wrapper over the single backup key. Kept storage-agnostic
+ * (any get/set adapter) so hosts can back it with something other than
+ * localStorage and tests can inject an in-memory map.
+ */
+export class BackupStorage {
+  private readonly storage: SettingsStorage | undefined;
+
+  constructor(storage: SettingsStorage | undefined = defaultStorage()) {
+    this.storage = storage;
+  }
+
+  /** Whether a backing store is available (false in SSR / sandboxed contexts). */
+  get available(): boolean {
+    return this.storage !== undefined;
+  }
+
+  /** All snapshots across every graph, newest first. */
+  listAll(): BackupSnapshot[] {
+    if (!this.storage) return [];
+    const store = readStore(this.storage);
+    return Object.values(store)
+      .flatMap((g) => g.snapshots)
+      .sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  /** Find one snapshot by id (across all graphs). */
+  find(id: string): BackupSnapshot | undefined {
+    return this.listAll().find((s) => s.id === id);
+  }
+
+  /**
+   * Append a snapshot to its graph's ring and trim to `maxCopies` (oldest
+   * dropped). `name` refreshes the stored graph label so the panel tracks
+   * renames.
+   */
+  append(snapshot: BackupSnapshot, maxCopies: number): void {
+    if (!this.storage) return;
+    const store = readStore(this.storage);
+    const entry = store[snapshot.graphId] ?? {
+      name: snapshot.name,
+      snapshots: []
+    };
+    entry.name = snapshot.name;
+    entry.snapshots = [...entry.snapshots, snapshot];
+    const limit = Math.max(1, Math.floor(maxCopies));
+    if (entry.snapshots.length > limit) {
+      entry.snapshots = entry.snapshots.slice(entry.snapshots.length - limit);
+    }
+    store[snapshot.graphId] = entry;
+    writeStore(this.storage, store);
+  }
+
+  /** Remove a single snapshot; prunes the graph entry once it is empty. */
+  remove(id: string): void {
+    if (!this.storage) return;
+    const store = readStore(this.storage);
+    for (const [graphId, entry] of Object.entries(store)) {
+      const next = entry.snapshots.filter((s) => s.id !== id);
+      if (next.length === entry.snapshots.length) continue;
+      if (next.length === 0) delete store[graphId];
+      else store[graphId] = { ...entry, snapshots: next };
+      writeStore(this.storage, store);
+      return;
+    }
+  }
+
+  /** Drop every snapshot for a single graph. */
+  removeGraph(graphId: string): void {
+    if (!this.storage) return;
+    const store = readStore(this.storage);
+    if (!(graphId in store)) return;
+    delete store[graphId];
+    writeStore(this.storage, store);
+  }
+
+  /** Wipe all backups. */
+  clear(): void {
+    if (!this.storage) return;
+    writeStore(this.storage, {});
+  }
+}

package/src/plugin/docs/index.tsx

@@ -0,0 +1,297 @@
+import { type System } from '@/system/system';
+import type { NodeDocumentation } from '@/store/documentation';
+import { BounceRight, Flash, GitFork, PauseWindow } from 'iconoir-react';
+import { DocumentationBrowserPanel } from './panel';
+import { ErrorBoundary } from 'react-error-boundary';
+import { MenuItemElement } from '../../components/menubar/menuItem';
+import { plugin } from '@/system/plugin';
+
+/**
+ * This is a plugin that sets up default documentation for core behave-graph nodes.
+ * It uses the documentation store to add rich markdown descriptions,
+ * short descriptions, and tags for various node types.
+ * @param sys
+ */
+export const docsPluginLoader = (sys: System, _options: void) => {
+  const docStore = sys.documentationStore.getState();
+
+  sys.tabLoader.register('docbrowser', () => {
+    return {
+      id: 'docbrowser',
+      closable: true,
+      cached: true,
+      title: 'Documentation',
+      group: 'headless',
+      content: () => (
+        <ErrorBoundary fallback={'whoops'}>
+          <DocumentationBrowserPanel />
+        </ErrorBoundary>
+      )
+    };
+  });
+
+  // Flow control nodes
+  const flowDocs: NodeDocumentation[] = [
+    {
+      type: 'flow/debounce',
+      shortDescription: 'Debounce rapid flow executions',
+      tags: ['flow', 'control', 'async'],
+      markdownDescription: `
+Prevents a flow from executing too frequently by enforcing a minimum delay between executions.
+`,
+      icon: <BounceRight />
+    },
+
+    {
+      type: 'customEvent/trigger',
+      shortDescription: 'Trigger a custom event by name',
+      tags: ['event', 'custom', 'trigger'],
+      markdownDescription: `
+Triggers a custom event by name, allowing other parts of the graph to respond to it.
+
+You will need to pass through the required parameters of the event when triggering it.
+        `.trim(),
+      icon: <Flash />
+    },
+
+    {
+      type: 'time/delay',
+      shortDescription: 'Delay execution for a specified duration',
+      tags: ['time', 'async', 'delay', 'control'],
+      markdownDescription: `
+Pauses execution for a specified number of seconds before continuing.
+
+Useful for creating timed behaviors, animations, or cooldown mechanics.
+      `.trim(),
+      icon: <PauseWindow />
+    },
+
+    {
+      type: 'debug/expectTrue',
+      shortDescription: 'Asserts that a condition is true during execution',
+      tags: ['debug', 'assertion', 'testing'],
+      markdownDescription: `
+## Purpose
+The Assert Expect True node is a debugging and validation tool used during graph execution to verify runtime conditions. It validates that a boolean condition evaluates to true at a specific point in the execution flow.
+
+## Use Cases
+Testing & Debugging: Validate that graph logic produces expected intermediate results
+Runtime Invariants: Enforce constraints that must always hold true during execution
+Quality Assurance: Catch logic errors early in development by asserting expected states
+Documentation: The description field serves as inline documentation of assumptions
+
+`.trim()
+    },
+
+    {
+      icon: <GitFork />,
+      type: 'flow/branch',
+      shortDescription: 'Execute different flows based on a boolean condition',
+      tags: ['flow', 'conditional', 'control'],
+      markdownDescription: `
+Conditionally executes one of two flow paths based on a boolean input.
+
+## Common Use Cases
+- Implementing if/else logic
+- State-based behavior
+- Conditional event handling
+      `.trim()
+    },
+    {
+      type: 'flow/sequence',
+      shortDescription: 'Execute multiple flows in order',
+      tags: ['flow', 'control', 'sequential'],
+      markdownDescription: `
+# Sequence
+
+Executes multiple flow outputs in order, one after another.
+
+Perfect for chaining multiple actions that need to happen sequentially.
+      `.trim()
+    },
+    {
+      type: 'flow/delay',
+      shortDescription: 'Delay execution for a specified duration',
+      tags: ['flow', 'time', 'async'],
+      markdownDescription: `
+# Delay
+
+Pauses execution for a specified number of seconds before continuing.
+
+Useful for creating timed behaviors, animations, or cooldown mechanics.
+      `.trim()
+    }
+  ];
+
+  // Math nodes
+  const mathDocs: NodeDocumentation[] = [
+    {
+      type: 'math/add',
+      shortDescription: 'Add two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription: 'Calculates the sum of two numeric values: a + b'
+    },
+    {
+      type: 'math/subtract',
+      shortDescription: 'Subtract two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription: 'Calculates the difference: a - b'
+    },
+    {
+      type: 'math/multiply',
+      shortDescription: 'Multiply two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription: 'Calculates the product: a * b'
+    },
+    {
+      type: 'math/divide',
+      shortDescription: 'Divide two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription:
+        'Calculates the quotient: a / b\\n\\n⚠️ Division by zero returns 0'
+    }
+  ];
+
+  // Logic nodes
+  const logicDocs: NodeDocumentation[] = [
+    {
+      type: 'logic/and',
+      shortDescription: 'Logical AND of two boolean values',
+      tags: ['logic', 'boolean', 'gates'],
+      markdownDescription: 'Returns true only if both inputs are true'
+    },
+    {
+      type: 'logic/or',
+      shortDescription: 'Logical OR of two boolean values',
+      tags: ['logic', 'boolean', 'gates'],
+      markdownDescription: 'Returns true if at least one input is true'
+    },
+    {
+      type: 'logic/not',
+      shortDescription: 'Logical NOT - inverts a boolean value',
+      tags: ['logic', 'boolean', 'gates'],
+      markdownDescription:
+        'Inverts the input: true becomes false, false becomes true'
+    }
+  ];
+
+  // Variable nodes
+  const variableDocs: NodeDocumentation[] = [
+    {
+      type: 'variable/get',
+      shortDescription: 'Read a variable value',
+      tags: ['variable', 'state', 'getter'],
+      markdownDescription: `
+Retrieves the current value of a named variable.
+
+Variables are shared across the entire graph and persist between executions.
+      `.trim()
+    },
+    {
+      type: 'variable/set',
+      shortDescription: 'Write a variable value',
+      tags: ['variable', 'state', 'setter'],
+      markdownDescription: `
+Sets the value of a named variable.
+
+This executes as a flow and passes through to allow chaining.
+      `.trim()
+    }
+  ];
+
+  // Event nodes
+  const eventDocs: NodeDocumentation[] = [
+    {
+      type: 'lifecycle/onStart',
+      shortDescription: 'Triggered when the graph starts',
+      tags: ['event', 'lifecycle', 'entry'],
+      markdownDescription: `
+Fires once when the graph begins execution.
+
+Perfect for initialization logic and setup tasks.
+      `.trim()
+    },
+    {
+      type: 'lifecycle/onEnd',
+      shortDescription: 'Triggered when the graph ends',
+      tags: ['event', 'lifecycle', 'cleanup'],
+      markdownDescription: `
+# On End
+
+Fires once when the graph stops execution.
+
+Useful for cleanup, saving state, or final actions.
+      `.trim()
+    },
+    {
+      type: 'lifecycle/onTick',
+      shortDescription: 'Triggered every frame/update',
+      tags: ['event', 'lifecycle', 'update', 'loop'],
+      markdownDescription: `
+# On Tick
+
+Fires continuously on every update cycle.
+
+⚠️ Use carefully - runs every frame! Great for animations and real-time updates.
+      `.trim()
+    }
+  ];
+
+  // Combine and set all documentation
+  const allDocs = [
+    ...flowDocs,
+    ...mathDocs,
+    ...logicDocs,
+    ...variableDocs,
+    ...eventDocs
+  ];
+
+  docStore.setMultipleDocumentation(allDocs);
+
+  console.log(`✅ Loaded documentation for ${allDocs.length} nodes`);
+
+  // Register the documentation panel with TabLoader
+  sys.tabLoader.register('docs', () => {
+    return {
+      id: 'docs',
+      closable: true,
+      title: 'Documentation',
+      group: 'default',
+      content: () => (
+        <ErrorBoundary fallback={'Error loading Documentation panel'}>
+          <DocumentationBrowserPanel />
+        </ErrorBoundary>
+      )
+    };
+  });
+
+  // Add menu item to Window menu
+  const menuStore = sys.menubarStore;
+  const currentItems = menuStore.getState().items;
+  const windowMenu = currentItems.find((menu) => menu.name === 'window');
+
+  if (windowMenu) {
+    // Add the Documentation menu item to the Window menu
+    const newMenuItem = {
+      name: 'docs',
+      render: function DocsMenuItem() {
+        return (
+          <MenuItemElement
+            onClick={() => sys.tabStore.getState().openTab('docs')}
+            key="docs"
+          >
+            Documentation
+          </MenuItemElement>
+        );
+      }
+    };
+
+    menuStore
+      .getState()
+      .setSubMenuItems('window', [...windowMenu.items, newMenuItem]);
+  }
+};
+
+export const docsPlugin = plugin(docsPluginLoader, {
+  name: 'docs'
+});

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

@@ -0,0 +1,200 @@
+import { useMemo, useCallback, type ComponentType } from 'react';
+import { useEditor, EditorContent } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import { useSystem } from '@/system/provider';
+import { Markdown } from 'tiptap-markdown';
+import { useStore } from 'zustand';
+import type { ExtendedNodeSpecJSON } from '@/components/contextMenus/NodePicker';
+import { useOnPressKey } from '@/hooks/useOnPressKey';
+import { removeTabFromLayout } from '@/components/layoutController/utils';
+import styles from './styles.module.css';
+
+/** One named socket (name + value type) rendered in a documentation section. */
+interface DocSocket {
+  name: string;
+  valueType: string;
+}
+
+interface SocketSectionProps {
+  title: string;
+  sockets: DocSocket[] | undefined;
+  getIconForType: (valueType: string) => ComponentType;
+  getColorForType: (valueType: string) => string;
+}
+
+/**
+ * A titled list of node sockets (Inputs / Outputs / Configuration). Renders
+ * nothing when the socket list is empty so callers can drop it in
+ * unconditionally.
+ */
+function SocketSection({
+  title,
+  sockets,
+  getIconForType,
+  getColorForType
+}: SocketSectionProps) {
+  if (!sockets || sockets.length === 0) return null;
+
+  return (
+    <div className={styles.section}>
+      <h3 className={styles.sectionTitle}>{title}</h3>
+      <div className={styles.socketList}>
+        {sockets.map((socket, index) => {
+          const IconComponent = getIconForType(socket.valueType);
+          const color = getColorForType(socket.valueType);
+          return (
+            <div key={index} className={styles.socketItem}>
+              <div className={styles.socketIcon} style={{ color }}>
+                <IconComponent />
+              </div>
+              <div className={styles.socketName}>{socket.name}</div>
+              <div className={styles.socketType} style={{ color }}>
+                {socket.valueType}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+export function DocumentationBrowserPanelImpl() {
+  const sys = useSystem();
+  const selectedNodeType = useStore(
+    sys.refStore,
+    (x) => x.refs.selectedDocumentationType
+  );
+  const documentation = useStore(sys.documentationStore, (x) => x.docs);
+  const specs = useStore(sys.specStore, (x) => x.specs);
+  const icons = useStore(sys.legendStore, (x) => x.icons);
+  const defaultIcon = useStore(sys.legendStore, (x) => x.defaultIcon);
+  const valueTypeColors = useStore(sys.legendStore, (x) => x.valueTypeColors);
+
+  const nodeSpec = useMemo((): ExtendedNodeSpecJSON | null => {
+    if (!selectedNodeType) return null;
+    return specs.find((s) => s.type === selectedNodeType) ?? null;
+  }, [selectedNodeType, specs]);
+
+  const getIconForType = useCallback(
+    (valueType: string): ComponentType => {
+      const IconComponent = icons[valueType] || defaultIcon;
+      return IconComponent;
+    },
+    [icons, defaultIcon]
+  );
+
+  const getColorForType = useCallback(
+    (valueType: string) => {
+      return valueTypeColors[valueType] || '#6c727e';
+    },
+    [valueTypeColors]
+  );
+
+  const nodeDoc = useMemo(() => {
+    if (!selectedNodeType) return null;
+    return documentation.get(selectedNodeType);
+  }, [selectedNodeType, documentation]);
+
+  const editor = useEditor(
+    {
+      extensions: [StarterKit, Markdown],
+      content: nodeDoc?.markdownDescription || '',
+      editable: false
+    },
+    [nodeDoc?.markdownDescription]
+  );
+
+  const closePanel = useCallback(() => {
+    const currentLayout = sys.tabStore.getState().layout;
+    const newLayout = removeTabFromLayout(currentLayout, 'docbrowser');
+    sys.tabStore.getState().setLayout(newLayout);
+  }, [sys]);
+
+  useOnPressKey('Escape', closePanel);
+
+  if (!selectedNodeType) {
+    return (
+      <div className={styles.container}>
+        <div className={styles.empty}>
+          <div className={styles.emptyIcon}>📚</div>
+          <div className={styles.emptyText}>No documentation selected</div>
+          <div className={styles.emptySub}>
+            Click the info icon on a node to view its documentation
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  const hasMarkdown = nodeDoc?.markdownDescription;
+  const hasShortDescription =
+    nodeDoc?.shortDescription || nodeSpec?.description;
+  const hasTags = nodeDoc?.tags && nodeDoc.tags.length > 0;
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.header}>
+        <div className={styles.titleSection}>
+          {nodeDoc?.icon && (
+            <div className={styles.iconLarge}>{nodeDoc.icon}</div>
+          )}
+          <div>
+            <h2 className={styles.title}>
+              {nodeSpec?.label || selectedNodeType}
+            </h2>
+            <div className={styles.nodeType}>{selectedNodeType}</div>
+          </div>
+        </div>
+        {hasTags && nodeDoc?.tags && (
+          <div className={styles.tags}>
+            {nodeDoc.tags.map((tag, index) => (
+              <span key={index} className={styles.tag}>
+                {tag}
+              </span>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div className={styles.content}>
+        {hasShortDescription && (
+          <div className={styles.description}>
+            {nodeDoc?.shortDescription || nodeSpec?.description}
+          </div>
+        )}
+
+        {hasMarkdown && nodeDoc?.markdownDescription ? (
+          <EditorContent editor={editor} />
+        ) : (
+          <div className={styles.noContent}>
+            <p>No detailed documentation available for this node.</p>
+          </div>
+        )}
+
+        {nodeSpec && (
+          <>
+            <SocketSection
+              title="Inputs"
+              sockets={nodeSpec.inputs}
+              getIconForType={getIconForType}
+              getColorForType={getColorForType}
+            />
+            <SocketSection
+              title="Outputs"
+              sockets={nodeSpec.outputs}
+              getIconForType={getIconForType}
+              getColorForType={getColorForType}
+            />
+            <SocketSection
+              title="Configuration"
+              sockets={nodeSpec.configuration}
+              getIconForType={getIconForType}
+              getColorForType={getColorForType}
+            />
+          </>
+        )}
+      </div>
+    </div>
+  );
+}