feat(workflows): describe container changes and build a canvas diff overlay

The comparison engine now reports which loop and parallel fields changed and
which blocks entered or left a container, and exposes the field lists and a
shared hasChanges helper. A new overlay module merges two workflow states into
one canvas: removed blocks, containers and edges ride along as ghosts at their
old positions (nudged clear of live cards), deleted condition and router
branches stay on the surviving card so their ghost edge keeps a handle, and
every edge is classified by canonical port key. The renderer edge view gains a
quiet ghost style for those removed connections.

Author: mzxchandra

apps/sim/lib/workflows/autolayout/index.ts

@@ -100,8 +100,14 @@ export {
   getTargetedLayoutImpact,
 } from '@/lib/workflows/autolayout/change-set'
 export { applyTargetedLayout } from '@/lib/workflows/autolayout/targeted'
-export type { Edge, LayoutOptions, LayoutResult } from '@/lib/workflows/autolayout/types'
+export type {
+  BoundingBox,
+  Edge,
+  LayoutOptions,
+  LayoutResult,
+} from '@/lib/workflows/autolayout/types'
 export {
+  boxesOverlap,
   getBlockMetrics,
   isContainerType,
   shouldSkipAutoLayout,

apps/sim/lib/workflows/comparison/compare.test.ts

@@ -1620,3 +1620,114 @@ describe('generateWorkflowDiffSummary', () => {
     })
   })
 })
+
+describe('containerChanges', () => {
+  function stateWithLoop(loop: Record<string, any>, blocks: Record<string, any> = {}) {
+    return createWorkflowState({
+      blocks: {
+        loop1: createBlock('loop1', { type: 'loop', name: 'My Loop' }),
+        ...blocks,
+      },
+      loops: { loop1: { id: 'loop1', enabled: true, ...loop } },
+    })
+  }
+
+  it.concurrent('describes a reconfigured loop field by field, named after its block', () => {
+    const previous = stateWithLoop({ nodes: ['a'], loopType: 'for', iterations: 2 })
+    const current = stateWithLoop({ nodes: ['a'], loopType: 'for', iterations: 5 })
+
+    const result = generateWorkflowDiffSummary(current, previous)
+
+    expect(result.loopChanges).toEqual({ added: 0, removed: 0, modified: 1 })
+    expect(result.containerChanges).toEqual([
+      {
+        id: 'loop1',
+        kind: 'loop',
+        name: 'My Loop',
+        changes: [{ field: 'iterations', oldValue: 2, newValue: 5 }],
+        nodesAdded: [],
+        nodesRemoved: [],
+      },
+    ])
+  })
+
+  it.concurrent(
+    'reports membership moves and a loop type switch with the fields that came and went',
+    () => {
+      const previous = stateWithLoop({ nodes: ['a', 'b'], loopType: 'for', iterations: 2 })
+      const current = stateWithLoop({
+        nodes: ['b', 'c'],
+        loopType: 'forEach',
+        forEachItems: '<start.items>',
+        /* Stale count left behind by the switch; the normalized shape drops it for forEach. */
+        iterations: 2,
+      })
+
+      const [change] = generateWorkflowDiffSummary(current, previous).containerChanges
+
+      expect(change.nodesAdded).toEqual(['c'])
+      expect(change.nodesRemoved).toEqual(['a'])
+      expect(change.changes).toEqual([
+        { field: 'loopType', oldValue: 'for', newValue: 'forEach' },
+        { field: 'iterations', oldValue: 2, newValue: null },
+        { field: 'forEachItems', oldValue: null, newValue: '<start.items>' },
+      ])
+    }
+  )
+
+  it.concurrent(
+    'describes a parallel and skips containers that were added, removed or unchanged',
+    () => {
+      const previous = createWorkflowState({
+        blocks: {
+          par1: createBlock('par1', { type: 'parallel' }),
+          parGone: createBlock('parGone', { type: 'parallel' }),
+          loopSame: createBlock('loopSame', { type: 'loop' }),
+        },
+        parallels: {
+          par1: { id: 'par1', nodes: ['x'], parallelType: 'count', count: 2, enabled: true },
+          parGone: { id: 'parGone', nodes: [], parallelType: 'count', count: 1, enabled: true },
+        },
+        loops: { loopSame: { id: 'loopSame', nodes: ['y', 'z'], loopType: 'for', iterations: 1 } },
+      })
+      const current = createWorkflowState({
+        blocks: {
+          par1: createBlock('par1', { type: 'parallel' }),
+          parNew: createBlock('parNew', { type: 'parallel' }),
+          loopSame: createBlock('loopSame', { type: 'loop' }),
+        },
+        parallels: {
+          par1: {
+            id: 'par1',
+            nodes: ['x'],
+            parallelType: 'collection',
+            distribution: '<start.list>',
+            enabled: true,
+          },
+          parNew: { id: 'parNew', nodes: [], parallelType: 'count', count: 3, enabled: true },
+        },
+        /* Same membership in a different order is not a change. */
+        loops: { loopSame: { id: 'loopSame', nodes: ['z', 'y'], loopType: 'for', iterations: 1 } },
+      })
+
+      const result = generateWorkflowDiffSummary(current, previous)
+
+      expect(result.parallelChanges).toEqual({ added: 1, removed: 1, modified: 1 })
+      expect(result.loopChanges).toEqual({ added: 0, removed: 0, modified: 0 })
+      expect(result.containerChanges).toEqual([
+        {
+          id: 'par1',
+          kind: 'parallel',
+          name: 'Block par1',
+          changes: [
+            { field: 'parallelType', oldValue: 'count', newValue: 'collection' },
+            { field: 'count', oldValue: 2, newValue: null },
+            { field: 'distribution', oldValue: null, newValue: '<start.list>' },
+          ],
+          nodesAdded: [],
+          nodesRemoved: [],
+        },
+      ])
+    }
+  )
+})

