@dr2rai/raid-canvas 0.3.0 → 0.3.1

package/src/RaidCanvas.tsx

@@ -57,6 +57,8 @@ export interface RaidCanvasProps {
   onSelectionChange?: (selectedIds: string[]) => void;
   /** Callback fired when a stencil is dropped onto the canvas */
   onDropStencil?: (kind: AimOntologyKind, point: { x: number; y: number }) => void;
+  /** Callback fired when the active routing mode changes (e.g. hydrated from SVG or switched by user) */
+  onRoutingModeChange?: (mode: AimRoutingMode) => void;
   /** Whether to render built-in navigation controls (Zoom In/Out, Fit, Center, Reset). Default: true */
   showToolbar?: boolean;
 }
@@ -115,6 +117,7 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
       onSelect,
       onSelectionChange,
       onDropStencil,
+      onRoutingModeChange,
       showToolbar = true,
     },
     ref,
@@ -128,7 +131,6 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
     const selectedCellIdRef = useRef<string | null>(null);
     const clearEdgeToolsRef = useRef<(() => void) | null>(null);
     const routingModeRef = useRef<AimRoutingMode>(defaultRouting);
-    routingModeRef.current = defaultRouting;
 
     const [zoomLevel, setZoomLevel] = useState<number>(100);
     const [isDragOver, setIsDragOver] = useState<boolean>(false);
@@ -152,6 +154,9 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
     const onDropStencilRef = useRef(onDropStencil);
     onDropStencilRef.current = onDropStencil;
 
+    const onRoutingModeChangeRef = useRef(onRoutingModeChange);
+    onRoutingModeChangeRef.current = onRoutingModeChange;
+
     const svgPropRef = useRef(activeSvg);
     svgPropRef.current = activeSvg;
 
@@ -169,6 +174,7 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
         const updatedSvg = bridgeRef.current.serializeToSvg(
           graphRef.current,
           currentBaseSvg,
+          { routingMode: routingModeRef.current },
         );
         lastSerializedSvgRef.current = updatedSvg;
 
