@codemation/next-host 0.0.1

package/src/features/workflows/components/canvas/lib/WorkflowCanvasSiIconRegistry.ts

@@ -0,0 +1,18 @@
+import type { SimpleIcon } from "simple-icons";
+import { siGmail } from "simple-icons";
+
+/**
+ * Cherry-picked Simple Icons for canvas use. Add named imports here when authors use `si:<slug>`.
+ * Prefer **builtin** assets ({@link WorkflowCanvasBuiltinIconRegistry}) for brands with official marks;
+ * use `si:` only when the icon is in `simple-icons` and not duplicated as a builtin.
+ * Authors may also set `icon` to an image URL for any brand not listed.
+ */
+export class WorkflowCanvasSiIconRegistry {
+  private static readonly slugToIcon: ReadonlyMap<string, SimpleIcon> = new Map<string, SimpleIcon>([
+    ["gmail", siGmail],
+  ]);
+
+  static resolve(slug: string): SimpleIcon | undefined {
+    return this.slugToIcon.get(slug);
+  }
+}

package/src/features/workflows/components/canvas/lib/WorkflowCanvasSymmetricForkPathPlanner.ts

@@ -0,0 +1,43 @@
+import { WORKFLOW_CANVAS_MAIN_EDGE_CORNER_RADIUS } from "./workflowCanvasEdgeGeometry";
+import { WorkflowCanvasRoundedOrthogonalPathPlanner } from "./WorkflowCanvasRoundedOrthogonalPathPlanner";
+
+/**
+ * Orthogonal path for fork edges (one source → many targets) so every branch
+ * shares the same first horizontal segment, then drops or rises vertically—mirroring
+ * how merge edges converge symmetrically on the right. Corners use the same
+ * quadratic smoothing as React Flow smoothstep edges.
+ */
+export class WorkflowCanvasSymmetricForkPathPlanner {
+  static build(
+    args: Readonly<{
+      sourceX: number;
+      sourceY: number;
+      targetX: number;
+      targetY: number;
+      offset: number;
+    }>,
+  ): Readonly<{ path: string; labelX: number; labelY: number }> {
+    const { sourceX, sourceY, targetX, targetY, offset } = args;
+    let x1 = sourceX + offset;
+    let x2 = targetX - offset;
+    if (x1 >= x2 - 0.5) {
+      const mid = (sourceX + targetX) / 2;
+      x1 = mid;
+      x2 = mid;
+    }
+    const points = [
+      { x: sourceX, y: sourceY },
+      { x: x1, y: sourceY },
+      { x: x1, y: targetY },
+      { x: x2, y: targetY },
+      { x: targetX, y: targetY },
+    ];
+    const path = WorkflowCanvasRoundedOrthogonalPathPlanner.buildPathFromPoints(
+      points,
+      WORKFLOW_CANVAS_MAIN_EDGE_CORNER_RADIUS,
+    );
+    const labelX = (x1 + x2) / 2;
+    const labelY = targetY;
+    return { path, labelX, labelY };
+  }
+}

package/src/features/workflows/components/canvas/lib/layoutWorkflow.ts