apps/sim/lib/workflows/comparison/compare.ts

@@ -42,6 +42,37 @@ interface FieldChange {
   newValue: unknown
 }
 
+/** The loop configuration fields a container diff compares, in the order they are reported. */
+export const LOOP_CONFIG_FIELDS = [
+  'loopType',
+  'iterations',
+  'forEachItems',
+  'whileCondition',
+  'doWhileCondition',
+] as const
+
+/** The parallel configuration fields a container diff compares, in the order they are reported. */
+export const PARALLEL_CONFIG_FIELDS = ['parallelType', 'count', 'distribution'] as const
+
+export type ContainerConfigField =
+  | (typeof LOOP_CONFIG_FIELDS)[number]
+  | (typeof PARALLEL_CONFIG_FIELDS)[number]
+
+/**
+ * A loop or parallel container present on both sides whose configuration or
+ * membership differs. Added and removed containers are reported as blocks.
+ */
+export interface ContainerChange {
+  id: string
+  kind: 'loop' | 'parallel'
+  name?: string
+  changes: FieldChange[]
+  /** Block ids that are inside the container on the current side only */
+  nodesAdded: string[]
+  /** Block ids that were inside the container on the previous side only */
+  nodesRemoved: string[]
+}
+
 /**
  * Result of workflow diff analysis between two workflow states
  */
@@ -57,6 +88,7 @@ export interface WorkflowDiffSummary {
   }
   loopChanges: { added: number; removed: number; modified: number }
   parallelChanges: { added: number; removed: number; modified: number }
