@principal-ai/principal-view-core 0.5.6

package/src/types/path-based-config.ts

@@ -0,0 +1,281 @@
+/**
+ * Path-based configuration extensions for Milestone 1 & 2
+ *
+ * These types extend the core GraphConfiguration to support:
+ * - Path-based log association (Milestone 1)
+ * - Action pattern refinement (Milestone 2)
+ */
+
+/**
+ * Log levels (matches logger package)
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Extended node type definition with source path mapping
+ */
+export interface PathBasedNodeTypeDefinition {
+  /** Base node type properties (inherited from NodeTypeDefinition) */
+  shape: 'circle' | 'rectangle' | 'hexagon' | 'diamond' | 'custom';
+  icon?: string;
+  color?: string;
+  size?: { width: number; height: number };
+  dataSchema: {
+    [field: string]: {
+      type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+      required?: boolean;
+      displayInLabel?: boolean;
+    };
+  };
+  states?: Record<
+    string,
+    {
+      color?: string;
+      icon?: string;
+      label?: string;
+    }
+  >;
+  layout?: {
+    layer?: number;
+    cluster?: string;
+  };
+
+  /** Manual position for 'manual' layout mode */
+  position?: { x: number; y: number };
+
+  /** MILESTONE 1: Source path mapping */
+  sources?: string[];  // e.g., ["lib/lock-manager.ts", "lib/**/*.ts"]
+
+  /** MILESTONE 2: Optional action patterns for refinement */
+  actions?: ActionPattern[];
+}
+
+/**
+ * Action pattern for extracting structured events from logs (Milestone 2)
+ */
+export interface ActionPattern {
+  /** Regex pattern to match log message (with named capture groups) */
+  pattern: string;
+
+  /** Event type to emit when pattern matches */
+  event: string;
+
+  /** Component state to transition to (optional) */
+  state?: string;
+
+  /** Metadata template - extracts data from capture groups */
+  metadata?: Record<string, string>;  // e.g., { lockId: "$lockId" }
+
+  /** Whether this action should trigger edge animations */
+  triggerEdges?: string[];  // Edge IDs or patterns
+}
+
+/**
+ * Extended edge definition with action-based activation (Milestone 2)
+ */
+export interface PathBasedEdgeTypeDefinition {
+  /** Base edge properties */
+  style: 'solid' | 'dashed' | 'dotted' | 'animated';
+  color?: string;
+  width?: number;
+  directed?: boolean;
+  animated?: boolean;
+  label?: {
+    field?: string;
+    position?: 'start' | 'middle' | 'end';
+  };
+  animation?: {
+    type: 'flow' | 'pulse' | 'particle' | 'glow';
+    duration?: number;
+    color?: string;
+  };
+
+  /** MILESTONE 2: Edge activation triggers */
+  activatedBy?: EdgeActivationTrigger[];
+}
+
+/**
+ * Configuration for activating edges based on component actions
+ */
+export interface EdgeActivationTrigger {
+  /** Action that triggers this edge animation */
+  action: string;
+
+  /** Animation type to play */
+  animation: 'flow' | 'particle' | 'pulse' | 'glow';
+
+  /** Animation direction */
+  direction?: 'forward' | 'backward' | 'bidirectional';
+
+  /** Animation duration in milliseconds */
+  duration?: number;
+}
+
+/**
+ * Extended graph configuration with path-based support
+ */
+export interface PathBasedGraphConfiguration {
+  metadata: {
+    name: string;
+    version: string;
+    description?: string;
+  };
+
+  /** Node types with source path mapping */
+  nodeTypes: Record<string, PathBasedNodeTypeDefinition>;
+
+  /** Edge types with action-based activation */
+  edgeTypes: Record<string, PathBasedEdgeTypeDefinition>;
+
+  /** Allowed connections between node types */
+  allowedConnections: Array<{
+    from: string;
+    to: string;
+    via: string;
+    constraints?: {
+      maxInstances?: number;
+      bidirectional?: boolean;
+      exclusive?: boolean;
+    };
+  }>;
+
+  /** Optional validation rules */
+  validation?: any;  // Reuse from base types
+
+  /** Display preferences */
+  display?: any;  // Reuse from base types
+
+  /** Path-based configuration options */
+  pathBasedConfig?: PathBasedConfigOptions;
+}
+
+/**
+ * Configuration options for path-based log association
+ */
+export interface PathBasedConfigOptions {
+  /** Project root for normalizing paths */
+  projectRoot?: string;
+
+  /** Whether to enable source capture (default: true) */
+  captureSource?: boolean;
+
+  /** Whether to enable action pattern matching (default: false in M1, true in M2) */
+  enableActionPatterns?: boolean;
+
+  /** Default log level for filtering (default: 'info') */
+  logLevel?: LogLevel;
+
+  /** Whether to ignore logs without source information (default: false) */
+  ignoreUnsourced?: boolean;
+}
+
+/**
+ * Component activity event (Milestone 1)
+ * Generated when a log is associated with a component by source path
+ */
+export interface ComponentActivityEvent {
+  type: 'component-activity';
+
+  /** Component ID (node type) */
+  componentId: string;
+
+  /**
+   * Instance identifier for multi-instance components.
+   * If provided, targets a specific node instance (e.g., "client-1").
+   * If undefined, targets the node type as a whole.
+   */
+  instanceId?: string;
+
+  /** Timestamp of the log */
+  timestamp: number;
+
+  /** Log level */
+  level: LogLevel;
+
+  /** Log message */
+  message: string;
+
+  /** Source location */
+  source: {
+    file: string;
+    line?: number;
+    column?: number;
+  };
+
+  /** Additional log arguments */
+  args?: any[];
+}
+
+/**
+ * Component action event (Milestone 2)
+ * Generated when a log matches an action pattern
+ */
+export interface ComponentActionEvent {
+  type: 'component-action';
+
+  /** Component ID (node type) */
+  componentId: string;
+
+  /**
+   * Instance identifier for multi-instance components.
+   * If provided, targets a specific node instance (e.g., "client-1").
+   * If undefined, targets the node type as a whole.
+   */
+  instanceId?: string;
+
+  /** Action type (from pattern) */
+  action: string;
+
+  /** New state (if specified in pattern) */
+  state?: string;
+
+  /** Timestamp of the log */
+  timestamp: number;
+
+  /** Extracted metadata from capture groups */
+  metadata?: Record<string, any>;
+
+  /** Source location */
+  source: {
+    file: string;
+    line?: number;
+    column?: number;
+  };
+}
+
+/**
+ * Edge animation event (Milestone 2)
+ * Generated when a component action triggers edge activation
+ */
+export interface EdgeAnimationEvent {
+  type: 'edge-animation';
+
+  /** Edge ID to animate */
+  edgeId: string;
+
+  /** Animation type */
+  animation: 'flow' | 'particle' | 'pulse' | 'glow';
+
+  /** Animation direction */
+  direction?: 'forward' | 'backward' | 'bidirectional';
+
+  /** Animation duration */
+  duration: number;
+
+  /** Timestamp */
+  timestamp: number;
+
+  /** Source action that triggered this */
+  triggeredBy?: {
+    componentId: string;
+    action: string;
+  };
+}
+
+/**
+ * Union type of all path-based events
+ */
+export type PathBasedEvent =
+  | ComponentActivityEvent
+  | ComponentActionEvent
+  | EdgeAnimationEvent;