@@ -0,0 +1,315 @@
+import dagre from "dagre";
+import { MarkerType, Position, type Edge as ReactFlowEdge, type Node as ReactFlowNode } from "@xyflow/react";
+
+import type { ConnectionInvocationRecord, NodeExecutionSnapshot } from "../../../lib/realtime/realtimeDomainTypes";
+import type { WorkflowDto } from "../../../lib/realtime/workflowTypes";
+import type { WorkflowCanvasNodeData } from "./workflowCanvasNodeData";
+import { WorkflowCanvasEdgeCountResolver } from "./WorkflowCanvasEdgeCountResolver";
+import { WorkflowCanvasEdgeStyleResolver } from "./WorkflowCanvasEdgeStyleResolver";
+import {
+  WORKFLOW_CANVAS_MAIN_EDGE_CORNER_RADIUS,
+  WORKFLOW_CANVAS_MAIN_EDGE_OFFSET,
+} from "./workflowCanvasEdgeGeometry";
+import {
+  WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX,
+  WORKFLOW_CANVAS_MAIN_NODE_CARD_PX,
+  WorkflowCanvasNodeGeometry,
+} from "./workflowCanvasNodeGeometry";
+
+function mainWorkflowNodeWidthPx(role: string | undefined): number {
+  return WorkflowCanvasNodeGeometry.mainNodeWidthPx(role === "agent");
+}
+import { WorkflowCanvasOverlapResolver } from "./WorkflowCanvasOverlapResolver";
+import { WorkflowCanvasPortOrderResolver } from "./WorkflowCanvasPortOrderResolver";
+
+export function layoutWorkflow(
+  workflow: WorkflowDto,
+  nodeSnapshotsByNodeId: Readonly<Record<string, NodeExecutionSnapshot>>,
+  connectionInvocations: ReadonlyArray<ConnectionInvocationRecord>,
+  nodeStatusesByNodeId: Readonly<Record<string, NodeExecutionSnapshot["status"] | undefined>>,
+  credentialAttentionTooltipByNodeId: ReadonlyMap<string, string>,
+  selectedNodeId: string | null,
+  propertiesTargetNodeId: string | null,
+  pinnedNodeIds: ReadonlySet<string>,
+  isLiveWorkflowView: boolean,
+  isRunning: boolean,
+  workflowNodeIdsWithBoundCredential: ReadonlySet<string>,
+  onSelectNode: (nodeId: string) => void,
+  onOpenPropertiesNode: (nodeId: string) => void,
+  onRequestOpenCredentialEditForNode: (nodeId: string) => void,
+  onRunNode: (nodeId: string) => void,
+  onTogglePinnedOutput: (nodeId: string) => void,
+  onEditNodeOutput: (nodeId: string) => void,
+  onClearPinnedOutput: (nodeId: string) => void,
+): Readonly<{ nodes: ReactFlowNode<WorkflowCanvasNodeData>[]; edges: ReactFlowEdge[] }> {
+  const dagreGraph = new dagre.graphlib.Graph();
+  dagreGraph.setDefaultEdgeLabel(() => ({}));
+  dagreGraph.setGraph({ rankdir: "LR", ranksep: 128, nodesep: 56, edgesep: 20 });
+
+  const attachmentNodeWidth = WorkflowCanvasNodeGeometry.attachmentNodeWidthPx();
+  const attachmentXSpacing = attachmentNodeWidth + 36;
+  const layoutNodes = workflow.nodes.filter((node) => !node.parentNodeId);
+  const layoutNodeIds = new Set(layoutNodes.map((node) => node.id));
+  const layoutEdges = workflow.edges.filter(
+    (edge) => layoutNodeIds.has(edge.from.nodeId) && layoutNodeIds.has(edge.to.nodeId),
+  );
+
+  for (const node of layoutNodes) {
+    dagreGraph.setNode(node.id, {
+      width: mainWorkflowNodeWidthPx(node.role),
+      height: WORKFLOW_CANVAS_MAIN_NODE_CARD_PX,
+    });
+  }
+  for (const [i, edge] of layoutEdges.entries()) {
+    dagreGraph.setEdge(edge.from.nodeId, edge.to.nodeId, { i });
+  }
+
+  dagre.layout(dagreGraph);
+
+  const positionsByNodeId = new Map<string, { x: number; y: number }>();
+  for (const node of layoutNodes) {
+    const position = dagreGraph.node(node.id) as { x: number; y: number } | undefined;
+    positionsByNodeId.set(node.id, { x: position?.x ?? 0, y: position?.y ?? 0 });
+  }
+
+  const attachmentNodesByParentNodeId = new Map<string, WorkflowDto["nodes"]>();
+  for (const node of workflow.nodes) {
+    if (!node.parentNodeId) continue;
+    const siblings = attachmentNodesByParentNodeId.get(node.parentNodeId) ?? [];
+    attachmentNodesByParentNodeId.set(node.parentNodeId, [...siblings, node]);
+  }
+
+  for (const [parentNodeId, attachmentNodes] of attachmentNodesByParentNodeId.entries()) {
+    const parentPosition = positionsByNodeId.get(parentNodeId);
+    if (!parentPosition) continue;
+    const parentMeta = layoutNodes.find((n) => n.id === parentNodeId);
+    const parentLabel = parentMeta?.name ?? parentMeta?.type ?? parentNodeId;
+    const parentIsAgent = parentMeta?.role === "agent";
+    if (attachmentNodes.length === 0) {
+      continue;
+    }
+    const attachmentYOffset = WorkflowCanvasNodeGeometry.attachmentCardCenterYDeltaFromParentCardCenter(
+      parentLabel,
+      parentIsAgent,
+    );
+    const orderedAttachmentNodes = [...attachmentNodes].sort((left, right) => {
+      if (left.role === right.role) return left.name?.localeCompare(right.name ?? "") ?? 0;
+      if (left.role === "languageModel") return -1;
+      if (right.role === "languageModel") return 1;
+      return 0;
+    });
+    orderedAttachmentNodes.forEach((attachmentNode, index) => {
+      positionsByNodeId.set(attachmentNode.id, {
+        x: parentPosition.x + (index - (attachmentNodes.length - 1) / 2) * attachmentXSpacing,
+        y: parentPosition.y + attachmentYOffset,
+      });
+    });
+  }
+
+  const widthByNodeId = new Map<string, number>();
+  const heightByNodeId = new Map<string, number>();
+  for (const n of workflow.nodes) {
+    widthByNodeId.set(n.id, n.parentNodeId ? attachmentNodeWidth : mainWorkflowNodeWidthPx(n.role));
+    heightByNodeId.set(
+      n.id,
+      n.parentNodeId ? WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX : WORKFLOW_CANVAS_MAIN_NODE_CARD_PX,
+    );
+  }
+  const resolvedPositions = WorkflowCanvasOverlapResolver.resolve({
+    positionsByNodeId,
+    widthByNodeId,
+    heightByNodeId,
+    gap: 10,
+  });
+  for (const [id, pos] of resolvedPositions) {
+    positionsByNodeId.set(id, pos);
+  }
+
+  const outgoingOutputsByNodeId = new Map<string, Set<string>>();
+  const incomingInputsByNodeId = new Map<string, Set<string>>();
+  for (const edge of workflow.edges) {
+    if (!outgoingOutputsByNodeId.has(edge.from.nodeId)) {
+      outgoingOutputsByNodeId.set(edge.from.nodeId, new Set());
+    }
+    outgoingOutputsByNodeId.get(edge.from.nodeId)!.add(edge.from.output);
+    if (!incomingInputsByNodeId.has(edge.to.nodeId)) {
+      incomingInputsByNodeId.set(edge.to.nodeId, new Set());
+    }
+    incomingInputsByNodeId.get(edge.to.nodeId)!.add(edge.to.input);
+  }
+
+  const nodes: ReactFlowNode<WorkflowCanvasNodeData>[] = workflow.nodes.map((n) => {
+    const pos = positionsByNodeId.get(n.id);
+    const label = n.name ?? n.type ?? n.id;
+    const resolvedNodeWidth = n.parentNodeId ? attachmentNodeWidth : mainWorkflowNodeWidthPx(n.role);
+    const resolvedNodeHeight = n.parentNodeId
+      ? WorkflowCanvasNodeGeometry.attachmentNodeHeightPx(label)
+      : WorkflowCanvasNodeGeometry.mainNodeHeightPx(label, n.role === "agent");
+    const layoutCardHeightPx = n.parentNodeId
+      ? WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX
+      : WORKFLOW_CANVAS_MAIN_NODE_CARD_PX;
+    const rawOut = outgoingOutputsByNodeId.get(n.id);
+    const rawIn = incomingInputsByNodeId.get(n.id);
+    const sourceOutputPorts = WorkflowCanvasPortOrderResolver.sortSourceOutputs(
+      rawOut && rawOut.size > 0 ? [...rawOut] : ["main"],
+    );
+    const targetInputPorts = WorkflowCanvasPortOrderResolver.sortTargetInputs(
+      rawIn && rawIn.size > 0 ? [...rawIn] : ["in"],
+    );
+    return {
+      id: n.id,
+      type: "codemation",
+      position: {
+        x: (pos?.x ?? 0) - resolvedNodeWidth / 2,
+        y: (pos?.y ?? 0) - layoutCardHeightPx / 2,
+      },
+      width: resolvedNodeWidth,
+      height: resolvedNodeHeight,
+      initialWidth: resolvedNodeWidth,
+      initialHeight: resolvedNodeHeight,
+      data: {
+        nodeId: n.id,
+        label,
+        type: n.type,
+        kind: n.kind,
+        role: n.role,
+        icon: n.icon,
+        status: nodeStatusesByNodeId[n.id],
+        selected: selectedNodeId === n.id,
+        propertiesTarget: propertiesTargetNodeId === n.id,
+        isAttachment: Boolean(n.parentNodeId),
+        isPinned: pinnedNodeIds.has(n.id),
+        hasOutputData: Boolean(pinnedNodeIds.has(n.id) || nodeSnapshotsByNodeId[n.id]?.outputs?.main),
+        isLiveWorkflowView,
+        isRunning,
+        retryPolicySummary: n.retryPolicySummary,
+        hasNodeErrorHandler: n.hasNodeErrorHandler,
+        continueWhenEmptyOutput: n.continueWhenEmptyOutput,
+        credentialAttentionTooltip: credentialAttentionTooltipByNodeId.get(n.id),
+        sourceOutputPorts,
+        targetInputPorts,
+        onSelectNode,
+        onOpenPropertiesNode,
+        onRunNode,
+        onTogglePinnedOutput,
+        onEditNodeOutput,
+        onClearPinnedOutput,
+        showCredentialEditToolbar: isLiveWorkflowView && workflowNodeIdsWithBoundCredential.has(n.id),
+        onOpenCredentialEditFromCanvas:
+          isLiveWorkflowView && workflowNodeIdsWithBoundCredential.has(n.id)
+            ? () => onRequestOpenCredentialEditForNode(n.id)
+            : undefined,
+        layoutWidthPx: resolvedNodeWidth,
+        layoutHeightPx: resolvedNodeHeight,
+      },
+      draggable: false,
+      sourcePosition: n.parentNodeId ? Position.Bottom : Position.Right,
+      targetPosition: n.parentNodeId ? Position.Top : Position.Left,
+    };
+  });
+
+  const nodesById = new Map(workflow.nodes.map((node) => [node.id, node]));
+  const edges: ReactFlowEdge[] = workflow.edges.map((e, i) => {
+    const targetNode = nodesById.get(e.to.nodeId);
+    const isAttachmentEdge = targetNode?.role === "languageModel" || targetNode?.role === "tool";
+    const attachmentSourceHandle =
+      targetNode?.role === "languageModel"
+        ? "attachment-llm-source"
+        : targetNode?.role === "tool"
+          ? "attachment-tools-source"
+          : undefined;
+    const outgoingFromSourceCount = outgoingOutputsByNodeId.get(e.from.nodeId)?.size ?? 0;
+    const incomingToTargetCount = incomingInputsByNodeId.get(e.to.nodeId)?.size ?? 0;
+    const useSharedBranchSourceHandle = !isAttachmentEdge && outgoingFromSourceCount > 1;
+    const useSharedBranchTargetHandle = !isAttachmentEdge && incomingToTargetCount > 1;
+    const sourcePosition = positionsByNodeId.get(e.from.nodeId);
+    const targetPosition = positionsByNodeId.get(e.to.nodeId);
+    const isStraightMainEdge = !isAttachmentEdge && Math.abs((sourcePosition?.y ?? 0) - (targetPosition?.y ?? 0)) < 1;
+    const targetSnapshot = nodeSnapshotsByNodeId[e.to.nodeId];
+    const sourceSnapshot = nodeSnapshotsByNodeId[e.from.nodeId];
+    const edgeItemCount = WorkflowCanvasEdgeCountResolver.resolveCount({
+      targetNodeId: e.to.nodeId,
+      targetNodeRole: targetNode?.role,
+      targetInput: e.to.input,
+      sourceOutput: e.from.output,
+      sourceSnapshot,
+      targetSnapshot,
+      nodeSnapshotsByNodeId,
+      connectionInvocations,
+    });
+    const edgeLabel = edgeItemCount > 0 ? `${edgeItemCount} item${edgeItemCount === 1 ? "" : "s"}` : undefined;
+    const edgeStroke = WorkflowCanvasEdgeStyleResolver.resolveStrokeColor({
+      edgeItemCount,
+      isAttachmentEdge,
+    });
+    const mainSourceHandle = isAttachmentEdge
+      ? attachmentSourceHandle
+      : useSharedBranchSourceHandle
+        ? undefined
+        : e.from.output;
+    const mainTargetHandle = isAttachmentEdge
+      ? "attachment-target"
+      : useSharedBranchTargetHandle
+        ? undefined
+        : e.to.input;
+    const isForkOutgoingEdge = !isAttachmentEdge && !isStraightMainEdge && outgoingFromSourceCount > 1;
+    return {
+      id: `${e.from.nodeId}:${e.from.output}->${e.to.nodeId}:${e.to.input}:${i}`,
+      source: e.from.nodeId,
+      target: e.to.nodeId,
+      sourceHandle: mainSourceHandle,
+      targetHandle: mainTargetHandle,
+      animated: false,
+      type: isAttachmentEdge
+        ? "smoothstep"
+        : isStraightMainEdge
+          ? "straightCount"
+          : isForkOutgoingEdge
+            ? "symmetricFork"
+            : "smoothstep",
+      pathOptions:
+        isAttachmentEdge || isStraightMainEdge || isForkOutgoingEdge
+          ? undefined
+          : {
+              borderRadius: WORKFLOW_CANVAS_MAIN_EDGE_CORNER_RADIUS,
+              offset: WORKFLOW_CANVAS_MAIN_EDGE_OFFSET,
+              stepPosition: 0.5,
+            },
+      style: {
+        stroke: edgeStroke,
+        strokeWidth: isAttachmentEdge ? 1.35 : 1.5,
+        strokeDasharray: isAttachmentEdge ? "2 6" : undefined,
+        strokeLinecap: isAttachmentEdge ? "round" : "round",
+        strokeLinejoin: isAttachmentEdge ? undefined : "round",
+      },
+      label: edgeLabel,
+      labelStyle: {
+        fill: WorkflowCanvasEdgeStyleResolver.resolveLabelFill({
+          edgeItemCount,
+          isAttachmentEdge,
+        }),
+        fontSize: isAttachmentEdge ? 10 : 11,
+        fontWeight: 800,
+      },
+      labelBgStyle: {
+        fill: WorkflowCanvasEdgeStyleResolver.resolveLabelBackground({
+          edgeItemCount,
+          isAttachmentEdge,
+        }),
+        fillOpacity: 1,
+      },
+      labelBgPadding: isAttachmentEdge ? [4, 2] : [6, 3],
+      labelBgBorderRadius: 4,
+      markerEnd: isAttachmentEdge
+        ? undefined
+        : {
+            type: MarkerType.ArrowClosed,
+            width: 18,
+            height: 18,
+            color: edgeStroke,
+          },
+    };
+  });
+
+  return { nodes, edges };
+}

