@dr2rai/raid-canvas 0.1.0 → 0.2.0

package/src/X6Shapes.ts

@@ -9,12 +9,14 @@
  * - Cascais Heraldry design tokens.
  */
 
-import { Graph, Node, Edge } from '@antv/x6';
+import { Graph, Shape, Node, Edge } from '@antv/x6';
 import type {
+  AimOntologyKind,
   AimEdgeKind,
   RaidNodeData,
   RaidEdgeData,
   OrthogonalPortId,
+  Bounds,
 } from './types.js';
 
 /**
@@ -105,9 +107,9 @@ export function registerAimShapes(): void {
   }
 
   // 1. AimUseCaseNode ('uc') — Ellipse with Net Gold border
-  Node.define({
+  Shape.Ellipse.define({
     shape: 'aim-uc',
-    inherit: 'ellipse',
+    overwrite: true,
     width: 140,
     height: 70,
     attrs: {
@@ -115,8 +117,6 @@ export function registerAimShapes(): void {
         fill: CascaisPalette.ChalkWhite,
         stroke: CascaisPalette.NetGold,
         strokeWidth: 2,
-        rx: 70,
-        ry: 35,
         class: 'aim-node aim-uc',
       },
       label: {
@@ -133,9 +133,9 @@ export function registerAimShapes(): void {
   });
 
   // 2. AimActivityNode ('act') — Rounded rectangle with Heraldic Green border
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-act',
-    inherit: 'rect',
+    overwrite: true,
     width: 150,
     height: 60,
     attrs: {
@@ -161,9 +161,9 @@ export function registerAimShapes(): void {
   });
 
   // 3. AimClassNode ('cls') — Compartmentalized class card
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-cls',
-    inherit: 'rect',
+    overwrite: true,
     width: 180,
     height: 100,
     markup: [
@@ -258,9 +258,9 @@ export function registerAimShapes(): void {
   });
 
   // 4. AimObjectNode ('obj') — Instance card with underlined title
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-obj',
-    inherit: 'rect',
+    overwrite: true,
     width: 160,
     height: 80,
     attrs: {
@@ -271,7 +271,7 @@ export function registerAimShapes(): void {
         class: 'aim-node aim-obj',
       },
       label: {
-        text: '<u>instance: Type</u>',
+        text: 'instance: Type',
         fill: CascaisPalette.TextPrimary,
         fontSize: 12,
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
@@ -283,9 +283,9 @@ export function registerAimShapes(): void {
   });
 
   // 5. AimPersonNode ('per') — Person / Actor role card
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-per',
-    inherit: 'rect',
+    overwrite: true,
     width: 120,
     height: 70,
     attrs: {
@@ -311,9 +311,9 @@ export function registerAimShapes(): void {
   });
 
   // 6. AimEdge — Orthogonal Manhattan edge with rounded corners
-  Edge.define({
+  Shape.Edge.define({
     shape: 'aim-edge',
-    inherit: 'edge',
+    overwrite: true,
     router: {
       name: 'manhattan',
       args: {
@@ -509,8 +509,11 @@ function getEdgeStyling(kind: AimEdgeKind): Record<string, unknown> {
         strokeWidth: 1.5,
         strokeDasharray: '5,5',
         targetMarker: {
-          name: 'open',
-          size: 8,
+          name: 'block',
+          args: {
+            size: 8,
+            open: true,
+          },
         },
       };
 
@@ -573,3 +576,48 @@ function getEdgeStyling(kind: AimEdgeKind): Record<string, unknown> {
       };
   }
 }
+
+/**
+ * Returns default Cartesian bounds for an instantiated AOAIM archetype.
+ */
+export function getDefaultNodeBounds(
+  kind: AimOntologyKind | string,
+  x: number = 100,
+  y: number = 100,
+): Bounds {
+  switch (kind) {
+    case 'uc':
+      return { x, y, width: 140, height: 70 };
+    case 'act':
+      return { x, y, width: 150, height: 60 };
+    case 'cls':
+      return { x, y, width: 180, height: 110 };
+    case 'obj':
+      return { x, y, width: 160, height: 80 };
+    case 'per':
+      return { x, y, width: 120, height: 70 };
+    default:
+      return { x, y, width: 140, height: 60 };
+  }
+}
+
+/**
+ * Returns a canonical default display name for an instantiated AOAIM archetype.
+ */
+export function getDefaultNodeName(kind: AimOntologyKind | string): string {
+  switch (kind) {
+    case 'uc':
+      return 'New UseCase';
+    case 'act':
+      return 'New Activity';
+    case 'cls':
+      return 'NewClass';
+    case 'obj':
+      return 'new Object';
+    case 'per':
+      return 'Actor';
+    default:
+      return 'Entity';
+  }
+}
+