package/src/utils/CanvasConverter.ts

@@ -0,0 +1,431 @@
+/**
+ * Canvas Converter
+ *
+ * Utilities for converting between Extended Canvas format and React Flow nodes/edges.
+ */
+
+import type {
+  ExtendedCanvas,
+  ExtendedCanvasNode,
+  ExtendedCanvasEdge,
+  PVEdgeTypeDefinition,
+  PVNodeShape,
+  PVEdgeStyle,
+  PVAnimationType,
+} from '../types/canvas';
+import { resolveCanvasColor } from '../types/canvas';
+import type { NodeState, EdgeState } from '../types';
+
+/**
+ * React Flow node format
+ */
+export interface ReactFlowNode {
+  id: string;
+  type: string;
+  position: { x: number; y: number };
+  data: {
+    label: string;
+    nodeType: string;
+    shape?: string;
+    icon?: string;
+    color?: string;
+    width?: number;
+    height?: number;
+    states?: Record<string, { color?: string; icon?: string; label?: string }>;
+    sources?: string[];
+    actions?: any[];
+    canvasType?: 'text' | 'file' | 'link' | 'group';
+    text?: string;
+    file?: string;
+    url?: string;
+    [key: string]: any;
+  };
+  style?: {
+    width?: number;
+    height?: number;
+  };
+}
+
+/**
+ * React Flow edge format
+ */
+export interface ReactFlowEdge {
+  id: string;
+  source: string;
+  target: string;
+  type?: string;
+  sourceHandle?: string;
+  targetHandle?: string;
+  label?: string;
+  data?: {
+    edgeType: string;
+    style?: string;
+    color?: string;
+    width?: number;
+    animation?: {
+      type: string;
+      duration?: number;
+      color?: string;
+    };
+    activatedBy?: any[];
+    [key: string]: any;
+  };
+  style?: {
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+  };
+  animated?: boolean;
+  markerEnd?: {
+    type: string;
+    color?: string;
+  };
+}
+
+/**
+ * Convert canvas side to React Flow handle position
+ */
+function sideToHandle(side?: string): string | undefined {
+  if (!side) return undefined;
+  // React Flow uses 'top', 'right', 'bottom', 'left' - same as canvas
+  return side;
+}
+
+/**
+ * Convert edge style to stroke-dasharray
+ */
+function styleToStrokeDasharray(style?: string): string | undefined {
+  switch (style) {
+    case 'dashed':
+      return '5,5';
+    case 'dotted':
+      return '2,2';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Canvas Converter utility class
+ */
+export class CanvasConverter {
+  /**
+   * Convert Extended Canvas to React Flow nodes and edges
+   */
+  static canvasToReactFlow(canvas: ExtendedCanvas): {
+    nodes: ReactFlowNode[];
+    edges: ReactFlowEdge[];
+  } {
+    const nodes: ReactFlowNode[] = [];
+    const edges: ReactFlowEdge[] = [];
+
+    // Convert nodes
+    if (canvas.nodes) {
+      for (const node of canvas.nodes) {
+        nodes.push(this.convertNode(node, canvas));
+      }
+    }
+
+    // Convert edges
+    if (canvas.edges) {
+      for (const edge of canvas.edges) {
+        edges.push(this.convertEdge(edge, canvas));
+      }
+    }
+
+    return { nodes, edges };
+  }
+
+  /**
+   * Convert a single canvas node to React Flow node
+   */
+  private static convertNode(node: ExtendedCanvasNode, canvas: ExtendedCanvas): ReactFlowNode {
+    const pv = node.pv;
+    const color = resolveCanvasColor(node.color);
+
+    // Build the data object based on canvas node type
+    const data: ReactFlowNode['data'] = {
+      label: this.getNodeLabel(node),
+      nodeType: pv?.nodeType || node.id,
+      canvasType: node.type,
+      shape: pv?.shape || 'rectangle',
+      icon: pv?.icon,
+      color: pv?.states?.idle?.color || color,
+      width: node.width,
+      height: node.height,
+    };
+
+    // Add type-specific data
+    if (node.type === 'text') {
+      data.text = node.text;
+    } else if (node.type === 'file') {
+      data.file = node.file;
+    } else if (node.type === 'link') {
+      data.url = node.url;
+    } else if (node.type === 'group') {
+      data.label = node.label || data.label;
+    }
+
+    // Add PV extensions if present
+    if (pv) {
+      data.states = pv.states;
+      data.sources = pv.sources;
+      data.actions = pv.actions;
+      if (pv.dataSchema) {
+        data.dataSchema = pv.dataSchema;
+      }
+    }
+
+    return {
+      id: node.id,
+      type: pv?.shape || 'default',
+      position: { x: node.x, y: node.y },
+      data,
+      style: {
+        width: node.width,
+        height: node.height,
+      },
+    };
+  }
+
+  /**
+   * Get display label for a node
+   */
+  private static getNodeLabel(node: ExtendedCanvasNode): string {
+    if (node.pv?.nodeType) {
+      return node.pv.nodeType;
+    }
+    switch (node.type) {
+      case 'text':
+        // Use first line of text as label
+        const firstLine = node.text.split('\n')[0];
+        return firstLine.replace(/^#+ /, '').substring(0, 50);
+      case 'file':
+        // Use filename as label
+        return node.file.split('/').pop() || node.file;
+      case 'link':
+        return node.url;
+      case 'group':
+        return node.label || 'Group';
+    }
+  }
+
+  /**
+   * Convert a single canvas edge to React Flow edge
+   */
+  private static convertEdge(edge: ExtendedCanvasEdge, canvas: ExtendedCanvas): ReactFlowEdge {
+    const pv = edge.pv;
+    const edgeTypeDef = pv?.edgeType ? canvas.pv?.edgeTypes?.[pv.edgeType] : undefined;
+    const color = resolveCanvasColor(edge.color) || edgeTypeDef?.color;
+
+    const rfEdge: ReactFlowEdge = {
+      id: edge.id,
+      source: edge.fromNode,
+      target: edge.toNode,
+      sourceHandle: sideToHandle(edge.fromSide),
+      targetHandle: sideToHandle(edge.toSide),
+      label: edge.label,
+      data: {
+        edgeType: pv?.edgeType || 'default',
+        style: pv?.style || edgeTypeDef?.style || 'solid',
+        color,
+        width: pv?.width || edgeTypeDef?.width || 2,
+        animation: pv?.animation || edgeTypeDef?.animation,
+        activatedBy: pv?.activatedBy || edgeTypeDef?.activatedBy,
+      },
+      style: {
+        stroke: color,
+        strokeWidth: pv?.width || edgeTypeDef?.width || 2,
+        strokeDasharray: styleToStrokeDasharray(pv?.style || edgeTypeDef?.style),
+      },
+      animated: pv?.style === 'animated' || edgeTypeDef?.style === 'animated',
+    };
+
+    // Add marker based on canvas endpoint settings
+    if (edge.toEnd !== 'none') {
+      rfEdge.markerEnd = {
+        type: 'arrowclosed',
+        color,
+      };
+    }
+
+    return rfEdge;
+  }
+
+  /**
+   * Convert Extended Canvas to internal NodeState/EdgeState format
+   */
+  static canvasToGraph(canvas: ExtendedCanvas): {
+    nodes: NodeState[];
+    edges: EdgeState[];
+  } {
+    const nodes: NodeState[] = [];
+    const edges: EdgeState[] = [];
+    const now = Date.now();
+
+    // Convert nodes
+    if (canvas.nodes) {
+      for (const node of canvas.nodes) {
+        const pv = node.pv;
+        nodes.push({
+          id: node.id,
+          type: pv?.nodeType || node.type,
+          data: {
+            label: this.getNodeLabel(node),
+            shape: pv?.shape || 'rectangle',
+            icon: pv?.icon,
+            // Color priority: pv.fill > node.color
+            color: pv?.fill || resolveCanvasColor(node.color),
+            // Stroke color for borders
+            stroke: pv?.stroke,
+            width: node.width,
+            height: node.height,
+            sources: pv?.sources || [],
+            actions: pv?.actions || [],
+            states: pv?.states,
+            canvasType: node.type,
+            ...(node.type === 'text' ? { text: node.text } : {}),
+            ...(node.type === 'file' ? { file: node.file } : {}),
+            ...(node.type === 'link' ? { url: node.url } : {}),
+          },
+          position: { x: node.x, y: node.y },
+          // Don't set a default state - only show state labels when explicitly set via events
+          state: undefined,
+          createdAt: now,
+          updatedAt: now,
+        });
+      }
+    }
+
+    // Convert edges
+    if (canvas.edges) {
+      for (const edge of canvas.edges) {
+        const pv = edge.pv;
+        const edgeTypeDef = pv?.edgeType ? canvas.pv?.edgeTypes?.[pv.edgeType] : undefined;
+
+        edges.push({
+          id: edge.id,
+          type: pv?.edgeType || 'default',
+          from: edge.fromNode,
+          to: edge.toNode,
+          data: {
+            label: edge.label,
+            style: pv?.style || edgeTypeDef?.style || 'solid',
+            color: resolveCanvasColor(edge.color) || edgeTypeDef?.color,
+            width: pv?.width || edgeTypeDef?.width,
+            animation: pv?.animation || edgeTypeDef?.animation,
+            activatedBy: pv?.activatedBy || edgeTypeDef?.activatedBy,
+            fromSide: edge.fromSide,
+            toSide: edge.toSide,
+          },
+          createdAt: now,
+          updatedAt: now,
+        });
+      }
+    }
+
+    return { nodes, edges };
+  }
+
+  /**
+   * Convert React Flow nodes/edges back to Extended Canvas format
+   */
+  static reactFlowToCanvas(
+    nodes: ReactFlowNode[],
+    edges: ReactFlowEdge[],
+    metadata?: { name?: string; version?: string; description?: string }
+  ): ExtendedCanvas {
+    const canvas: ExtendedCanvas = {
+      nodes: [],
+      edges: [],
+      pv: {
+        version: metadata?.version || '1.0.0',
+        name: metadata?.name || 'Untitled',
+        description: metadata?.description,
+        edgeTypes: {},
+      },
+    };
+
+    // Collect edge types
+    const edgeTypes = new Map<string, PVEdgeTypeDefinition>();
+
+    // Convert nodes
+    for (const node of nodes) {
+      const canvasNode: ExtendedCanvasNode = {
+        id: node.id,
+        type: node.data.canvasType || 'text',
+        x: node.position.x,
+        y: node.position.y,
+        width: node.style?.width || node.data.width || 150,
+        height: node.style?.height || node.data.height || 80,
+        text: node.data.text || node.data.label || '',
+      } as ExtendedCanvasNode;
+
+      // Add color if present
+      if (node.data.color) {
+        canvasNode.color = node.data.color;
+      }
+
+      // Add PV extension if there's custom data
+      if (node.data.nodeType || node.data.shape || node.data.sources?.length) {
+        canvasNode.pv = {
+          nodeType: node.data.nodeType || node.id,
+          shape: node.data.shape as PVNodeShape | undefined,
+          icon: node.data.icon,
+          states: node.data.states,
+          sources: node.data.sources,
+          actions: node.data.actions,
+          dataSchema: node.data.dataSchema,
+        };
+      }
+
+      canvas.nodes!.push(canvasNode);
+    }
+
+    // Convert edges
+    for (const edge of edges) {
+      const canvasEdge: ExtendedCanvasEdge = {
+        id: edge.id,
+        fromNode: edge.source,
+        toNode: edge.target,
+        fromSide: edge.sourceHandle as any,
+        toSide: edge.targetHandle as any,
+        label: edge.label as string | undefined,
+      };
+
+      // Add color
+      if (edge.style?.stroke) {
+        canvasEdge.color = edge.style.stroke;
+      }
+
+      // Add PV extension
+      if (edge.data?.edgeType) {
+        canvasEdge.pv = {
+          edgeType: edge.data.edgeType,
+          style: edge.data.style as PVEdgeStyle | undefined,
+          width: edge.data.width,
+          animation: edge.data.animation as { type: PVAnimationType; duration?: number; color?: string } | undefined,
+          activatedBy: edge.data.activatedBy,
+        };
+
+        // Collect edge type definition
+        if (!edgeTypes.has(edge.data.edgeType)) {
+          edgeTypes.set(edge.data.edgeType, {
+            style: edge.data.style as PVEdgeStyle | undefined,
+            color: edge.data.color,
+            width: edge.data.width,
+            animation: edge.data.animation as { type: PVAnimationType; duration?: number; color?: string } | undefined,
+            activatedBy: edge.data.activatedBy,
+          });
+        }
+      }
+
+      canvas.edges!.push(canvasEdge);
+    }
+
+    // Add collected edge types to canvas
+    canvas.pv!.edgeTypes = Object.fromEntries(edgeTypes);
+
+    return canvas;
+  }
+}