package/src/features/workflows/components/canvas/lib/workflowCanvasEdgeGeometry.ts

@@ -0,0 +1,3 @@
+/** Matches `smoothstep` `pathOptions` on non-fork main edges (merge / chain). */
+export const WORKFLOW_CANVAS_MAIN_EDGE_CORNER_RADIUS = 6;
+export const WORKFLOW_CANVAS_MAIN_EDGE_OFFSET = 34;

package/src/features/workflows/components/canvas/lib/workflowCanvasEmbeddedStyles.ts

@@ -0,0 +1,62 @@
+export const WORKFLOW_CANVAS_EMBEDDED_STYLES = `
+        @property --codemation-node-ring-angle {
+          syntax: "<angle>";
+          initial-value: 0deg;
+          inherits: false;
+        }
+
+        @keyframes codemationNodeSpin {
+          from {
+            transform: rotate(0deg);
+          }
+          to {
+            transform: rotate(360deg);
+          }
+        }
+
+        @keyframes codemationNodeBreath {
+          0%,
+          100% {
+            opacity: 0.45;
+            transform: scale(0.992);
+          }
+          45% {
+            opacity: 0.92;
+            transform: scale(1.018);
+          }
+          70% {
+            opacity: 0.72;
+            transform: scale(1.003);
+          }
+        }
+
+        @keyframes codemationNodeRingRotate {
+          from {
+            --codemation-node-ring-angle: 0deg;
+          }
+          to {
+            --codemation-node-ring-angle: 360deg;
+          }
+        }
+
+        @keyframes codemationCanvasLoaderPulse {
+          0%,
+          100% {
+            opacity: 0.45;
+            transform: scale(0.9);
+          }
+          50% {
+            opacity: 1;
+            transform: scale(1);
+          }
+        }
+
+        @keyframes codemationCanvasLoaderShimmer {
+          0% {
+            background-position: 200% 0;
+          }
+          100% {
+            background-position: -200% 0;
+          }
+        }
+      `;

