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

package/src/store/settings.ts

@@ -9,91 +9,91 @@ export const EDGE_TYPE = {
 
 export type EdgeType = (typeof EDGE_TYPE)[keyof typeof EDGE_TYPE];
 
-export const LAYOUT_TYPE = {
-  dagre: 'Dagre',
-  elkForce: 'Elk - Force',
-  elkRect: 'Elk - Rect',
-  elkLayered: 'Elk - Layered'
-} as const;
+export type GeneratorLocation = 'inline' | 'panel';
 
-export type LayoutType = (typeof LAYOUT_TYPE)[keyof typeof LAYOUT_TYPE];
+/**
+ * Single source of truth for editor settings. Each entry's `default` defines the
+ * value (and its type); `persist: false` excludes it from the saved settings.
+ * The store shape, setters, and the persisted-key list are all derived from this
+ * , adding a setting here is the only edit needed (no setter boilerplate, no
+ * separate persist allow-list to keep in sync).
+ */
+const SETTINGS = {
+  edgeType: { default: EDGE_TYPE.bezier as EdgeType },
+  debugMode: { default: false as boolean },
+  showMenu: { default: true as boolean },
+  showTimings: { default: false as boolean },
+  showMinimap: { default: false as boolean },
+  showGrid: { default: true as boolean },
+  // Transient UI state , not persisted.
+  showSearch: { default: false as boolean, persist: false },
+  /** Delay applying a node value change until the user commits it. */
+  delayedUpdate: { default: false as boolean },
+  /** Show value types inline on nodes. */
+  inlineTypes: { default: false as boolean },
+  /** Show values inline on nodes. */
+  inlineValues: { default: false as boolean },
+  connectOnClick: { default: true as boolean },
+  /**
+   * When connecting sockets of different-but-convertible value types,
+   * automatically insert a conversion node between them.
+   */
+  autoConvert: { default: true as boolean },
+  snapGrid: { default: false as boolean },
+  gridSize: { default: 15 as number },
+  generatorLocation: { default: 'panel' as GeneratorLocation }
+} satisfies Record<string, { default: unknown; persist?: boolean }>;
 
-export type GeneratorLocation = 'inline' | 'panel';
+type SettingsSchema = typeof SETTINGS;
+
+type SettingsState = {
+  [K in keyof SettingsSchema]: SettingsSchema[K]['default'];
+};
 
-export type SystemSettingsStore = {
-  debugMode: boolean;
-  showTimings: boolean;
-  showMinimap: boolean;
-  showGrid: boolean;
-  showSearch: boolean;
-  showMenu: boolean;
-  edgeType: EdgeType;
-  layoutType: LayoutType;
-  delayedUpdate: boolean;
-  inlineTypes: boolean;
-  inlineValues: boolean;
-  connectOnClick: boolean;
-  snapGrid: boolean;
-  gridSize: number;
-  generatorLocation: GeneratorLocation;
-  setDebugMode: (debugMode: boolean) => void;
-  setShowTimings: (showTimings: boolean) => void;
-  setShowMinimap: (showMinimap: boolean) => void;
-  setShowGrid: (showGrid: boolean) => void;
-  setShowSearch: (showSearch: boolean) => void;
-  setEdgeType: (edgeType: EdgeType) => void;
-  setLayoutType: (layoutType: LayoutType) => void;
-  setDelayedUpdate: (delayedUpdate: boolean) => void;
-  setInlineTypes: (inlineTypes: boolean) => void;
-  setInlineValues: (inlineValues: boolean) => void;
-  setConnectOnClick: (connectOnClick: boolean) => void;
-  setSnapGrid: (snapGrid: boolean) => void;
-  setGridSize: (gridSize: number) => void;
-  setGeneratorLocation: (generatorLocation: GeneratorLocation) => void;
+type SettingsSetters = {
+  [K in keyof SettingsSchema as `set${Capitalize<K & string>}`]: (
+    value: SettingsSchema[K]['default']
+  ) => void;
 };
 
+/**
+ * Generic accessors so plugin-contributed settings (dynamic keys not in the
+ * static {@link SETTINGS} schema) live in the same store as the typed built-ins.
+ * The auto-generated panel writes every row through {@link SystemSettingsStore.setSetting};
+ * the typed per-key setters above remain for existing typed consumers.
+ */
+type SettingsDynamicAccess = {
+  /** Dynamic plugin-contributed setting values, keyed by descriptor key. */
+  [key: string]: unknown;
+  /** Set any setting by key (used by the schema-driven panel + plugins). */
+  setSetting: (key: string, value: unknown) => void;
+};
+
+export type SystemSettingsStore = SettingsState &
+  SettingsSetters &
+  SettingsDynamicAccess;
+
+const setterName = (key: string): string =>
+  `set${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+/** Settings round-tripped to persisted storage (everything except `persist:false`). */
+export const PERSISTED_SETTING_KEYS = (
+  Object.entries(SETTINGS) as [keyof SettingsSchema, { persist?: boolean }][]
+)
+  .filter(([, spec]) => spec.persist !== false)
+  .map(([key]) => key);
+
 export const systemSettingsFactory = () =>
-  create<SystemSettingsStore>((set) => ({
-    edgeType: EDGE_TYPE.bezier,
-    layoutType: LAYOUT_TYPE.dagre,
-    debugMode: false,
-    showMenu: true,
-    showTimings: false,
-    showMinimap: false,
-    showGrid: true,
-    showSearch: false,
-    /**
-     * Whether to delay the update of a node when a value is changed
-     */
-    delayedUpdate: false,
-    /**
-     * Whether to show the types inline with the nodes
-     */
-    inlineTypes: false,
-    /**
-     * Whether to show the values inline with the nodes
-     */
-    inlineValues: false,
-    connectOnClick: true,
-    snapGrid: false,
-    gridSize: 15,
-    generatorLocation: 'panel',
-    setShowMenu: (showMenu: boolean) => set(() => ({ showMenu })),
-    setEdgeType: (edgeType: EdgeType) => set(() => ({ edgeType })),
-    setLayoutType: (layoutType: LayoutType) => set(() => ({ layoutType })),
-    setDebugMode: (debugMode: boolean) => set(() => ({ debugMode })),
-    setShowTimings: (showTimings: boolean) => set(() => ({ showTimings })),
-    setShowMinimap: (showMinimap: boolean) => set(() => ({ showMinimap })),
-    setShowGrid: (showGrid: boolean) => set(() => ({ showGrid })),
-    setShowSearch: (showSearch: boolean) => set(() => ({ showSearch })),
-    setDelayedUpdate: (delayedUpdate: boolean) =>
-      set(() => ({ delayedUpdate })),
-    setInlineTypes: (inlineTypes: boolean) => set(() => ({ inlineTypes })),
-    setInlineValues: (inlineValues: boolean) => set(() => ({ inlineValues })),
-    setConnectOnClick: (connectOnClick: boolean) =>
-      set(() => ({ connectOnClick })),
-    setSnapGrid: (snapGrid: boolean) => set(() => ({ snapGrid })),
-    setGridSize: (gridSize: number) => set(() => ({ gridSize })),
-    setGeneratorLocation: (generatorLocation: GeneratorLocation) =>
-      set(() => ({ generatorLocation }))
-  }));
+  create<SystemSettingsStore>((set) => {
+    const initial: Record<string, unknown> = {};
+    for (const [key, spec] of Object.entries(SETTINGS)) {
+      initial[key] = spec.default;
+      initial[setterName(key)] = (value: unknown) =>
+        set({ [key]: value } as Partial<SystemSettingsStore>);
+    }
+    // Generic setter for dynamic (plugin-contributed) keys and for the
+    // schema-driven panel, which writes every row by key.
+    initial.setSetting = (key: string, value: unknown) =>
+      set({ [key]: value } as Partial<SystemSettingsStore>);
+    return initial as SystemSettingsStore;
+  });

package/src/store/settingsSchema.ts

@@ -0,0 +1,210 @@
+import { createStore, type StoreApi } from 'zustand/vanilla';
+import type { FC } from 'react';
+import { EDGE_TYPE } from './settings';
+
+/**
+ * Schema-driven settings.
+ *
+ * The Settings panel is auto-generated from a registry of {@link SettingDescriptor}s
+ * rather than hand-coded JSX. Built-in settings are seeded as {@link DEFAULT_SETTINGS};
+ * plugins contribute their own via `system.registerSetting(...)`, and the panel
+ * renders them the same way — so a plugin can surface settings without forking
+ * the panel.
+ *
+ * Descriptors are intentionally plain data (everything except `render`/`when` is
+ * JSON-serializable), so a future declarative manifest `contributes.configuration`
+ * section can feed this same registry.
+ */
+
+export type SettingEnumOption = { value: string; label: string };
+
+/** Live values bag passed to a descriptor's {@link SettingDescriptorBase.when}. */
+export type SettingsValues = Record<string, unknown>;
+
+/** Props handed to a `type: 'custom'` descriptor's `render` component. */
+export type SettingControlProps = {
+  value: unknown;
+  setValue: (value: unknown) => void;
+  descriptor: SettingDescriptor;
+};
+
+type SettingDescriptorBase = {
+  /**
+   * Unique key. Built-ins are flat (`edgeType`) and match the value-store keys
+   * 1:1; plugin settings should be namespaced (`graphRunner.autoStart`) to avoid
+   * collisions.
+   */
+  key: string;
+  /** Category heading the row is grouped under, e.g. `"Layout"`. */
+  section: string;
+  /** Sort order within the section (falls back to registration order). */
+  order?: number;
+  /** Row label. */
+  title?: string;
+  /** Secondary description text under the label. */
+  description?: string;
+  /** Excluded from persisted settings when `false`. Defaults to `true`. */
+  persist?: boolean;
+  /** Hide the row unless this returns true for the current values. */
+  when?: (values: SettingsValues) => boolean;
+};
+
+export type SettingDescriptor =
+  | (SettingDescriptorBase & { type: 'boolean'; default: boolean })
+  | (SettingDescriptorBase & {
+      type: 'number';
+      default: number;
+      min?: number;
+      max?: number;
+      step?: number;
+    })
+  | (SettingDescriptorBase & {
+      type: 'string';
+      default: string;
+      placeholder?: string;
+    })
+  | (SettingDescriptorBase & {
+      type: 'enum';
+      default: string;
+      options: SettingEnumOption[];
+    })
+  | (SettingDescriptorBase & {
+      type: 'custom';
+      default?: unknown;
+      render: FC<SettingControlProps>;
+    });
+
+export type SettingsSchemaStore = {
+  /** Registered descriptors, in registration order. */
+  settings: SettingDescriptor[];
+  /** Section names in first-seen order, for stable display grouping. */
+  sectionOrder: string[];
+  registerSetting: (descriptor: SettingDescriptor) => void;
+  registerSettings: (descriptors: SettingDescriptor[]) => void;
+};
+
+const toOptions = (values: readonly string[]): SettingEnumOption[] =>
+  values.map((value) => ({ value, label: value }));
+
+/**
+ * Built-in editor settings, mirroring the previously hand-coded panel. Keys
+ * match the value-store keys in {@link file://./settings.ts} exactly, so typed
+ * consumers (`settings.edgeType`, …) are unaffected.
+ */
+export const DEFAULT_SETTINGS: SettingDescriptor[] = [
+  {
+    key: 'edgeType',
+    section: 'Layout',
+    type: 'enum',
+    default: EDGE_TYPE.bezier,
+    options: toOptions(Object.values(EDGE_TYPE)),
+    title: 'Edge Type',
+    description: 'Select the type of edge to use in the graph editor.'
+  },
+  {
+    key: 'inlineTypes',
+    section: 'Accessibility',
+    type: 'boolean',
+    default: false,
+    title: 'Show inline types',
+    description:
+      'Adds additional spans to help differentiate types for colorblind users.'
+  },
+  {
+    key: 'delayedUpdate',
+    section: 'Interaction',
+    type: 'boolean',
+    default: false,
+    title: 'Use delayed interaction',
+    description: 'Forces a user to click save to update port.'
+  },
+  {
+    key: 'connectOnClick',
+    section: 'Interaction',
+    type: 'boolean',
+    default: true,
+    title: 'Click to connect',
+    description: 'Allows you to quick connect nodes by clicking on the 2 port.'
+  },
+  {
+    key: 'autoConvert',
+    section: 'Interaction',
+    type: 'boolean',
+    default: true,
+    title: 'Auto-convert types',
+    description:
+      'When connecting different but convertible types, insert a conversion node automatically.'
+  },
+  {
+    key: 'showMinimap',
+    section: 'Display',
+    type: 'boolean',
+    default: false,
+    title: 'Show Minimap',
+    description: 'Shows the minimap in the graph editing area.'
+  },
+  {
+    key: 'showGrid',
+    section: 'Display',
+    type: 'boolean',
+    default: true,
+    title: 'Show Grid',
+    description: 'Shows the grid in the graph editing area.'
+  },
+  {
+    key: 'snapGrid',
+    section: 'Display',
+    type: 'boolean',
+    default: false,
+    title: 'Snap to Grid',
+    description: 'Snaps nodes to the grid while dragging.'
+  },
+  {
+    key: 'showTimings',
+    section: 'Performance',
+    type: 'boolean',
+    default: false,
+    title: 'Show execution time',
+    description: 'Shows how long it takes for a node to process.'
+  }
+];
+
+export const settingsSchemaStoreFactory = (
+  initial: SettingDescriptor[] = DEFAULT_SETTINGS
+): StoreApi<SettingsSchemaStore> =>
+  createStore<SettingsSchemaStore>((set, get) => {
+    const registerSetting = (descriptor: SettingDescriptor): void => {
+      const { settings, sectionOrder } = get();
+      if (settings.some((existing) => existing.key === descriptor.key)) {
+        console.warn(
+          `Setting "${descriptor.key}" is already registered; ignoring duplicate.`
+        );
+        return;
+      }
+      set({
+        settings: [...settings, descriptor],
+        sectionOrder: sectionOrder.includes(descriptor.section)
+          ? sectionOrder
+          : [...sectionOrder, descriptor.section]
+      });
+    };
+
+    // Seed the built-in descriptors as the starting state.
+    const settings: SettingDescriptor[] = [];
+    const sectionOrder: string[] = [];
+    for (const descriptor of initial) {
+      if (settings.some((existing) => existing.key === descriptor.key))
+        continue;
+      settings.push(descriptor);
+      if (!sectionOrder.includes(descriptor.section)) {
+        sectionOrder.push(descriptor.section);
+      }
+    }
+
+    return {
+      settings,
+      sectionOrder,
+      registerSetting,
+      registerSettings: (descriptors) => descriptors.forEach(registerSetting)
+    };
+  });

package/src/store/tabs.ts

@@ -1,5 +1,6 @@
 import type { BoxBase, LayoutBase, PanelBase, TabBase } from 'rc-dock';
 import { create } from 'zustand';
+import { isGraphTabId } from '@/components/layoutController/utils';
 
 function isPanelBase(value: BoxBase | PanelBase): value is PanelBase {
   return Array.isArray((value as PanelBase).tabs);
@@ -120,6 +121,9 @@ const defaultLayout: LayoutBase = {
                     children: [
                       {
                         tabs: [
+                          {
+                            id: 'graphProperties'
+                          },
                           {
                             id: 'variables'
                           },
@@ -226,7 +230,7 @@ export const tabStoreFactory = () =>
 
         // 2) Otherwise, insert it into a target panel (prefer explicit panelId).
         const targetPanelId =
-          options?.panelId ?? (tabId === 'graph' ? 'graphs' : undefined);
+          options?.panelId ?? (isGraphTabId(tabId) ? 'graphs' : undefined);
 
         if (targetPanelId) {
           const res = recurseUpsertTabInPanelId(

package/src/store/traces.ts

@@ -1,6 +1,6 @@
 import type { Engine, INode } from '@kiberon-labs/behave-graph';
 import { create } from 'zustand';
-import type { System } from '@/system';
+import type { GraphSession } from '@/system/graphSession';
 
 export type TraceSpan = {
   id: number;
@@ -74,11 +74,11 @@ export type TraceStore = {
   connectEngine: (engine?: Engine) => void;
   recordNodeStart: (node: INode, startTime?: number) => void;
   recordNodeEnd: (node: INode, endTime?: number) => void;
-  addSpan: (span: Omit<TraceSpan, 'id'>) => void;
+  addSpan: (span: Omit<TraceSpan, 'id' | 'lane'> & { lane?: number }) => void;
   updateSpan: (nodeId: string, updates: Partial<TraceSpan>) => void;
 };
 
-export const traceStoreFactory = (_: System) => {
+export const traceStoreFactory = (_: GraphSession) => {
   let connectedEngine: Engine | undefined;
   let onStart: ((node: INode) => void) | undefined;
   let onEnd: ((node: INode) => void) | undefined;

package/src/system/graph.ts

@@ -1,5 +1,5 @@
 import type { Viewport } from 'reactflow';
-import type { System } from './system';
+import type { GraphSession } from './graphSession';
 import type { Edge } from 'reactflow';
 import type { UIGraphJSON } from '@/types/graph';
 
@@ -9,12 +9,10 @@ import type { UIGraphJSON } from '@/types/graph';
  */
 export class Graph {
   public readonly viewports: Viewport[] = [];
-  private sys: System;
+  private sys: GraphSession;
 
-  protected annotations: { [key: string]: any } = {};
-
-  constructor(system: System) {
-    this.sys = system;
+  constructor(session: GraphSession) {
+    this.sys = session;
   }
 
   setViewport(index: number, viewport: Viewport) {
@@ -83,13 +81,14 @@ export class Graph {
   }
 
   serialize(): UIGraphJSON {
+    const meta = this.sys.metaStore.getState();
     return {
       v: '1.0.0',
-      name: 'Untitled Graph',
+      name: meta.name,
       user: {
         viewport: this.viewports[0] || { x: 0, y: 0, zoom: 1 }
       },
-      annotations: this.annotations,
+      annotations: { ...meta.metadata },
       data: {
         layers: this.sys.layerStore.getState().serialize()
       },
@@ -100,14 +99,11 @@ export class Graph {
   }
 
   getAnnotations() {
-    return { ...this.annotations };
+    return { ...this.sys.metaStore.getState().metadata };
   }
 
   setAnnotations(annotations: { [key: string]: any }) {
-    this.annotations = {
-      ...this.annotations,
-      ...annotations
-    };
+    this.sys.metaStore.getState().mergeMetadata(annotations);
     this.sys.pubsub.publish('graphAnnotationsChanged', this.getAnnotations());
   }
 
@@ -115,7 +111,8 @@ export class Graph {
     //Load nodes
     this.sys.nodeStore.getState().setNodes(data.nodes);
     this.sys.edgeStore.getState().setEdges(data.edges);
-    this.annotations = data.annotations || {};
+    this.sys.metaStore.getState().setMetadata(data.annotations || {});
+    if (data.name) this.sys.metaStore.getState().setName(data.name);
     this.sys.layerStore.getState().deserialize(data.data?.layers);
 
     // Restore viewport

package/src/system/graphSession.ts

@@ -0,0 +1,172 @@
+import { type StoreApi } from 'zustand';
+import { UndoManager } from './undoRedo';
+import { PubSub } from './pubsub';
+import { Graph } from './graph';
+import type { System, GraphPubSys } from './system';
+import {
+  edgeStoreFactory,
+  flowStoreFactory,
+  nodeStoreFactory,
+  type EdgeStore,
+  type FlowStore,
+  type NodeStore
+} from '@/store/flow';
+import { controlsStoreFactory, type ControlsStore } from '@/store/controls';
+import { variableStoreFactory, type VariableStore } from '@/store/variables';
+import { selectionStoreFactory, type SelectionStore } from '@/store/selection';
+import { refStoreFactory, type RefStore } from '@/store/refs';
+import { actionStoreFactory, type ActionStore } from '@/store/actions';
+import { traceStoreFactory, type TraceStore } from '@/store/traces';
+import { eventsStoreFactory, type EventsStore } from '@/store/events';
+import { layerStoreFactory, type LayerStore } from '@/store/layers';
+import { logStoreFactory, type LogStore } from '@/store/logs';
+import { graphMetaStoreFactory, type GraphMetaStore } from '@/store/graphMeta';
+import type { UIGraphJSON } from '@/types/graph';
+
+/**
+ * Augmentable surface for per-graph state contributed by plugins. Mirrors
+ * {@link ISystem} at the editor level: a plugin adds typed properties to every
+ * graph by augmenting this interface and assigning them via
+ * {@link GraphSession.decorate} from inside a session extension.
+ *
+ * @example
+ * declare module '@/system/graphSession' {
+ *   interface IGraphSession {
+ *     myController?: MyController;
+ *   }
+ * }
+ */
+export interface IGraphSession {}
+
+/**
+ * Merge the augmentable surface into the class instance type. Declaration
+ * merging (same-named interface + class) makes plugin-added members , set via
+ * {@link GraphSession.decorate} , readable as `session.x`, which `implements`
+ * alone would NOT provide.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface GraphSession extends IGraphSession {}
+
+/**
+ * A single open graph. Owns all per-graph state , nodes, edges, variables,
+ * selection, traces, layers, logs, undo history and a private pubsub , so that
+ * multiple graphs can be open simultaneously in complete isolation.
+ *
+ * Shared, editor-level resources (registry, specs, settings, notifications, ...)
+ * are reached through {@link GraphSession.editor}.
+ *
+ * Per-graph state contributed by editor plugins is attached on creation via
+ * session extensions (`system.registerSessionExtension`), which may register
+ * teardown through {@link GraphSession.onDispose}.
+ */
+export class GraphSession {
+  public readonly id: string;
+  public readonly editor: System;
+  /** Reactive graph-level properties (name + metadata). */
+  public readonly metaStore: StoreApi<GraphMetaStore>;
+  public readonly pubsub = new PubSub<GraphPubSys>();
+  public readonly undoManager = new UndoManager();
+
+  /** Display name, used as the graph tab title. Backed by {@link metaStore}. */
+  get name(): string {
+    return this.metaStore.getState().name;
+  }
+  set name(value: string) {
+    this.metaStore.getState().setName(value);
+  }
+
+  public readonly controlStore: StoreApi<ControlsStore>;
+  public readonly variableStore: StoreApi<VariableStore>;
+  public readonly refStore: StoreApi<RefStore>;
+  public readonly logsStore: StoreApi<LogStore>;
+  public readonly eventsStore: StoreApi<EventsStore>;
+  public readonly nodeStore: StoreApi<NodeStore>;
+  public readonly edgeStore: StoreApi<EdgeStore>;
+  public readonly flowStore: StoreApi<FlowStore>;
+  public readonly selectionStore: StoreApi<SelectionStore>;
+  public readonly actionStore: StoreApi<ActionStore>;
+  public readonly layerStore: StoreApi<LayerStore>;
+  public readonly traceStore: StoreApi<TraceStore>;
+  public readonly graph: Graph;
+
+  /** Cleanups registered by session extensions, run (LIFO) on {@link dispose}. */
+  private readonly disposers: Array<() => void> = [];
+
+  constructor(editor: System, id = 'graph', name = 'Graph') {
+    this.id = id;
+    this.editor = editor;
+    this.metaStore = graphMetaStoreFactory(name);
+
+    // Construction order preserves the dependency wiring of the old System ctor.
+    this.controlStore = controlsStoreFactory();
+    this.variableStore = variableStoreFactory();
+    this.refStore = refStoreFactory();
+    this.logsStore = logStoreFactory();
+    this.eventsStore = eventsStoreFactory();
+    this.nodeStore = nodeStoreFactory(this);
+    this.edgeStore = edgeStoreFactory(this);
+    this.flowStore = flowStoreFactory(this);
+    this.selectionStore = selectionStoreFactory(this);
+    this.actionStore = actionStoreFactory(this);
+    this.layerStore = layerStoreFactory(this);
+    this.traceStore = traceStoreFactory(this);
+    this.graph = new Graph(this);
+
+    // Per-session behaviours (alignment, ...) are contributed by opt-in plugins
+    // via system.registerSessionExtension(...), not wired here. See the
+    // alignment plugin (`@/plugin/alignment`).
+  }
+
+  /**
+   * Convenience access to the shared editor notifications service.
+   */
+  get notifications() {
+    return this.editor.notifications;
+  }
+
+  /**
+   * Attach a plugin-contributed property to this session. The companion to the
+   * {@link IGraphSession} augmentation; mirrors {@link System.decorate}.
+   */
+  decorate<K extends keyof IGraphSession>(
+    name: K,
+    val: IGraphSession[K]
+  ): void {
+    (this as IGraphSession)[name] = val;
+  }
+
+  /**
+   * Register a cleanup to run when this session is disposed. Session extensions
+   * use this (via their returned cleanup) to tear down per-graph state they
+   * attached. Cleanups run in reverse registration order.
+   */
+  onDispose(cleanup: () => void): void {
+    this.disposers.push(cleanup);
+  }
+
+  serialize(): UIGraphJSON {
+    return this.graph.serialize();
+  }
+
+  /**
+   * Tear down this session's reactive wiring. Called when its tab is closed so
+   * its pubsub subscriptions and trace flush loop don't leak. Extension-supplied
+   * cleanups run first (LIFO), then the built-in teardown.
+   */
+  dispose(): void {
+    for (let i = this.disposers.length - 1; i >= 0; i--) {
+      try {
+        this.disposers[i]!();
+      } catch (err) {
+        console.error('GraphSession disposer failed', err);
+      }
+    }
+    this.disposers.length = 0;
+
+    // Per-session plugin state (e.g. the graph runner's runController) is torn
+    // down by the extension cleanups registered above via onDispose , core no
+    // longer reaches into plugin-owned fields here.
+    this.traceStore.getState().connectEngine(undefined);
+    this.pubsub.clearAllSubscriptions();
+  }
+}

package/src/system/index.ts

@@ -1,3 +1,6 @@
 export * from './system';
+export * from './persistence';
+export * from './graphSession';
 export * from './provider';
+export * from './plugin';
 export { subscribeToRef, useRefFromStore } from '@/store/refs';