@principal-ai/principal-view-core 0.26.24 → 0.26.26

package/src/codegen/type-generator.ts

@@ -12,7 +12,8 @@
  * - Zod: runtime validation with TypeScript inference
  */
 
-import type { ExtendedCanvas, PVEventSchema, PVEventFieldSchema } from '../types/canvas';
+import type { ExtendedCanvas, PVEventSchema, PVEventFieldSchema, ExtendedCanvasNode } from '../types/canvas';
+import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
 import type { ComponentLibrary } from '../types/library';
 
 /**
@@ -103,18 +104,32 @@ export class TypeScriptGenerator implements CodeGenerator {
       for (const node of canvas.nodes) {
         let eventSchema: PVEventSchema | undefined;
 
-        // Check for inline event definition
-        if (node.pv?.event) {
-          eventSchema = node.pv.event;
+        // Check for OTEL event node (top-level event/eventRef fields)
+        if (isOtelEventNode(node)) {
+          if (node.event) {
+            eventSchema = node.event;
+          } else if (node.eventRef) {
+            eventSchema = this.resolveLibraryEvent(node.eventRef, library);
+            if (!eventSchema) {
+              console.warn(
+                `Node '${node.id}' references unknown library event '${node.eventRef}'`
+              );
+              continue;
+            }
+          }
         }
-        // Check for library event reference
-        else if (node.pv?.eventRef) {
-          eventSchema = this.resolveLibraryEvent(node.pv.eventRef, library);
-          if (!eventSchema) {
-            console.warn(
-              `Node '${node.id}' references unknown library event '${node.pv.eventRef}'`
-            );
-            continue;
+        // Check for standard node with pv.event/pv.eventRef
+        else if (isStandardCanvasNode(node)) {
+          if (node.pv?.event) {
+            eventSchema = node.pv.event;
+          } else if (node.pv?.eventRef) {
+            eventSchema = this.resolveLibraryEvent(node.pv.eventRef, library);
+            if (!eventSchema) {
+              console.warn(
+                `Node '${node.id}' references unknown library event '${node.pv.eventRef}'`
+              );
+              continue;
+            }
           }
         }
 
@@ -308,15 +323,26 @@ export class TypeScriptGenerator implements CodeGenerator {
 
     if (canvas.nodes) {
       for (const node of canvas.nodes) {
-        // Check for inline event definition
-        if (node.pv?.event?.name) {
-          allEventNames.add(node.pv.event.name);
+        // Check for OTEL event node (top-level event/eventRef fields)
+        if (isOtelEventNode(node)) {
+          if (node.event?.name) {
+            allEventNames.add(node.event.name);
+          } else if (node.eventRef) {
+            const eventSchema = this.resolveLibraryEvent(node.eventRef, library);
+            if (eventSchema) {
+              allEventNames.add(eventSchema.name);
+            }
+          }
         }
-        // Check for library event reference
-        else if (node.pv?.eventRef) {
-          const eventSchema = this.resolveLibraryEvent(node.pv.eventRef, library);
-          if (eventSchema) {
-            allEventNames.add(eventSchema.name);
+        // Check for standard node with pv.event/pv.eventRef
+        else if (isStandardCanvasNode(node)) {
+          if (node.pv?.event?.name) {
+            allEventNames.add(node.pv.event.name);
+          } else if (node.pv?.eventRef) {
+            const eventSchema = this.resolveLibraryEvent(node.pv.eventRef, library);
+            if (eventSchema) {
+              allEventNames.add(eventSchema.name);
+            }
           }
         }
       }

package/src/index.ts

@@ -16,6 +16,7 @@ import {
   isLinkNode,
   isGroupNode,
   hasPVExtension,
+  isStandardCanvasNode,
   CANVAS_COLOR_PRESETS,
   resolveCanvasColor,
 } from './types/canvas';
@@ -113,6 +114,7 @@ export {
   isLinkNode,
   isGroupNode,
   hasPVExtension,
+  isStandardCanvasNode,
   CANVAS_COLOR_PRESETS,
   resolveCanvasColor,
 };

package/src/matchers/SpanMatcher.ts

@@ -9,6 +9,7 @@
  */
 
 import type { ExtendedCanvas, PVOtelExtension } from '../types/canvas';