package/src/features/workflows/components/canvas/lib/workflowCanvasFlowTypes.ts

@@ -0,0 +1,10 @@
+import { CodemationNode } from "../WorkflowCanvasCodemationNode";
+import { StraightCountEdge } from "../WorkflowCanvasStraightCountEdge";
+import { WorkflowCanvasSymmetricForkEdge } from "../WorkflowCanvasSymmetricForkEdge";
+
+export const workflowCanvasNodeTypes = { codemation: CodemationNode };
+
+export const workflowCanvasEdgeTypes = {
+  straightCount: StraightCountEdge,
+  symmetricFork: WorkflowCanvasSymmetricForkEdge,
+};

package/src/features/workflows/components/canvas/lib/workflowCanvasNodeData.ts

@@ -0,0 +1,41 @@
+import type { NodeExecutionSnapshot } from "../../../lib/realtime/realtimeDomainTypes";
+
+export type WorkflowCanvasNodeData = Readonly<{
+  nodeId: string;
+  label: string;
+  type: string;
+  kind: string;
+  role?: string;
+  icon?: string;
+  status?: NodeExecutionSnapshot["status"];
+  selected: boolean;
+  propertiesTarget: boolean;
+  isAttachment: boolean;
+  isPinned: boolean;
+  hasOutputData: boolean;
+  isLiveWorkflowView: boolean;
+  isRunning: boolean;
+  retryPolicySummary?: string;
+  hasNodeErrorHandler?: boolean;
+  /** When true, empty main batches still schedule downstream; surfaced on the canvas. */
+  continueWhenEmptyOutput?: boolean;
+  /** When set, show a credential warning icon with this tooltip (required slot unbound). */
+  credentialAttentionTooltip?: string;
+  /** Distinct source output port names on this node (for multi-handle Right routing). */
+  sourceOutputPorts: readonly string[];
+  /** Distinct target input port names on this node (for multi-handle Left routing). */
+  targetInputPorts: readonly string[];
+  /** Matches Dagre / React Flow measured bounds (label wrap + agent badge row). */
+  layoutWidthPx: number;
+  layoutHeightPx: number;
+  onSelectNode: (nodeId: string) => void;
+  onOpenPropertiesNode: (nodeId: string) => void;
+  onRunNode: (nodeId: string) => void;
+  onTogglePinnedOutput: (nodeId: string) => void;
+  onEditNodeOutput: (nodeId: string) => void;
+  onClearPinnedOutput: (nodeId: string) => void;
+  /** Live workflow: node has a bound credential — toolbar can open the edit dialog. */
+  showCredentialEditToolbar?: boolean;
+  /** Opens properties (if needed) and the credential edit dialog for this node. */
+  onOpenCredentialEditFromCanvas?: () => void;
+}>;