+  containerChanges: ContainerChange[]
   variableChanges: {
     added: number
     removed: number
@@ -68,6 +100,62 @@ export interface WorkflowDiffSummary {
   hasChanges: boolean
 }
 
+/**
+ * Field-by-field description of a container that changed, from the normalized
+ * shapes the equality check already uses so the two can never disagree.
+ */
+function describeContainerChange(
+  id: string,
+  kind: ContainerChange['kind'],
+  name: string | undefined,
+  current: { nodes: string[] } | null,
+  previous: { nodes: string[] } | null,
+  fields: readonly string[]
+): ContainerChange {
+  const changes: FieldChange[] = []
+  const currentRecord = (current ?? {}) as Record<string, unknown>
+  const previousRecord = (previous ?? {}) as Record<string, unknown>
+  for (const field of fields) {
+    if (normalizedStringify(currentRecord[field]) !== normalizedStringify(previousRecord[field])) {
+      changes.push({
+        field,
+        oldValue: previousRecord[field] ?? null,
+        newValue: currentRecord[field] ?? null,
+      })
+    }
+  }
+  const currentNodes = new Set(current?.nodes ?? [])
+  const previousNodes = new Set(previous?.nodes ?? [])
+  return {
+    id,
+    kind,
+    name,
+    changes,
+    nodesAdded: [...currentNodes].filter((node) => !previousNodes.has(node)),
+    nodesRemoved: [...previousNodes].filter((node) => !currentNodes.has(node)),
+  }
+}
+
+/** Whether any counted section of a summary reports a difference. */
+export function summaryHasChanges(summary: Omit<WorkflowDiffSummary, 'hasChanges'>): boolean {
+  return (
+    summary.addedBlocks.length > 0 ||
+    summary.removedBlocks.length > 0 ||
+    summary.modifiedBlocks.length > 0 ||
+    summary.edgeChanges.added > 0 ||
+    summary.edgeChanges.removed > 0 ||
+    summary.loopChanges.added > 0 ||
+    summary.loopChanges.removed > 0 ||
+    summary.loopChanges.modified > 0 ||
+    summary.parallelChanges.added > 0 ||
+    summary.parallelChanges.removed > 0 ||
+    summary.parallelChanges.modified > 0 ||
+    summary.variableChanges.added > 0 ||
+    summary.variableChanges.removed > 0 ||
+    summary.variableChanges.modified > 0
+  )
+}
+
 /**
  * Generate a detailed diff summary between two workflow states
  */
@@ -82,6 +170,7 @@ export function generateWorkflowDiffSummary(
     edgeChanges: { added: 0, removed: 0, addedDetails: [], removedDetails: [] },
     loopChanges: { added: 0, removed: 0, modified: 0 },
     parallelChanges: { added: 0, removed: 0, modified: 0 },
+    containerChanges: [],
     variableChanges: {
       added: 0,
       removed: 0,
@@ -354,10 +443,23 @@ export function generateWorkflowDiffSummary(
     if (!previousLoopIds.includes(id)) {
       result.loopChanges.added++
     } else {
-      const normalizedCurrent = normalizeValue(normalizeLoop(currentLoops[id]))
-      const normalizedPrevious = normalizeValue(normalizeLoop(previousLoops[id]))
-      if (normalizedStringify(normalizedCurrent) !== normalizedStringify(normalizedPrevious)) {
+      const normalizedCurrent = normalizeLoop(currentLoops[id])
+      const normalizedPrevious = normalizeLoop(previousLoops[id])
+      if (
+        normalizedStringify(normalizeValue(normalizedCurrent)) !==
+        normalizedStringify(normalizeValue(normalizedPrevious))
+      ) {
         result.loopChanges.modified++
+        result.containerChanges.push(
+          describeContainerChange(
+            id,
+            'loop',
+            currentBlocks[id]?.name ?? previousBlocks[id]?.name,
+            normalizedCurrent ?? null,
+            normalizedPrevious ?? null,
+            LOOP_CONFIG_FIELDS
+          )
+        )
       }
     }
   }
@@ -376,10 +478,23 @@ export function generateWorkflowDiffSummary(
     if (!previousParallelIds.includes(id)) {
       result.parallelChanges.added++
     } else {
-      const normalizedCurrent = normalizeValue(normalizeParallel(currentParallels[id]))
-      const normalizedPrevious = normalizeValue(normalizeParallel(previousParallels[id]))
-      if (normalizedStringify(normalizedCurrent) !== normalizedStringify(normalizedPrevious)) {
+      const normalizedCurrent = normalizeParallel(currentParallels[id])
+      const normalizedPrevious = normalizeParallel(previousParallels[id])
+      if (
+        normalizedStringify(normalizeValue(normalizedCurrent)) !==
+        normalizedStringify(normalizeValue(normalizedPrevious))
+      ) {
         result.parallelChanges.modified++
+        result.containerChanges.push(
+          describeContainerChange(
+            id,
+            'parallel',
+            currentBlocks[id]?.name ?? previousBlocks[id]?.name,
+            normalizedCurrent ?? null,
+            normalizedPrevious ?? null,
+            PARALLEL_CONFIG_FIELDS
+          )
+        )
       }
     }
   }
@@ -417,21 +532,7 @@ export function generateWorkflowDiffSummary(
     }
   }
 
-  result.hasChanges =
-    result.addedBlocks.length > 0 ||
-    result.removedBlocks.length > 0 ||
-    result.modifiedBlocks.length > 0 ||
-    result.edgeChanges.added > 0 ||
-    result.edgeChanges.removed > 0 ||
-    result.loopChanges.added > 0 ||
-    result.loopChanges.removed > 0 ||
-    result.loopChanges.modified > 0 ||
-    result.parallelChanges.added > 0 ||
-    result.parallelChanges.removed > 0 ||
-    result.parallelChanges.modified > 0 ||
-    result.variableChanges.added > 0 ||
-    result.variableChanges.removed > 0 ||
-    result.variableChanges.modified > 0
+  result.hasChanges = summaryHasChanges(result)
 
   return result
 }

apps/sim/lib/workflows/comparison/index.ts

@@ -1,9 +1,20 @@
 export {
+  type ContainerChange,
+  type ContainerConfigField,
   generateWorkflowDiffSummary,
   hasWorkflowChanged,
+  LOOP_CONFIG_FIELDS,
+  PARALLEL_CONFIG_FIELDS,
+  summaryHasChanges,
   type WorkflowDiffSummary,
 } from './compare'
 export {
   normalizedStringify,
   normalizeWorkflowState,
 } from './normalize'
+export {
+  type BlockDiffStatus,
+  buildWorkflowDiffOverlay,
+  type EdgeDiffStatus,
+  type WorkflowDiffOverlay,
+} from './overlay'