+import { isOtelNode, isStandardCanvasNode } from '../types/canvas';
 import type { OtelSpanData, OtelResourceData } from '../types/otel';
 import {
   getAttributeValue,
@@ -89,9 +90,17 @@ export class SpanMatcher {
     if (!canvas.nodes) return rules;
 
     for (const node of canvas.nodes) {
-      if (!node.pv?.otel) continue;
+      // Get OTEL metadata from either OTEL nodes (top-level) or standard nodes (pv.otel)
+      let otel: PVOtelExtension | undefined;
+
+      if (isOtelNode(node) && node.otel) {
+        otel = node.otel as PVOtelExtension;
+      } else if (isStandardCanvasNode(node) && node.pv?.otel) {
+        otel = node.pv.otel as PVOtelExtension;
+      }
+
+      if (!otel) continue;
 
-      const otel = node.pv.otel as PVOtelExtension;
       const rule: CompiledMatchRule = {
         nodeId: node.id,
         resourceMatchers: [],

package/src/registry/EventRegistry.ts

@@ -7,6 +7,7 @@
 
 import type { ComponentLibrary } from '../types/library';
 import type { ExtendedCanvas, PVEventSchema } from '../types/canvas';
+import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
 
 /**
  * Describes where an event is defined
@@ -81,28 +82,51 @@ export class EventRegistry {
       if (!canvas.nodes) continue;
 
       for (const node of canvas.nodes) {
-        if (!node.pv) continue;
-
-        // Inline event definition (pv.event)
-        if (node.pv.event && typeof node.pv.event === 'object' && node.pv.event.name) {
-          registry.addEvent(node.pv.event.name, {
-            type: 'canvas',
-            path: canvasPath,
-            eventSchema: node.pv.event,
-          });
-        }
+        // Handle OTEL event nodes (top-level event/eventRef)
+        if (isOtelEventNode(node)) {
+          // Inline event definition
+          if (node.event && typeof node.event === 'object' && node.event.name) {
+            registry.addEvent(node.event.name, {
+              type: 'canvas',
+              path: canvasPath,
+              eventSchema: node.event,
+            });
+          }
 
-        // Event reference (pv.eventRef) - note: these should resolve to library
-        // but we track them as canvas sources too for completeness
-        if (node.pv.eventRef && typeof node.pv.eventRef === 'string') {
-          // Only add if not already in registry (library takes priority)
-          if (!registry.hasEvent(node.pv.eventRef)) {
-            registry.addEvent(node.pv.eventRef, {
+          // Event reference
+          if (node.eventRef && typeof node.eventRef === 'string') {
+            // Only add if not already in registry (library takes priority)
+            if (!registry.hasEvent(node.eventRef)) {
+              registry.addEvent(node.eventRef, {
+                type: 'canvas',
+                path: canvasPath,
+                // No schema available - it's just a reference
+              });
+            }
+          }
+        }
+        // Handle standard nodes with pv.event/pv.eventRef
+        else if (isStandardCanvasNode(node) && node.pv) {
+          // Inline event definition (pv.event)
+          if (node.pv.event && typeof node.pv.event === 'object' && node.pv.event.name) {
+            registry.addEvent(node.pv.event.name, {
               type: 'canvas',
               path: canvasPath,
-              // No schema available - it's just a reference
+              eventSchema: node.pv.event,
             });
           }
+
+          // Event reference (pv.eventRef)
+          if (node.pv.eventRef && typeof node.pv.eventRef === 'string') {
+            // Only add if not already in registry (library takes priority)
+            if (!registry.hasEvent(node.pv.eventRef)) {
+              registry.addEvent(node.pv.eventRef, {
+                type: 'canvas',
+                path: canvasPath,
+                // No schema available - it's just a reference
+              });
+            }
+          }
         }
       }
     }

package/src/spans/utils.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
+import { isOtelSpanConventionNode, isStandardCanvasNode } from '../types/canvas';
 
 /** Default color for spans without a defined color */
 export const DEFAULT_SPAN_COLOR = '#9CA3AF'; // gray-400
@@ -32,6 +33,27 @@ export interface NormalizedSpanConvention {
  * Extract span convention from a canvas node
  */
 export function extractSpanConvention(node: ExtendedCanvasNode): NormalizedSpanConvention | null {
+  // Handle OTEL span convention nodes (top-level otel field)
+  if (isOtelSpanConventionNode(node)) {
+    const spanPattern = node.otel?.spanPattern;
+    if (!spanPattern) return null;
+
+    const color = node.color as string | undefined;
+    if (!color) return null;
+
+    return {
+      id: node.id,
+      spanPattern,
+      color,
+      icon: node.icon,
+      description: node.description,
+      status: node.otel?.status,
+    };
+  }
+
+  // Handle standard nodes with pv.nodeType === 'span-convention'
+  if (!isStandardCanvasNode(node)) return null;
+
   const pv = node.pv;
   if (!pv) return null;
 

package/src/storyboard/builder.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
+import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
 import type { WorkflowTemplate, WorkflowScenario } from '../workflow/types';
 import type {
   StoryboardReference,
@@ -102,11 +103,17 @@ export function getNodeEventName(node: ExtendedCanvasNode): string | undefined {
   const topLevelEvent = (node as { event?: { name?: string } }).event?.name;
   if (topLevelEvent) return topLevelEvent;
 
-  const topLevelEventRef = (node as { eventRef?: string }).eventRef;
-  if (topLevelEventRef) return topLevelEventRef;
+  // Check OTEL event node (top-level event/eventRef)
+  if (isOtelEventNode(node)) {
+    return node.event?.name || node.eventRef;
+  }
+
+  // Check standard node with pv.event/pv.eventRef
+  if (isStandardCanvasNode(node)) {
+    return node.pv?.event?.name || node.pv?.eventRef;
+  }
 
-  // 2. PVNodeExtension format (inside node.pv)
-  return node.pv?.event?.name || node.pv?.eventRef;
+  return undefined;
 }
 
 /**

package/src/telemetry/coverage.ts

@@ -12,6 +12,7 @@ import type { FileTree } from '@principal-ai/repository-abstraction';
 import { CanvasDiscovery } from '../discovery/CanvasDiscovery';
 import type { DiscoveredCanvasWithContent } from '../discovery/types';
 import type { ExtendedCanvasNode } from '../types/canvas';
+import { isOtelNode, isStandardCanvasNode } from '../types/canvas';
 import { getNodeEventName } from '../storyboard/builder';
 import {
   ImplementationFileLayerModule,
@@ -108,13 +109,15 @@ function getEventName(node: ExtendedCanvasNode): string | null {
  * Supports both new format (node.otel.files) and legacy format (pv.otel.files)
  */
 function getInstrumentationFiles(node: ExtendedCanvasNode): string[] {
-  // Check new format first (otel-event nodes)
-  const otelNode = node as { otel?: { files?: string[] } };
-  if (otelNode.otel?.files) {
-    return otelNode.otel.files;
+  // Check OTEL nodes (top-level otel field)
+  if (isOtelNode(node) && node.otel?.files) {
+    return node.otel.files;
   }
-  // Fallback to legacy format (pv.otel.files)
-  return node.pv?.otel?.files || [];
+  // Check standard nodes (pv.otel.files)
+  if (isStandardCanvasNode(node) && node.pv?.otel?.files) {
+    return node.pv.otel.files;
+  }
+  return [];
 }
 
 /**
@@ -138,13 +141,15 @@ async function fileContainsEvent(
  * Supports both new format (node.otel.status) and legacy format (pv.status)
  */
 function getNodeStatus(node: ExtendedCanvasNode): 'draft' | 'approved' | 'implemented' | undefined {
-  // Check new format first (otel-event nodes)
-  const otelNode = node as { otel?: { status?: 'draft' | 'approved' | 'implemented' } };
-  if (otelNode.otel?.status) {
-    return otelNode.otel.status;
+  // Check OTEL nodes (otel.status)
+  if (isOtelNode(node) && node.otel?.status) {
+    return node.otel.status;
+  }
+  // Check standard nodes (pv.status)
+  if (isStandardCanvasNode(node) && node.pv?.status) {
+    return node.pv.status;
   }
-  // Fallback to legacy format (pv.status)
-  return node.pv?.status;
+  return undefined;
 }
 
 /**
@@ -234,7 +239,12 @@ function validateNodes(
       }
 
       // Get references for grounding validation
-      const references = node.pv?.references || [];
+      let references: string[] = [];
+      if (isOtelNode(node) && node.otel?.references) {
+        references = node.otel.references;
+      } else if (isStandardCanvasNode(node) && node.pv?.references) {
+        references = node.pv.references;
+      }
       const hasReferences = references.length > 0;
 
       // Count by status
@@ -271,8 +281,11 @@ function validateNodes(
         });
       }
 
-      // Error if using deprecated pv.otel.scope
-      const legacyScope = node.pv?.otel?.scope;
+      // Error if using deprecated pv.otel.scope (only for standard nodes)
+      let legacyScope: string | undefined;
+      if (isStandardCanvasNode(node)) {
+        legacyScope = node.pv?.otel?.scope;
+      }
       if (legacyScope) {
         errors.push({
           nodeId: node.id,

package/src/telemetry/event-validator.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ExtendedCanvas, PVEventSchema } from '../types/canvas';
+import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
 import type { ComponentLibrary } from '../types/library';
 import type { JsonValue, JsonObject } from '../types';
 
@@ -54,18 +55,32 @@ export class EventValidator {
     for (const node of canvas.nodes) {
       let eventSchema: PVEventSchema | undefined;
 
-      // Check for inline event definition
-      if (node.pv?.event) {
-        eventSchema = node.pv.event;
+      // Check OTEL event node (top-level event/eventRef)
+      if (isOtelEventNode(node)) {
+        if (node.event) {
+          eventSchema = node.event;
+        } else if (node.eventRef) {
+          eventSchema = this.resolveLibraryEvent(node.eventRef);
+          if (!eventSchema) {
+            console.warn(
+              `Node '${node.id}' references unknown library event '${node.eventRef}'`
+            );
+            continue;
+          }
+        }
       }
-      // Check for library event reference
-      else if (node.pv?.eventRef) {
-        eventSchema = this.resolveLibraryEvent(node.pv.eventRef);
-        if (!eventSchema) {
-          console.warn(
-            `Node '${node.id}' references unknown library event '${node.pv.eventRef}'`
-          );
-          continue;
+      // Check standard node (pv.event/pv.eventRef)
+      else if (isStandardCanvasNode(node)) {
+        if (node.pv?.event) {
+          eventSchema = node.pv.event;
+        } else if (node.pv?.eventRef) {
+          eventSchema = this.resolveLibraryEvent(node.pv.eventRef);
+          if (!eventSchema) {
+            console.warn(
+              `Node '${node.id}' references unknown library event '${node.pv.eventRef}'`
+            );
+            continue;
+          }
         }
       }
 

package/src/types/canvas.ts

@@ -911,12 +911,6 @@ export interface OtelNodeBase extends CanvasNodeBase {
   stroke?: string;
   /** Visual shape */
   shape?: PVNodeShape;
-  /**
-   * Legacy PV extension field for backward compatibility during migration.
-   * New OTEL nodes should use top-level fields instead.
-   * @deprecated Use top-level fields (label, icon, etc.) instead
-   */
-  pv?: PVNodeExtension;
 }
 
 /**
@@ -1302,6 +1296,15 @@ export function isOtelNode(node: ExtendedCanvasNode): node is OtelNode {
   );
 }
 
+/**
+ * Type guard for standard canvas nodes (that may have pv extensions)
+ */
+export function isStandardCanvasNode(
+  node: ExtendedCanvasNode
+): node is ExtendedCanvasTextNode | ExtendedCanvasFileNode | ExtendedCanvasLinkNode | ExtendedCanvasGroupNode {
+  return !isOtelNode(node);
+}
+
 /**
  * Get the identifier for an OTEL node (shown below the label)
  */

package/src/types/library.ts

@@ -398,6 +398,28 @@ export interface ComponentLibrary {
 
   /** Optional connection rules (which nodes can connect via which edges) */
   connectionRules?: LibraryConnectionRule[];
+
+  /**
+   * Global state definitions for OTEL nodes
+   *
+   * Defines reusable states that can be applied to OTEL event and span nodes.
+   * States provide visual indicators (colors) for different statuses.
+   *
+   * @example
+   * ```yaml
+   * states:
+   *   draft:
+   *     color: "#f59e0b"
+   *     label: "Draft"
+   *   approved:
+   *     color: "#10b981"
+   *     label: "Approved"
+   *   implemented:
+   *     color: "#6366f1"
+   *     label: "Implemented"
+   * ```
+   */
+  states?: Record<string, PVNodeState>;
 }
 
 // ============================================================================