package/src/features/workflows/components/canvas/lib/workflowCanvasNodeGeometry.ts

@@ -0,0 +1,99 @@
+import { WorkflowCanvasLabelLayoutEstimator } from "./WorkflowCanvasLabelLayoutEstimator";
+
+/** Main workflow node: square card + optional agent badge row + label strip below (React Flow node bounds). ~10% larger than initial canvas revision. */
+export const WORKFLOW_CANVAS_MAIN_NODE_CARD_PX = 92;
+/** AI Agent: wider card with the node title inline next to the icon (no separate label strip below the card). */
+export const WORKFLOW_CANVAS_AGENT_NODE_CARD_WIDTH_PX = 220;
+export const WORKFLOW_CANVAS_MAIN_NODE_LABEL_GAP_PX = 5;
+export const WORKFLOW_CANVAS_MAIN_NODE_ICON_PX = 22;
+/** Unified stroke for Lucide canvas glyphs (matches visual weight of filled brand marks). */
+export const WORKFLOW_CANVAS_NODE_ICON_STROKE_WIDTH = 2;
+export const WORKFLOW_CANVAS_MAIN_NODE_LABEL_FONT_PX = 13;
+export const WORKFLOW_CANVAS_MAIN_NODE_LABEL_LINE_HEIGHT = 1.25;
+
+/** Attachment nodes (LLM/tools): smaller square + label below. */
+export const WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX = 74;
+export const WORKFLOW_CANVAS_ATTACHMENT_NODE_LABEL_GAP_PX = 5;
+/** Proportional to main card icon (~22×74/92); keeps attachment row readable vs main row. */
+export const WORKFLOW_CANVAS_ATTACHMENT_NODE_ICON_PX = 18;
+export const WORKFLOW_CANVAS_ATTACHMENT_NODE_LABEL_FONT_PX = 12;
+export const WORKFLOW_CANVAS_ATTACHMENT_NODE_LABEL_LINE_HEIGHT = 1.25;
+
+/** Horizontal padding inside label (matches LabelBelow padding). */
+export const WORKFLOW_CANVAS_LABEL_HORIZONTAL_PADDING_PX = 9;
+
+/** In-flow row under agent card for LLM / Tools chips (see WorkflowCanvasCodemationNodeAgentLabels). */
+export const WORKFLOW_CANVAS_AGENT_BADGE_ROW_PX = 24;
+
+/** Vertical gap between main node bottom and attachment row center line (layout). Extra slack so edges clear agent labels/badges. */
+export const WORKFLOW_CANVAS_ATTACHMENT_STACK_GAP_PX = 50;
+
+export class WorkflowCanvasNodeGeometry {
+  static mainNodeWidthPx(isAgent: boolean): number {
+    return isAgent ? WORKFLOW_CANVAS_AGENT_NODE_CARD_WIDTH_PX : WORKFLOW_CANVAS_MAIN_NODE_CARD_PX;
+  }
+
+  static mainNodeLabelBlockHeightPx(label: string): number {
+    const maxW = Math.max(32, WORKFLOW_CANVAS_MAIN_NODE_CARD_PX - WORKFLOW_CANVAS_LABEL_HORIZONTAL_PADDING_PX);
+    const lines = WorkflowCanvasLabelLayoutEstimator.estimateLineCount(
+      label,
+      maxW,
+      WORKFLOW_CANVAS_MAIN_NODE_LABEL_FONT_PX,
+    );
+    const lineHeightPx = WORKFLOW_CANVAS_MAIN_NODE_LABEL_FONT_PX * WORKFLOW_CANVAS_MAIN_NODE_LABEL_LINE_HEIGHT;
+    return lines * lineHeightPx + 2;
+  }
+
+  static mainNodeHeightPx(label: string, isAgent: boolean): number {
+    const badge = isAgent ? WORKFLOW_CANVAS_AGENT_BADGE_ROW_PX : 0;
+    const labelBelowCard = isAgent ? 0 : this.mainNodeLabelBlockHeightPx(label);
+    return WORKFLOW_CANVAS_MAIN_NODE_CARD_PX + WORKFLOW_CANVAS_MAIN_NODE_LABEL_GAP_PX + badge + labelBelowCard;
+  }
+
+  static attachmentNodeWidthPx(): number {
+    return WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX;
+  }
+
+  static attachmentNodeLabelBlockHeightPx(label: string): number {
+    const maxW = Math.max(28, WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX - WORKFLOW_CANVAS_LABEL_HORIZONTAL_PADDING_PX);
+    const lines = WorkflowCanvasLabelLayoutEstimator.estimateLineCount(
+      label,
+      maxW,
+      WORKFLOW_CANVAS_ATTACHMENT_NODE_LABEL_FONT_PX,
+    );
+    const lineHeightPx =
+      WORKFLOW_CANVAS_ATTACHMENT_NODE_LABEL_FONT_PX * WORKFLOW_CANVAS_ATTACHMENT_NODE_LABEL_LINE_HEIGHT;
+    return lines * lineHeightPx + 2;
+  }
+
+  static attachmentNodeHeightPx(label: string): number {
+    return (
+      WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX +
+      WORKFLOW_CANVAS_ATTACHMENT_NODE_LABEL_GAP_PX +
+      this.attachmentNodeLabelBlockHeightPx(label)
+    );
+  }
+
+  /**
+   * Vertical distance from the bottom of the main node card to the bottom of the shell content
+   * (gap, optional agent badge row, label block). Used to place attachment card centers from the
+   * parent card center when Dagre aligns by card square only.
+   */
+  static verticalExtentBelowParentMainCard(parentLabel: string, parentIsAgent: boolean): number {
+    const badge = parentIsAgent ? WORKFLOW_CANVAS_AGENT_BADGE_ROW_PX : 0;
+    const labelBelowCard = parentIsAgent ? 0 : this.mainNodeLabelBlockHeightPx(parentLabel);
+    return WORKFLOW_CANVAS_MAIN_NODE_LABEL_GAP_PX + badge + labelBelowCard;
+  }
+
+  /**
+   * Delta Y from parent main-node **card center** to child attachment **card center** (siblings share one row).
+   */
+  static attachmentCardCenterYDeltaFromParentCardCenter(parentLabel: string, parentIsAgent: boolean): number {
+    return (
+      WORKFLOW_CANVAS_MAIN_NODE_CARD_PX / 2 +
+      this.verticalExtentBelowParentMainCard(parentLabel, parentIsAgent) +
+      WORKFLOW_CANVAS_ATTACHMENT_STACK_GAP_PX +
+      WORKFLOW_CANVAS_ATTACHMENT_NODE_CARD_PX / 2
+    );
+  }
+}

