symbiote-ui 0.3.0-alpha.4

package/core/GraphMermaid.js

@@ -0,0 +1,348 @@
+/**
+ * GraphMermaid — bidirectional Mermaid ↔ graph serialization
+ *
+ * Converts NodeEditor state to Mermaid flowchart syntax and back.
+ * Supports shapes, labeled connections, and subgraphs (frames).
+ *
+ * Mermaid shape mapping:
+ *   circle  → ((label))
+ *   diamond → {label}
+ *   pill    → ([label])
+ *   rect    → [label]
+ *   comment → >label]
+ *
+ * @module symbiote-node/core/GraphMermaid
+ */
+
+
+const SHAPE_TO_MERMAID = {
+  circle: (id, label) => `${id}((${label}))`,
+  diamond: (id, label) => `${id}{${label}}`,
+  pill: (id, label) => `${id}([${label}])`,
+  rect: (id, label) => `${id}[${label}]`,
+  comment: (id, label) => `${id}>${label}]`,
+};
+
+/**
+ * Pattern matchers for Mermaid node shapes.
+ * Order matters — more specific patterns first.
+ * @type {Array<{re: RegExp, shape: string}>}
+ */
+const MERMAID_SHAPE_PATTERNS = [
+  { re: /^(\w+)\(\((.+?)\)\)$/, shape: 'circle' },
+  { re: /^(\w+)\(\[(.+?)\]\)$/, shape: 'pill' },
+  { re: /^(\w+)\{(.+?)\}$/, shape: 'diamond' },
+  { re: /^(\w+)>(.+?)\]$/, shape: 'comment' },
+  { re: /^(\w+)\[(.+?)\]$/, shape: 'rect' },
+];
+
+
+/**
+ * Arrow patterns with optional label.
+ * Supports: -->, --->, -->|label|, -- label -->
+ * @type {Array<{re: RegExp}>}
+ */
+const ARROW_PATTERNS = [
+
+  /^(.+?)\s*-->\|([^|]*)\|\s*(.+)$/,
+
+  /^(.+?)\s*--\s+(.+?)\s+-->\s*(.+)$/,
+
+  /^(.+?)\s*-->\s*(.+)$/,
+];
+
+/**
+ * Parse a node reference that might include inline shape definition.
+ *
+ * @param {string} raw - e.g. "trigger((Job Event))" or just "trigger"
+ * @returns {{ id: string, label: string|null, shape: string|null }}
+ */
+function parseNodeRef(raw) {
+  let trimmed = raw.trim();
+  for (const { re, shape } of MERMAID_SHAPE_PATTERNS) {
+    let m = trimmed.match(re);
+    if (m) return { id: m[1], label: m[2], shape };
+  }
+
+  return { id: trimmed, label: null, shape: null };
+}
+
+/**
+ * Convert a NodeEditor to Mermaid flowchart syntax
+ *
+ * @param {import('./Editor.js').NodeEditor} editor
+ * @param {object} [options]
+ * @param {'LR'|'TB'|'RL'|'BT'} [options.direction='LR']
+ * @returns {string}
+ */
+export function editorToMermaid(editor, options = {}) {
+  let { direction = 'LR' } = options;
+  let lines = [];
+
+  lines.push(`graph ${direction}`);
+
+
+  let frames = editor.getFrames();
+  let nodeToFrame = new Map();
+
+
+  let framedNodes = new Map();
+  let freeNodes = [];
+
+
+  let allNodes = editor.getNodes();
+  let allConnections = editor.getConnections();
+
+
+  if (frames.length) {
+
+
+    for (const frame of frames) {
+      let nodeIds = frame._nodeIds || [];
+      if (nodeIds.length) {
+        for (const nid of nodeIds) {
+          nodeToFrame.set(nid, frame);
+        }
+      }
+    }
+  }
+
+
+  for (const node of allNodes) {
+    if (nodeToFrame.has(node.id)) {
+      let frame = nodeToFrame.get(node.id);
+      if (!framedNodes.has(frame.id)) framedNodes.set(frame.id, []);
+      framedNodes.get(frame.id).push(node);
+    } else {
+      freeNodes.push(node);
+    }
+  }
+
+
+  for (const node of freeNodes) {
+    lines.push('  ' + nodeToMermaid(node));
+  }
+
+
+  if (framedNodes.size === 0 && frames.length > 0) {
+
+    if (freeNodes.length === 0) {
+      for (const node of allNodes) {
+        lines.push('  ' + nodeToMermaid(node));
+      }
+    }
+
+    for (const frame of frames) {
+      lines.push('');
+      lines.push(`  subgraph ${sanitizeId(frame.label)}["${frame.label}"]`);
+      lines.push('    direction TB');
+      lines.push('  end');
+    }
+  } else {
+
+    for (const [frameId, nodes] of framedNodes) {
+      let frame = frames.find((f) => f.id === frameId);
+      if (!frame) continue;
+      lines.push('');
+      lines.push(`  subgraph ${sanitizeId(frame.label)}["${frame.label}"]`);
+      lines.push('    direction TB');
+      for (const node of nodes) {
+        lines.push('    ' + nodeToMermaid(node));
+      }
+      lines.push('  end');
+    }
+  }
+
+
+  lines.push('');
+  for (const conn of allConnections) {
+    let label = conn.out === 'exec' ? '' : conn.out;
+    if (label) {
+      lines.push(`  ${conn.from} -->|${label}| ${conn.to}`);
+    } else {
+      lines.push(`  ${conn.from} --> ${conn.to}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Convert a single node to Mermaid declaration
+ * @param {import('./Node.js').Node} node
+ * @returns {string}
+ */
+function nodeToMermaid(node) {
+  let shapeFn = SHAPE_TO_MERMAID[node.shape] || SHAPE_TO_MERMAID.rect;
+  return shapeFn(node.id, node.label);
+}
+
+/**
+ * Sanitize a string for use as Mermaid subgraph ID
+ * @param {string} str
+ * @returns {string}
+ */
+function sanitizeId(str) {
+  return str.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+
+/**
+ * Parse Mermaid flowchart text into graph data structure.
+ * Supports: node shapes, labeled arrows, subgraphs.
+ *
+ * @param {string} text
+ * @returns {{ nodes: Array, connections: Array, frames: Array, direction: string }}
+ */
+export function mermaidToGraph(text) {
+  let nodes = new Map();
+  let connections = [];
+  let frames = [];
+  let frameStack = [];
+
+  let direction = 'LR';
+
+  /**
+   * Register a node from a parsed reference
+   * @param {{ id: string, label: string|null, shape: string|null }} ref
+   */
+  function registerNode(ref) {
+    if (!nodes.has(ref.id)) {
+      nodes.set(ref.id, {
+        id: ref.id,
+        name: ref.label || ref.id,
+        type: 'default',
+        shape: ref.shape || 'rect',
+        category: 'default',
+      });
+    } else if (ref.label && !nodes.get(ref.id).name) {
+
+      let existing = nodes.get(ref.id);
+      if (existing.name === existing.id) {
+        existing.name = ref.label;
+      }
+      if (ref.shape) existing.shape = ref.shape;
+    }
+
+    if (frameStack.length > 0) {
+      let currentFrame = frameStack[frameStack.length - 1];
+      if (!currentFrame._nodeIds) currentFrame._nodeIds = [];
+      if (!currentFrame._nodeIds.includes(ref.id)) {
+        currentFrame._nodeIds.push(ref.id);
+      }
+    }
+  }
+
+  for (const rawLine of text.split('\n')) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('%%')) continue;
+
+
+    let dirMatch = line.match(/^graph\s+(LR|RL|TB|BT|TD)\s*$/);
+    if (dirMatch) {
+      direction = dirMatch[1] === 'TD' ? 'TB' : dirMatch[1];
+      continue;
+    }
+
+
+    let flowMatch = line.match(/^flowchart\s+(LR|RL|TB|BT|TD)\s*$/);
+    if (flowMatch) {
+      direction = flowMatch[1] === 'TD' ? 'TB' : flowMatch[1];
+      continue;
+    }
+
+
+    let subMatch = line.match(/^subgraph\s+(\w+)(?:\["(.+?)"\])?\s*$/);
+    if (subMatch) {
+      let frame = {
+        label: subMatch[2] || subMatch[1],
+        color: '#4a9eff',
+        x: 0,
+        y: 0,
+        width: 400,
+        height: 300,
+        _nodeIds: [],
+      };
+      frameStack.push(frame);
+      frames.push(frame);
+      continue;
+    }
+
+
+    if (line === 'end') {
+      frameStack.pop();
+      continue;
+    }
+
+
+    if (line.match(/^direction\s+(LR|RL|TB|BT|TD)$/)) continue;
+
+
+    let matched = false;
+    for (const pattern of ARROW_PATTERNS) {
+      let m = line.match(pattern);
+      if (m) {
+        matched = true;
+        if (m.length === 4) {
+
+          let source = parseNodeRef(m[1]);
+          let label = m[2].trim();
+          let target = parseNodeRef(m[3]);
+          registerNode(source);
+          registerNode(target);
+          connections.push({
+            from: source.id,
+            out: label || 'exec',
+            to: target.id,
+            in: 'exec',
+          });
+        } else if (m.length === 3) {
+
+          let source = parseNodeRef(m[1]);
+          let target = parseNodeRef(m[2]);
+          registerNode(source);
+          registerNode(target);
+          connections.push({
+            from: source.id,
+            out: 'exec',
+            to: target.id,
+            in: 'exec',
+          });
+        }
+        break;
+      }
+    }
+
+
+    if (!matched) {
+
+      let parts = line.split(/\s*&\s*/);
+      for (const part of parts) {
+        let ref = parseNodeRef(part.trim());
+        if (
+          ref.id &&
+          ref.id !== 'end' &&
+          !ref.id.startsWith('style') &&
+          !ref.id.startsWith('class')
+        ) {
+          registerNode(ref);
+        }
+      }
+    }
+  }
+
+  return {
+    nodes: [...nodes.values()],
+    connections,
+    frames: frames.map((f) => ({
+      label: f.label,
+      color: f.color,
+      x: f.x,
+      y: f.y,
+      width: f.width,
+      height: f.height,
+    })),
+    direction,
+  };
+}
+
+export { editorToMermaid as default };

package/core/GraphText.js

@@ -0,0 +1,228 @@
+/**
+ * GraphText — bidirectional text ↔ graph serialization
+ *
+ * Converts NodeEditor state to human-readable text and back.
+ * Useful for debugging, LLM-based generation, and quick iteration.
+ *
+ * Text format:
+ *   NODES:
+ *   [○ trigger] Job Event: RU (queue/job-event) shape=circle
+ *   [◇ switch_status] Status? (flow/switch) shape=diamond
+ *
+ *   CONNECTIONS:
+ *   trigger.exec --> switch_status.exec
+ *   switch_status.created --> fmt_created.exec
+ *
+ *   FRAMES:
+ *   [Formatters] color=#5cd87a x=490 y=-10 w=260 h=520
+ *
+ * @module symbiote-node/core/GraphText
+ */
+
+const SHAPE_ICONS = {
+  circle: '○',
+  diamond: '◇',
+  pill: '⊃',
+  rect: '□',
+  comment: '✎',
+};
+
+const ICON_SHAPES = Object.fromEntries(Object.entries(SHAPE_ICONS).map(([k, v]) => [v, k]));
+
+/**
+ * Convert a NodeEditor to human-readable text
+ *
+ * @param {import('./Editor.js').NodeEditor} editor
+ * @param {Object<string, number[]>} [positions] - {nodeId: [x, y]}
+ * @returns {string}
+ */
+export function editorToText(editor, positions = {}) {
+  let lines = [];
+
+
+  lines.push('NODES:');
+  for (const node of editor.getNodes()) {
+    let icon = SHAPE_ICONS[node.shape] || '□';
+    let ins = Object.keys(node.inputs);
+    let outs = Object.keys(node.outputs);
+    let line = `[${icon} ${node.id}] ${node.label} (${node.type})`;
+    if (node.shape !== 'rect') line += ` shape=${node.shape}`;
+    if (node.category !== 'default') line += ` cat=${node.category}`;
+    if (ins.length) line += ` in=[${ins.join(',')}]`;
+    if (outs.length) line += ` out=[${outs.join(',')}]`;
+    let pos = positions[node.id];
+    if (pos) line += ` @${pos[0]},${pos[1]}`;
+    lines.push('  ' + line);
+  }
+
+
+  lines.push('');
+  lines.push('CONNECTIONS:');
+  for (const conn of editor.getConnections()) {
+    lines.push(`  ${conn.from}.${conn.out} --> ${conn.to}.${conn.in}`);
+  }
+
+
+  let frames = editor.getFrames();
+  if (frames.length) {
+    lines.push('');
+    lines.push('FRAMES:');
+    for (const frame of frames) {
+      lines.push(
+        `  [${frame.label}] color=${frame.color} x=${frame.x} y=${frame.y} w=${frame.width} h=${frame.height}`
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Parse text representation back into graph data structure.
+ * Returns plain objects suitable for building a NodeEditor.
+ *
+ * @param {string} text
+ * @returns {{ nodes: Array, connections: Array, frames: Array, positions: Object }}
+ */
+export function textToGraph(text) {
+  let nodes = [];
+  let connections = [];
+  let frames = [];
+  let positions = {};
+
+  let section = '';
+  for (const raw of text.split('\n')) {
+    let line = raw.trim();
+    if (!line) continue;
+
+    if (line === 'NODES:') {
+      section = 'nodes';
+      continue;
+    }
+    if (line === 'CONNECTIONS:') {
+      section = 'connections';
+      continue;
+    }
+    if (line === 'FRAMES:') {
+      section = 'frames';
+      continue;
+    }
+
+    if (section === 'nodes') {
+
+      let m = line.match(/^\[(.)\s+(\S+)\]\s+(.+?)\s+\(([^)]+)\)(.*)$/);
+      if (!m) continue;
+
+      let [, shapeIcon, id, name, type, rest] = m;
+      let shape = ICON_SHAPES[shapeIcon] || 'rect';
+      let category = rest.match(/cat=(\S+)/)?.[1] || 'default';
+      let posMatch = rest.match(/@(-?\d+),(-?\d+)/);
+
+      nodes.push({ id, name, type, shape, category });
+      if (posMatch) {
+        positions[id] = [parseInt(posMatch[1]), parseInt(posMatch[2])];
+      }
+    }
+
+    if (section === 'connections') {
+
+      let m = line.match(/^(\S+)\.(\S+)\s+-->\s+(\S+)\.(\S+)$/);
+      if (!m) continue;
+      let [, from, out, to, inp] = m;
+      connections.push({ from, out, to, in: inp });
+    }
+
+    if (section === 'frames') {
+
+      let m = line.match(/^\[([^\]]+)\]\s+(.*)$/);
+      if (!m) continue;
+      let [, label, rest] = m;
+      let color = rest.match(/color=(\S+)/)?.[1] || '#4a9eff';
+      let x = parseInt(rest.match(/x=(-?\d+)/)?.[1] || '0');
+      let y = parseInt(rest.match(/y=(-?\d+)/)?.[1] || '0');
+      let w = parseInt(rest.match(/w=(\d+)/)?.[1] || '400');
+      let h = parseInt(rest.match(/h=(\d+)/)?.[1] || '300');
+      frames.push({ label, color, x, y, width: w, height: h });
+    }
+  }
+
+  return { nodes, connections, frames, positions };
+}
+
+/**
+ * Build a NodeEditor from text representation
+ *
+ * @param {string} text
+ * @param {import('./Editor.js').NodeEditor} editor
+ * @param {{ Socket: Function, Node: Function, Input: Function, Output: Function, Connection: Function, Frame: Function }} classes
+ * @returns {{ editor: import('./Editor.js').NodeEditor, positions: Object }}
+ */
+export function textToEditor(text, editor, classes) {
+  let { Node, Connection, Socket, Input, Output, Frame } = classes;
+  let { nodes, connections, frames, positions } = textToGraph(text);
+
+  let execSocket = new Socket('exec', { color: '#ffffff' });
+  let dataSocket = new Socket('data', { color: '#5cb8ff' });
+  let nodeMap = new Map();
+
+
+  let inPorts = {};
+  let outPorts = {};
+  for (const conn of connections) {
+    if (!inPorts[conn.to]) inPorts[conn.to] = new Set();
+    inPorts[conn.to].add(conn.in);
+    if (!outPorts[conn.from]) outPorts[conn.from] = new Set();
+    outPorts[conn.from].add(conn.out);
+  }
+
+  for (const n of nodes) {
+    let node = new Node(n.name, {
+      id: n.id,
+      type: n.type,
+      category: n.category,
+      shape: n.shape,
+    });
+
+    let ins = inPorts[n.id] || new Set();
+    let outs = outPorts[n.id] || new Set();
+
+    for (const port of ins) {
+      let isExec = port === 'exec' || port === 'trigger';
+      node.addInput(port, new Input(isExec ? execSocket : dataSocket, port === 'exec' ? '' : port));
+    }
+    for (const port of outs) {
+      let isExec = port === 'exec' || port === 'trigger';
+      node.addOutput(
+        port,
+        new Output(isExec ? execSocket : dataSocket, port === 'exec' ? '' : port)
+      );
+    }
+
+    editor.addNode(node);
+    nodeMap.set(n.id, node);
+  }
+
+  for (const conn of connections) {
+    let fromNode = nodeMap.get(conn.from);
+    let toNode = nodeMap.get(conn.to);
+    if (fromNode && toNode) {
+      editor.addConnection(new Connection(fromNode, conn.out, toNode, conn.in));
+    }
+  }
+
+  for (const f of frames) {
+    editor.addFrame(
+      new Frame(f.label, {
+        x: f.x,
+        y: f.y,
+        width: f.width,
+        height: f.height,
+        color: f.color,
+      })
+    );
+  }
+
+  return { editor, positions };
+}
+
+export { editorToText as default };

package/core/Node.js

@@ -0,0 +1,145 @@
+/**
+ * Node — graph node with typed ports and controls
+ *
+ * Compatible with symbiote-node GraphNode structure.
+ * Ports are explicit objects (unlike symbiote-node where they're implicit).
+ *
+ * @module symbiote-node/core/Node
+ */
+
+import { uid } from './Socket.js';
+
+export class Node {
+  /**
+   * @param {string} label - Display name
+   * @param {object} [options]
+   * @param {string} [options.id] - Custom ID (default: auto-generated)
+   * @param {string} [options.type] - Node type identifier (e.g. 'ai/llm')
+   * @param {string} [options.category] - Category for styling (server/instance/control)
+   * @param {string} [options.shape] - Shape name (rect/pill/circle/diamond/comment)
+   * @param {string} [options.icon] - Material icon name for visual rendering
+   */
+  constructor(label, options = {}) {
+    /** @type {string} */
+    this.id = options.id || uid('nd');
+
+    /** @type {string} */
+    this.label = label;
+
+    /** @type {string} */
+    this.type = options.type || 'default';
+
+    /** @type {string} */
+    this.category = options.category || 'default';
+
+    /** @type {string} */
+    this.shape = options.shape || 'rect';
+
+    /** @type {string} */
+    this.icon = options.icon || '';
+
+    /** @type {Object<string, Input>} */
+    this.inputs = {};
+
+    /** @type {Object<string, Output>} */
+    this.outputs = {};
+
+    /** @type {Object<string, import('./Socket.js').Control>} */
+    this.controls = {};
+
+    /** @type {Object<string, *>} */
+    this.params = {};
+
+    /** @type {boolean} */
+    this.selected = false;
+
+    /** @type {boolean} */
+    this.collapsed = false;
+
+    /** @type {boolean} */
+    this.muted = false;
+  }
+
+  /**
+   * Check if input exists
+   * @param {string} key
+   * @returns {boolean}
+   */
+  hasInput(key) {
+    return key in this.inputs;
+  }
+
+  /**
+   * Add input port
+   * @param {string} key - Port key
+   * @param {Input} input - Input instance
+   */
+  addInput(key, input) {
+    if (this.hasInput(key)) throw new Error(`input '${key}' already exists`);
+    this.inputs[key] = input;
+  }
+
+  /**
+   * Remove input port
+   * @param {string} key
+   */
+  removeInput(key) {
+    delete this.inputs[key];
+  }
+
+  /**
+   * Check if output exists
+   * @param {string} key
+   * @returns {boolean}
+   */
+  hasOutput(key) {
+    return key in this.outputs;
+  }
+
+  /**
+   * Add output port
+   * @param {string} key - Port key
+   * @param {Output} output - Output instance
+   */
+  addOutput(key, output) {
+    if (this.hasOutput(key)) throw new Error(`output '${key}' already exists`);
+    this.outputs[key] = output;
+  }
+
+  /**
+   * Remove output port
+   * @param {string} key
+   */
+  removeOutput(key) {
+    delete this.outputs[key];
+  }
+
+  /**
+   * Check if control exists
+   * @param {string} key
+   * @returns {boolean}
+   */
+  hasControl(key) {
+    return key in this.controls;
+  }
+
+  /**
+   * Add control widget
+   * @param {string} key
+   * @param {import('./Socket.js').Control} control
+   */
+  addControl(key, control) {
+    if (this.hasControl(key)) throw new Error(`control '${key}' already exists`);
+    this.controls[key] = control;
+  }
+
+  /**
+   * Remove control widget
+   * @param {string} key
+   */
+  removeControl(key) {
+    delete this.controls[key];
+  }
+}
+
+export { Node as default };