package/src/index.ts

@@ -7,6 +7,8 @@
  * - 4-way orthogonal ports and Manhattan router integration.
  * - Cascais Heraldry design tokens and theme styling.
  * - Bidirectional RaiBridge for hydrating from and serializing to the aim-* SVG contract.
+ * - Anti-entropy semantic connection validation and wiring rules.
+ * - Reusable <RaidCanvas /> React component with Dnd and imperative control handle.
  */
 
 // Core Metamodel & SVG Contract Types
@@ -33,7 +35,28 @@ export {
   configureAimGraph,
   createAimNode,
   createAimEdge,
+  getDefaultNodeBounds,
+  getDefaultNodeName,
 } from './X6Shapes.js';
 
+// Anti-Entropy Semantic Connection Rules
+export {
+  SEMANTIC_RULES_MATRIX,
+  validateSemanticConnection,
+  getSemanticEdgeKind,
+  getSemanticEdgeStereotype,
+  getSemanticRuleDescription,
+  getAvailableStereotypes,
+  type SemanticRule,
+  type StereotypeOption,
+} from './semanticRules.js';
+
 // Bidirectional SVG <-> X6 Synchronization Bridge
 export { RaiBridge } from './RaiBridge.js';
+
+// Reusable React Canvas Component & Ref Handle
+export {
+  RaidCanvas,
+  type RaidCanvasProps,
+  type RaidCanvasHandle,
+} from './RaidCanvas.js';

package/src/semanticRules.ts