package/src/features/workflows/components/canvas/workflowCanvasNodeChrome.tsx

@@ -0,0 +1,46 @@
+import { CircleAlert, CircleCheckBig, Clock3, Pin } from "lucide-react";
+
+import type { NodeExecutionSnapshot } from "../../hooks/realtime/realtime";
+
+export function statusIconForNode(status: NodeExecutionSnapshot["status"] | undefined) {
+  if (status === "completed") {
+    return <CircleCheckBig size={15} style={{ color: "#15803d" }} strokeWidth={2.1} />;
+  }
+  if (status === "skipped") {
+    return <Clock3 size={15} style={{ color: "#d97706" }} strokeWidth={2.1} />;
+  }
+  if (status === "failed") {
+    return <CircleAlert size={15} style={{ color: "#b91c1c" }} strokeWidth={2.1} />;
+  }
+  if (status === "running" || status === "queued" || status === "pending" || typeof status === "undefined") {
+    return null;
+  }
+  return null;
+}
+
+export function trailingIconForNode(
+  args: Readonly<{ status: NodeExecutionSnapshot["status"] | undefined; isPinned: boolean }>,
+) {
+  if (args.isPinned) {
+    return <Pin size={14} style={{ color: "#6d28d9" }} strokeWidth={2.4} fill="currentColor" />;
+  }
+  return statusIconForNode(args.status);
+}
+
+export function trailingIconKindForNode(
+  args: Readonly<{ status: NodeExecutionSnapshot["status"] | undefined; isPinned: boolean }>,
+): string {
+  if (args.isPinned) {
+    return "pin";
+  }
+  if (args.status === "completed") {
+    return "completed";
+  }
+  if (args.status === "skipped") {
+    return "skipped";
+  }
+  if (args.status === "failed") {
+    return "failed";
+  }
+  return "none";
+}

