@kiberon-labs/behave-graph-flow 2.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

@@ -1,6 +1,6 @@
 import { type System } from '@/system/system';
 import type { NodeDocumentation } from '@/store/documentation';
-import { BounceRight, Flash, PauseWindow } from 'iconoir-react';
+import { BounceRight, Flash, GitFork, PauseWindow } from 'iconoir-react';
 import { DocumentationBrowserPanel } from './panel';
 import { ErrorBoundary } from 'react-error-boundary';
 import { MenuItemElement } from '../../components/menubar/menuItem';
@@ -84,9 +84,7 @@ Documentation: The description field serves as inline documentation of assumptio
     },
 
     {
-      icon: (
-        <img src="https://imgs.search.brave.com/I24-hRYZL3tBnj1vmcr525tMOtlP-GFWPoS1qr7tMdo/rs:fit:860:0:0:0/g:ce/aHR0cHM6Ly9pbWcu/aWNvbnM4LmNvbS9l/eHRlcm5hbC1mbGF0/aWNvbnMtbGluZWFs/LWNvbG9yLWZsYXQt/aWNvbnMvMTIwMC9l/eHRlcm5hbC1kZWJ1/Zy1tb2JpbGUtYXBw/LWRldmVsb3BtZW50/LWZsYXRpY29ucy1s/aW5lYWwtY29sb3It/ZmxhdC1pY29ucy5q/cGc" />
-      ),
+      icon: <GitFork />,
       type: 'flow/branch',
       shortDescription: 'Execute different flows based on a boolean condition',
       tags: ['flow', 'conditional', 'control'],

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>
+  );
+}

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

@@ -1,200 +1,21 @@
-import { useMemo, useCallback } 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 { lazy, Suspense } from 'react';
 import styles from './styles.module.css';
 
-export function DocumentationBrowserPanel() {
-  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) => {
-      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;
+/**
+ * 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 (
-    <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 && (
-          <>
-            {nodeSpec.inputs && nodeSpec.inputs.length > 0 && (
-              <div className={styles.section}>
-                <h3 className={styles.sectionTitle}>Inputs</h3>
-                <div className={styles.socketList}>
-                  {nodeSpec.inputs.map((input, index) => {
-                    const IconComponent = getIconForType(input.valueType);
-                    const color = getColorForType(input.valueType);
-                    return (
-                      <div key={index} className={styles.socketItem}>
-                        <div className={styles.socketIcon} style={{ color }}>
-                          <IconComponent />
-                        </div>
-                        <div className={styles.socketName}>{input.name}</div>
-                        <div className={styles.socketType} style={{ color }}>
-                          {input.valueType}
-                        </div>
-                      </div>
-                    );
-                  })}
-                </div>
-              </div>
-            )}
-
-            {nodeSpec.outputs && nodeSpec.outputs.length > 0 && (
-              <div className={styles.section}>
-                <h3 className={styles.sectionTitle}>Outputs</h3>
-                <div className={styles.socketList}>
-                  {nodeSpec.outputs.map((output, index) => {
-                    const IconComponent = getIconForType(output.valueType);
-                    const color = getColorForType(output.valueType);
-                    return (
-                      <div key={index} className={styles.socketItem}>
-                        <div className={styles.socketIcon} style={{ color }}>
-                          <IconComponent />
-                        </div>
-                        <div className={styles.socketName}>{output.name}</div>
-                        <div className={styles.socketType} style={{ color }}>
-                          {output.valueType}
-                        </div>
-                      </div>
-                    );
-                  })}
-                </div>
-              </div>
-            )}
-
-            {nodeSpec.configuration && nodeSpec.configuration.length > 0 && (
-              <div className={styles.section}>
-                <h3 className={styles.sectionTitle}>Configuration</h3>
-                <div className={styles.socketList}>
-                  {nodeSpec.configuration.map((config, index) => {
-                    const IconComponent = getIconForType(config.valueType);
-                    const color = getColorForType(config.valueType);
-                    return (
-                      <div key={index} className={styles.socketItem}>
-                        <div className={styles.socketIcon} style={{ color }}>
-                          <IconComponent />
-                        </div>
-                        <div className={styles.socketName}>{config.name}</div>
-                        <div className={styles.socketType} style={{ color }}>
-                          {config.valueType}
-                        </div>
-                      </div>
-                    );
-                  })}
-                </div>
-              </div>
-            )}
-          </>
-        )}
-      </div>
-    </div>
+    <Suspense fallback={<div className={styles.container} />}>
+      <LazyPanel />
+    </Suspense>
   );
 }