@@ -0,0 +1,237 @@
+/**
+ * @file semanticRules.ts
+ * @description Anti-entropy semantic connection validation and wiring rules
+ * for the AOAIM (Activity-Object-AI Model) graphical modeling contract.
+ *
+ * Enforces ontological integrity during edge creation:
+ * - 'per' -> 'uc'  : 'association' («initiates», «owns» [0..1], «participates» [0..*])
+ * - 'per' -> 'act' : 'association' («executes»)
+ * - 'uc'  -> 'uc'  : 'dependency'  («includes», «extends», «dependsOn»)
+ * - 'uc'  -> 'act' : 'dependency'  («includes»)
+ * - 'act' -> 'act' : 'association' («sequence» / process flow)
+ * - 'cls' -> 'cls' : 'association' («relatesTo»), 'generalization', 'composition', 'aggregation'
+ * - 'cls' -> 'obj' : 'dependency'  («instantiates»)
+ * - 'obj' -> 'obj' : 'association' («link»)
+ */
+
+import type { AimOntologyKind, AimEdgeKind } from './types.js';
+
+export interface StereotypeOption {
+  readonly stereotype: string;
+  readonly defaultCardinality?: string;
+  readonly description: string;
+}
+
+export interface SemanticRule {
+  readonly valid: boolean;
+  readonly defaultEdgeKind: AimEdgeKind;
+  readonly defaultStereotype: string;
+  readonly defaultCardinality?: string;
+  readonly availableStereotypes: readonly StereotypeOption[];
+  readonly description: string;
+}
+
+/**
+ * Ontological connection rules matrix.
+ * Key: `${sourceKind}->${targetKind}`
+ */
+export const SEMANTIC_RULES_MATRIX: Readonly<Record<string, SemanticRule>> = {
+  'per->uc': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«initiates»',
+    description: 'Actor initiates, owns, or participates in UseCase',
+    availableStereotypes: [
+      {
+        stereotype: '«initiates»',
+        defaultCardinality: '1',
+        description: 'Initiating role triggering the UseCase flow',
+      },
+      {
+        stereotype: '«owns»',
+        defaultCardinality: '0..1',
+        description: 'Ownership relationship representing responsible party (cardinality 0..1)',
+      },
+      {
+        stereotype: '«participates»',
+        defaultCardinality: '0..*',
+        description: 'Participating role supporting the UseCase execution (cardinality 0..*)',
+      },
+    ],
+  },
+  'per->act': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«executes»',
+    description: 'Actor directly performs or executes Activity',
+    availableStereotypes: [
+      {
+        stereotype: '«executes»',
+        description: 'Actor performs this process step',
+      },
+      {
+        stereotype: '«approves»',
+        description: 'Actor reviews or approves activity completion',
+      },
+    ],
+  },
+  'uc->uc': {
+    valid: true,
+    defaultEdgeKind: 'dependency',
+    defaultStereotype: '«includes»',
+    description: 'UseCase includes or extends sub-UseCase',
+    availableStereotypes: [
+      {
+        stereotype: '«includes»',
+        description: 'Mandatory sub-flow inclusion dependency',
+      },
+      {
+        stereotype: '«extends»',
+        description: 'Optional conditional extension point',
+      },
+      {
+        stereotype: '«dependsOn»',
+        description: 'Prerequisite functional dependency',
+      },
+    ],
+  },
+  'uc->act': {
+    valid: true,
+    defaultEdgeKind: 'dependency',
+    defaultStereotype: '«includes»',
+    description: 'UseCase elaborates downflow process Activity',
+    availableStereotypes: [
+      {
+        stereotype: '«includes»',
+        description: 'Process activity required by UseCase',
+      },
+      {
+        stereotype: '«triggers»',
+        description: 'UseCase execution triggers activity',
+      },
+    ],
+  },
+  'act->act': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«sequence»',
+    description: 'Activity transitions to next process step',
+    availableStereotypes: [
+      {
+        stereotype: '«sequence»',
+        description: 'Sequential process transition',
+      },
+      {
+        stereotype: '«branch»',
+        description: 'Conditional decision branch',
+      },
+    ],
+  },
+  'cls->cls': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«relatesTo»',
+    description: 'Domain structural relationship between Classes',
+    availableStereotypes: [
+      {
+        stereotype: '«relatesTo»',
+        defaultCardinality: '1..*',
+        description: 'General domain association',
+      },
+      {
+        stereotype: '«generalization»',
+        description: 'Inheritance classification (subclass is-a superclass)',
+      },
+      {
+        stereotype: '«composition»',
+        defaultCardinality: '1',
+        description: 'Composite whole-part lifecycle binding',
+      },
+      {
+        stereotype: '«aggregation»',
+        defaultCardinality: '0..*',
+        description: 'Shared aggregation relationship',
+      },
+    ],
+  },
+  'cls->obj': {
+    valid: true,
+    defaultEdgeKind: 'dependency',
+    defaultStereotype: '«instantiates»',
+    description: 'Class specifies runtime Object instance',
+    availableStereotypes: [
+      {
+        stereotype: '«instantiates»',
+        description: 'Class defines schema for runtime instance',
+      },
+    ],
+  },
+  'obj->obj': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«link»',
+    description: 'Runtime communication link between Objects',
+    availableStereotypes: [
+      {
+        stereotype: '«link»',
+        description: 'Runtime object collaboration message link',
+      },
+    ],
+  },
+};
+
+/**
+ * Validates whether an edge connection between source and target archetypes is ontologically allowed.
+ */
+export function validateSemanticConnection(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): boolean {
+  if (!sourceKind || !targetKind) return false;
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.valid ?? false;
+}
+
+/**
+ * Determines the canonical default relationship edge kind for a connected pair.
+ */
+export function getSemanticEdgeKind(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): AimEdgeKind {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.defaultEdgeKind ?? 'association';
+}
+
+/**
+ * Determines the canonical default stereotype annotation for a connected pair.
+ */
+export function getSemanticEdgeStereotype(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): string {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.defaultStereotype ?? '';
+}
+
+/**
+ * Returns available ontological stereotypes and their default cardinalities for a pair.
+ */
+export function getAvailableStereotypes(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): readonly StereotypeOption[] {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.availableStereotypes ?? [];
+}
+
+/**
+ * Returns a human-readable description explaining the ontological relationship.
+ */
+export function getSemanticRuleDescription(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): string {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.description ?? 'Invalid ontological connection';
+}