package/src/features/workflows/components/realtime/RealtimeContext.tsx

@@ -0,0 +1,14 @@
+"use client";
+
+import { createContext } from "react";
+
+import type { RetainWorkflowSubscription } from "../../lib/realtime/realtimeClientBridge";
+
+export type RealtimeContextValue = Readonly<{
+  retainWorkflowSubscription: RetainWorkflowSubscription;
+  isConnected: boolean;
+  /** True when the workflow websocket transport is closed (not while connecting or before the first socket opens). */
+  showDisconnectedBadge: boolean;
+}>;
+
+export const RealtimeContext = createContext<RealtimeContextValue | null>(null);

package/src/features/workflows/components/realtime/WorkflowRealtimeProvider.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import type { Logger } from "@codemation/host-src/application/logging/Logger";
+import type { ReactNode } from "react";
+
+import { RealtimeContext } from "./RealtimeContext";
+import { useWorkflowRealtimeInfrastructure } from "../../hooks/realtime/useWorkflowRealtimeInfrastructure";
+
+export function WorkflowRealtimeProvider(
+  args: Readonly<{ children: ReactNode; logger: Logger; websocketPort?: string }>,
+) {
+  const { children, logger, websocketPort } = args;
+  const value = useWorkflowRealtimeInfrastructure({ logger, websocketPort });
+  return <RealtimeContext.Provider value={value}>{children}</RealtimeContext.Provider>;
+}