@@ -227,6 +233,7 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
           return bridgeRef.current.serializeToSvg(
             graphRef.current,
             svgPropRef.current,
+            { routingMode: routingModeRef.current },
           );
         },
         addNode: (kind, x, y, customData) => {
@@ -310,8 +317,7 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
           if (!edge || !edge.isEdge()) return;
 
           const currentData = (edge.getData() ?? {}) as RaidEdgeData;
-          const nextData = { ...currentData, ...updates };
-          edge.setData(nextData);
+          const mutableData: Record<string, unknown> = { ...currentData, ...updates };
 
           if (updates.routing !== undefined) {
             applyEdgeRouting(edge, updates.routing);
@@ -320,17 +326,31 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
           if (updates.sourcePort !== undefined) {
             const currentSource = edge.getSource() as { cell?: string };
             if (currentSource.cell) {
-              edge.setSource({ cell: currentSource.cell, port: updates.sourcePort });
+              if (updates.sourcePort === '' || updates.sourcePort === 'auto') {
+                edge.setSource({ cell: currentSource.cell });
+                delete mutableData.sourcePort;
+              } else {
+                edge.setSource({ cell: currentSource.cell, port: updates.sourcePort });
+                mutableData.sourcePort = updates.sourcePort;
+              }
             }
           }
 
           if (updates.targetPort !== undefined) {
             const currentTarget = edge.getTarget() as { cell?: string };
             if (currentTarget.cell) {
-              edge.setTarget({ cell: currentTarget.cell, port: updates.targetPort });
+              if (updates.targetPort === '' || updates.targetPort === 'auto') {
+                edge.setTarget({ cell: currentTarget.cell });
+                delete mutableData.targetPort;
+              } else {
+                edge.setTarget({ cell: currentTarget.cell, port: updates.targetPort });
+                mutableData.targetPort = updates.targetPort;
+              }
             }
           }
 
+          edge.setData(mutableData as unknown as RaidEdgeData);
+
           if (updates.label !== undefined || updates.stereotype !== undefined) {
             const text = updates.label ?? updates.stereotype ?? '';
             edge.setLabels(
@@ -355,6 +375,10 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
         },
         setRoutingMode: (mode, applyToAll = true) => {
           routingModeRef.current = mode;
+          if (graphRef.current) {
+            (graphRef.current as unknown as { _aimRoutingMode?: AimRoutingMode })._aimRoutingMode = mode;
+          }
+          onRoutingModeChangeRef.current?.(mode);
           if (applyToAll && graphRef.current) {
             for (const edge of graphRef.current.getEdges()) {
               applyEdgeRouting(edge, mode);
@@ -723,8 +747,13 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
       if (svgPropRef.current) {
         isHydratingRef.current = true;
         try {
-          bridgeRef.current.hydrateFromSvg(svgPropRef.current, graph);
+          const metamodel = bridgeRef.current.hydrateFromSvg(svgPropRef.current, graph, { inferPorts: false });
           lastSerializedSvgRef.current = svgPropRef.current;
+          if (metamodel.routing) {
+            routingModeRef.current = metamodel.routing;
+            (graph as unknown as { _aimRoutingMode?: AimRoutingMode })._aimRoutingMode = metamodel.routing;
+            onRoutingModeChangeRef.current?.(metamodel.routing);
+          }
           graph.centerContent();
         } catch (err) {
           console.error('RaidCanvas hydration error:', err);
@@ -760,8 +789,13 @@ export const RaidCanvas = React.forwardRef<RaidCanvasHandle, RaidCanvasProps>(
 
       isHydratingRef.current = true;
       try {
-        bridgeRef.current.hydrateFromSvg(activeSvg, graph);
+        const metamodel = bridgeRef.current.hydrateFromSvg(activeSvg, graph, { inferPorts: false });
         lastSerializedSvgRef.current = activeSvg;
+        if (metamodel.routing) {
+          routingModeRef.current = metamodel.routing;
+          (graph as unknown as { _aimRoutingMode?: AimRoutingMode })._aimRoutingMode = metamodel.routing;
+          onRoutingModeChangeRef.current?.(metamodel.routing);
+        }
         graph.centerContent();
       } catch (err) {
         console.error('RaidCanvas re-hydration error:', err);

package/src/X6Shapes.ts

@@ -37,6 +37,74 @@ export const CascaisPalette = {
   TextSecondary: '#4B5563',
 } as const;
 
+/**
+ * Formats and wraps node label text for AOAIM entities.
+ * Automatically wraps on whitespace when exceeding target length,
+ * and treats `<wbr>` / `<wbr/>` tags and hyphens as soft word-break opportunities
+ * within long unbroken words or strings.
+ */
+export function wrapAimText(rawText: string, maxLineLength: number = 18): string {
+  if (!rawText) return '';
+
+  const lines = rawText.split('\n');
+  const resultLines: string[] = [];
+
+  for (const line of lines) {
+    if (!line) {
+      resultLines.push('');
+      continue;
+    }
+
+    // Replace <wbr> / <wbr/> with zero-width break marker \u200B,
+    // and allow breaking after hyphens within words
+    const normalized = line
+      .replace(/<wbr\s*\/?>/gi, '\u200B')
+      .replace(/-(?=[a-zA-Z0-9])/g, '-\u200B');
+
+    const spaceWords = normalized.split(/\s+/).filter(Boolean);
+    if (spaceWords.length === 0) continue;
+
+    let currentLine = '';
+
+    for (let wordIdx = 0; wordIdx < spaceWords.length; wordIdx++) {
+      const spaceWord = spaceWords[wordIdx]!;
+      const chunks = spaceWord.split('\u200B').filter(Boolean);
+
+      for (let chunkIdx = 0; chunkIdx < chunks.length; chunkIdx++) {
+        const chunk = chunks[chunkIdx]!;
+        const isFirstChunkOfWord = chunkIdx === 0;
+
+        if (!currentLine) {
+          currentLine = chunk;
+        } else if (isFirstChunkOfWord) {
+          // Break or space before a new whitespace-separated word
+          if (currentLine.length + 1 + chunk.length <= maxLineLength) {
+            currentLine += ' ' + chunk;
+          } else {
+            resultLines.push(currentLine);
+            currentLine = chunk;
+          }
+        } else {
+          // Soft-break opportunity within a word (<wbr> or hyphen):
+          // Glues together without space if it fits; breaks without space if it overflows
+          if (currentLine.length + chunk.length <= maxLineLength) {
+            currentLine += chunk;
+          } else {
+            resultLines.push(currentLine);
+            currentLine = chunk;
+          }
+        }
+      }
+    }
+
+    if (currentLine) {
+      resultLines.push(currentLine);
+    }
+  }
+
+  return resultLines.join('\n');
+}
+
 /**
  * Port configuration generating 4 orthogonal snap anchors.
  */
@@ -133,7 +201,7 @@ export function registerAimShapes(): void {
     ports: createOrthogonalPorts(),
   });
 
-  // 2. AimActivityNode ('act') — Rounded rectangle with Heraldic Green border
+  // 2. AimActivityNode ('act') — Rounded rectangle with Heraldic Green border & underlined label
   Shape.Rect.define({
     shape: 'aim-act',
     overwrite: true,
@@ -156,6 +224,11 @@ export function registerAimShapes(): void {
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
         textAnchor: 'middle',
         textVerticalAnchor: 'middle',
+        textDecoration: 'underline',
+        textWrap: {
+          width: -16,
+          breakWord: true,
+        },
       },
     },
     ports: createOrthogonalPorts(),
@@ -278,34 +351,77 @@ export function registerAimShapes(): void {
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
         textAnchor: 'middle',
         textVerticalAnchor: 'middle',
+        textDecoration: 'underline',
+        textWrap: {
+          width: -16,
+          breakWord: true,
+        },
       },
     },
     ports: createOrthogonalPorts(),
   });
 
-  // 5. AimPersonNode ('per') — Person / Actor role card
+  // 5. AimPersonNode ('per') — Person / Actor glyph
   Shape.Rect.define({
     shape: 'aim-per',
     overwrite: true,
-    width: 120,
-    height: 70,
+    width: 90,
+    height: 90,
+    markup: [
+      {
+        tagName: 'rect',
+        selector: 'body',
+      },
+      {
+        tagName: 'path',
+        selector: 'torso',
+      },
+      {
+        tagName: 'circle',
+        selector: 'head',
+      },
+      {
+        tagName: 'text',
+        selector: 'label',
+      },
+    ],
     attrs: {
       body: {
-        fill: CascaisPalette.CanvasCream,
-        stroke: CascaisPalette.WarmGraphite,
-        strokeWidth: 1.5,
-        rx: 6,
-        ry: 6,
+        fill: 'transparent',
+        stroke: 'transparent',
+        strokeWidth: 0,
         class: 'aim-node aim-per',
       },
+      torso: {
+        d: 'M 61 50 v -4 a 8 8 0 0 0 -8 -8 H 37 a 8 8 0 0 0 -8 8 v 4',
+        fill: 'none',
+        stroke: CascaisPalette.WarmGraphite,
+        strokeWidth: 2,
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+      },
+      head: {
+        cx: 45,
+        cy: 22,
+        r: 8,
+        fill: CascaisPalette.ChalkWhite,
+        stroke: CascaisPalette.WarmGraphite,
+        strokeWidth: 2,
+      },
       label: {
-        text: '«actor»\nOperator',
+        text: 'Actor',
         fill: CascaisPalette.TextPrimary,
         fontSize: 12,
         fontWeight: '500',
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
         textAnchor: 'middle',
-        textVerticalAnchor: 'middle',
+        textVerticalAnchor: 'top',
+        refX: 0.5,
+        refY: 62,
+        textWrap: {
+          width: -10,
+          breakWord: true,
+        },
       },
     },
     ports: createOrthogonalPorts(),
@@ -391,25 +507,30 @@ export function createAimNode(data: RaidNodeData): Node.Metadata {
 
   // Archetype-specific customization
   switch (data.kind) {
-    case 'uc':
+    case 'uc': {
+      const wrappedName = wrapAimText(data.displayName);
       return {
         ...baseMetadata,
         attrs: {
           label: {
-            text: data.stereotype ? `${data.stereotype}\n${data.displayName}` : data.displayName,
+            text: data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName,
           },
         },
       };
+    }
 
-    case 'act':
+    case 'act': {
+      const wrappedName = wrapAimText(data.displayName);
       return {
         ...baseMetadata,
         attrs: {
           label: {
-            text: data.stereotype ? `${data.stereotype}\n${data.displayName}` : data.displayName,
+            text: data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName,
+            textDecoration: 'underline',
           },
         },
       };
+    }
 
     case 'cls':
       return {
@@ -427,27 +548,35 @@ export function createAimNode(data: RaidNodeData): Node.Metadata {
         },
       };
 
-    case 'obj':
+    case 'obj': {
+      const wrappedName = wrapAimText(data.displayName);
       return {
         ...baseMetadata,
         attrs: {
           label: {
-            text: data.displayName,
+            text: data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName,
+            textDecoration: 'underline',
           },
         },
       };
+    }
 
     case 'per': {
       const isInitiating = data.stereotype?.toLowerCase().includes('initiates') ?? false;
+      const strokeColor = isInitiating ? CascaisPalette.NetGold : CascaisPalette.WarmGraphite;
+      const wrappedName = wrapAimText(data.displayName, 14);
+      const text = data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName;
       return {
         ...baseMetadata,
         attrs: {
-          body: {
-            stroke: isInitiating ? CascaisPalette.NetGold : CascaisPalette.WarmGraphite,
-            strokeWidth: isInitiating ? 2 : 1.5,
+          torso: {
+            stroke: strokeColor,
+          },
+          head: {
+            stroke: strokeColor,
           },
           label: {
-            text: data.stereotype ? `${data.stereotype}\n${data.displayName}` : data.displayName,
+            text,
           },
         },
       };
@@ -648,7 +777,7 @@ export function getDefaultNodeBounds(
     case 'obj':
       return { x, y, width: 160, height: 80 };
     case 'per':
-      return { x, y, width: 120, height: 70 };
+      return { x, y, width: 90, height: 90 };
     default:
       return { x, y, width: 140, height: 60 };
   }

package/src/index.ts

@@ -39,6 +39,7 @@ export {
   applyEdgeRouting,
   getDefaultNodeBounds,
   getDefaultNodeName,
+  wrapAimText,
 } from './X6Shapes.js';
 
 // Anti-Entropy Semantic Connection Rules

package/src/styles/aoaim-theme.css

@@ -83,6 +83,12 @@
   ry: var(--aim-radius-act);
 }
 
+.aim-node[aim-act] text,
+.aim-node[aim-kind="act"] text,
+.aim-act text {
+  text-decoration: underline;
+}
+
 .aim-node[aim-act]:hover,
 .aim-node[aim-kind="act"]:hover {
   filter: drop-shadow(0 0 6px rgba(16, 185, 129, 0.4));
@@ -115,20 +121,28 @@
   stroke-width: 1.5px;
 }
 
+.aim-node[aim-obj] text,
+.aim-node[aim-kind="obj"] text,
+.aim-obj text {
+  text-decoration: underline;
+}
+
 /* 5. Person / Actor Nodes ('per') */
 .aim-node[aim-per],
 .aim-node[aim-kind="per"],
 .aim-per {
-  fill: var(--aim-canvas-cream);
-  stroke: var(--aim-warm-graphite);
-  stroke-width: 1.5px;
-  rx: var(--aim-radius-card);
-  ry: var(--aim-radius-card);
+  fill: transparent;
+  stroke: none;
 }
 
-.aim-node[aim-per][aim-role="initiating"] {
+.aim-node[aim-per] path,
+.aim-node[aim-per] circle {
+  transition: stroke 0.15s ease;
+}
+
+.aim-node[aim-per][aim-role="initiating"] path,
+.aim-node[aim-per][aim-role="initiating"] circle {
   stroke: var(--aim-net-gold);
-  stroke-width: 2px;
 }
 
 /* Relationship Edges */

package/src/types.ts

@@ -139,6 +139,9 @@ export interface RaidEdgeData {
 
   /** User-editable or router-computed Manhattan bend points. */
   readonly bendPoints: readonly SvgBendPoint[];
+
+  /** Precomputed or live SVG path data ('M ... L ...') for standalone vector rendering. */
+  readonly pathData?: string;
 }
 
 /**
@@ -160,6 +163,9 @@ export interface RaidMetamodel {
   /** Relationships connecting projected nodes. */
   readonly edges: readonly RaidEdgeData[];
 
+  /** Diagram-level edge routing mode ('manhattan', 'normal', 'smooth'). */
+  readonly routing?: AimRoutingMode;
+
   /** Additional diagram-level metadata. */
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
@@ -201,6 +207,13 @@ export interface HydrationOptions {
   /** If true, automatically executes Manhattan routing if bend points are missing. Default: true. */
   readonly autoRouteEdges?: boolean;
 
+  /**
+   * If true, infers docking ports (e.g. port-right, port-left) based on node geometry when ports
+   * are omitted in the SVG. When false (default), edges bind directly to node cells without ports,
+   * enabling dynamic Manhattan center-aiming routing. Default: false.
+   */
+  readonly inferPorts?: boolean;
+
   /** Default fallback dimensions when width/height are unspecified in SVG. */
   readonly defaultNodeSize?: { readonly width: number; readonly height: number };
 }
@@ -217,4 +230,7 @@ export interface SerializationOptions {
 
   /** Inject Cascais design token CSS variables into `<defs><style>`. Default: true. */
   readonly embedStyles?: boolean;
+
+  /** Optional diagram-level routing mode to serialize onto root `<svg>` tag. */
+  readonly routingMode?: AimRoutingMode;
 }