fix: make the digest the sole authority on minimap repaints

The digest existed but two paths bypassed it: the graphChanged event hook
repainted unconditionally - so a bring-to-front from any widget
pointerdown still forced a full rebuild - and the execution watcher
forced a redraw per progress message. Both now funnel through one
checkAndRepaint that compares digests first; events are hints to check,
not commands to repaint.

For that to be safe the digests must cover everything the renderer
reads, so they now include node bgcolor, groups (position, size,
colour) and per-node execution state, split into a geometry digest that
drives bounds recomputation and a visual digest that only repaints. The
execution deep watcher is deleted outright: state is drawn as discrete
outline colours, so the poll picks up each transition within a tick and
a run costs zero work per progress message. Group drags, previously
tracked by nothing, now repaint too.

Fixes a poll-lifecycle regression from the earlier canvas gating: init()
runs synchronously from the immediate canvas watcher, before the
template ref mounts, so a start decision taken inside init() saw a null
canvasRef and never started the loop - events masked it. Polling is now
derived state: watch(initialized && canDraw && !hidden), started and
stopped as conditions change rather than decided once.

Every new behaviour is mutation-tested: dropping the bgcolor, group or
execution terms, reverting the event gate to an unconditional repaint,
or restoring the one-shot init decision each fails a named test.
Verified in-browser: a widget click now changes zero minimap pixels;
drags, adds and removes still repaint.

Author: benjcooley

src/renderer/extensions/minimap/composables/useMinimap.intervalLifecycle.test.ts

@@ -204,6 +204,66 @@ describe('useMinimap change-detection interval', () => {
     }
   })
 
+  it('a graphChanged event with nothing drawn changed does not repaint', async () => {
+    // graphChanged fires for zIndex (every widget pointerdown), widget values
+    // and title edits. The event is a hint to compare digests, not a command
+    // to repaint.
+    const { api } = await import('@/scripts/api')
+    await initMinimap()
+    await vi.advanceTimersByTimeAsync(POLL_MS + 10)
+    const settled = drawCalls()
+
+    const graphChangedHandler = vi
+      .mocked(api.addEventListener)
+      .mock.calls.find(([name]) => name === 'graphChanged')?.[1] as () => void
+    expect(graphChangedHandler).toBeTypeOf('function')
+
+    graphChangedHandler()
+    await vi.advanceTimersByTimeAsync(POLL_MS * 6)
+    expect(drawCalls()).toBe(settled)
+
+    // The same path must still repaint when the picture did change.
+    moveNode()
+    graphChangedHandler()
+    await vi.advanceTimersByTimeAsync(POLL_MS + 10)
+    expect(drawCalls()).toBeGreaterThan(settled)
+  })
+
+  it('starts polling when the canvas mounts after init', async () => {
+    // In the real component init() runs synchronously from the immediate
+    // canvas watcher, before the template ref has mounted, so a start decision
+    // taken inside init() sees a null canvasRef and never starts the loop.
+    const canvasRef = shallowRef<HTMLCanvasElement | null>(null)
+    const container = {
+      getBoundingClientRect: vi.fn(() => new DOMRect(0, 0, 250, 200) as DOMRect)
+    }
+    const minimap = useMinimap({
+      containerRefMaybe: shallowRef(
+        container as Partial<HTMLDivElement> as HTMLDivElement
+      ),
+      canvasRefMaybe: canvasRef
+    })
+    active = minimap
+    await minimap.init()
+    await nextTick()
+
+    // Template ref mounts after init.
+    canvasRef.value = createMockMinimapCanvas({
+      getContext: vi
+        .fn()
+        .mockImplementation((id) =>
+          id === '2d' ? context : null
+        ) as HTMLCanvasElement['getContext']
+    })
+    await nextTick()
+    await vi.runOnlyPendingTimersAsync()
+
+    moveNode()
+    await vi.advanceTimersByTimeAsync(POLL_MS + 10)
+
+    expect(drawCalls()).toBeGreaterThan(0)
+  })
+
   it('stops polling after destroy', async () => {
     const minimap = await initMinimap()
     minimap.destroy()

src/renderer/extensions/minimap/composables/useMinimap.ts

@@ -5,7 +5,6 @@ import type { ShallowRef } from 'vue'
 import type { LGraph } from '@/lib/litegraph/src/litegraph'
 import { useSettingStore } from '@/platform/settings/settingStore'
 import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
-import { useExecutionStore } from '@/stores/executionStore'
 import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
 
 import type { MinimapCanvas, MinimapSettingsKey } from '../types'
@@ -15,7 +14,7 @@ import { useMinimapRenderer } from './useMinimapRenderer'
 import { useMinimapSettings } from './useMinimapSettings'
 import { useMinimapViewport } from './useMinimapViewport'
 
-/** How often to poll for node drags/resizes, which emit no graph event. */
+/** How often to compare digests for state that emits no event; see the poll. */
 const CHANGE_DETECTION_INTERVAL_MS = 100
 
 export function useMinimap({
@@ -83,12 +82,18 @@ export function useMinimap({
   // a full layout-map rebuild, so every path that redraws checks this first.
   const canDraw = computed(() => visible.value && !!canvasRef.value)
 
-  // Graph event management
-  const graphManager = useMinimapGraph(graph, () => {
+  // Graph events are hints to compare the digests, not commands to repaint:
+  // graphChanged fires for plenty the minimap does not draw (zIndex from every
+  // widget pointerdown, widget values, title edits), and the digest is the one
+  // place that knows whether the picture moved.
+  const checkAndRepaint = () => {
     if (!canDraw.value) return
-    renderer.forceFullRedraw()
-    renderer.updateMinimap(viewport.updateBounds, viewport.updateViewport)
-  })
+    if (graphManager.checkForChanges()) {
+      renderer.updateMinimap(viewport.updateBounds, viewport.updateViewport)
+    }
+  }
+
+  const graphManager = useMinimapGraph(graph, () => checkAndRepaint())
 
   // Rendering
   const renderer = useMinimapRenderer(
@@ -102,43 +107,41 @@ export function useMinimap({
     height
   )
 
-  // Most edits already force a redraw through useMinimapGraph's event hooks,
-  // which cover node add/remove, connection changes and visual properties;
-  // moves and resizes reach layoutStore and could be observed the same way.
-  // This loop is the backstop for the writes that reach neither: snapPoint
-  // mutating `_pos` elements in place, extensions assigning `node.pos[0]`
-  // directly (only `size` is Proxy-wrapped against that), and `has_errors`,
-  // which has no event at all. Subscribing to layoutStore changes and letting
-  // the poll cover only that residue would allow a much longer period.
+  // Most edits reach the digest comparison through useMinimapGraph's event
+  // hooks. This loop is the backstop for state that emits no event at all:
+  // snapPoint mutating `_pos` elements in place, extensions assigning
+  // `node.pos[0]` directly (only `size` is Proxy-wrapped against that),
+  // `has_errors`, group drags, and execution-state transitions, which arrive
+  // in executionStore rather than as graph events. Repaints happen only when
+  // the digests move, so idle ticks cost one O(n) comparison and nothing else.
   const { pause: pauseChangeDetection, resume: resumeChangeDetection } =
-    useIntervalFn(
-      () => {
-        if (!canDraw.value) return
-        if (graphManager.checkForChanges()) {
-          renderer.updateMinimap(viewport.updateBounds, viewport.updateViewport)
-        }
-      },
-      CHANGE_DETECTION_INTERVAL_MS,
-      { immediate: false }
-    )
-
-  // rAF was suspended entirely on a hidden tab; setInterval is only clamped to
-  // roughly 1s, so without this a parked tab keeps digesting the whole graph.
+    useIntervalFn(checkAndRepaint, CHANGE_DETECTION_INTERVAL_MS, {
+      immediate: false
+    })
+
+  // Polling is derived state, not something init() decides once. init() runs
+  // synchronously from the immediate canvas watcher - before the template ref
+  // has mounted - so any start decision taken there sees canvasRef as null and
+  // the poll never starts. Deriving from the refs means the loop starts the
+  // moment the canvas mounts and stops the moment any condition lapses.
   //
-  // `immediate` matters: a tab opened in the background (middle-click, session
-  // restore) is already hidden at mount, so no visibilitychange ever fires and
-  // a transition-only watcher would never pause the loop it just started.
+  // Document visibility is part of the condition because rAF was suspended
+  // entirely on a hidden tab while setInterval is only clamped, and a tab that
+  // is hidden at mount (middle-click, session restore) never fires a
+  // visibilitychange to a transition-only watcher.
   const documentVisibility = useDocumentVisibility()
-  const documentHidden = computed(() => documentVisibility.value === 'hidden')
-
-  /** Both start paths consult this, so a hidden tab never starts polling. */
-  const shouldPoll = () => canDraw.value && !documentHidden.value
+  const shouldPoll = computed(
+    () =>
+      initialized.value &&
+      canDraw.value &&
+      documentVisibility.value !== 'hidden'
+  )
 
   watch(
-    documentHidden,
-    (hidden) => {
-      if (hidden) pauseChangeDetection()
-      else if (canDraw.value) resumeChangeDetection()
+    shouldPoll,
+    (active) => {
+      if (active) resumeChangeDetection()
+      else pauseChangeDetection()
     },
     { immediate: true }
   )
@@ -164,7 +167,6 @@ export function useMinimap({
       renderer.updateMinimap(viewport.updateBounds, viewport.updateViewport)
       viewport.updateViewport()
 
-      if (shouldPoll()) resumeChangeDetection()
       if (visible.value) viewport.startViewportSync()
       initialized.value = true
     }
@@ -226,28 +228,12 @@ export function useMinimap({
 
       renderer.updateMinimap(viewport.updateBounds, viewport.updateViewport)
       viewport.updateViewport()
-      if (shouldPoll()) resumeChangeDetection()
       viewport.startViewportSync()
     } else {
-      pauseChangeDetection()
       viewport.stopViewportSync()
     }
   })
 
-  const executionStore = useExecutionStore()
-  watch(
-    () => executionStore.nodeProgressStates,
-    () => {
-      // Fires per progress message during a run, so the canvas check matters
-      // here more than anywhere else.
-      if (canDraw.value) {
-        renderer.forceFullRedraw()
-        renderer.updateMinimap(viewport.updateBounds, viewport.updateViewport)
-      }
-    },
-    { deep: true }
-  )
-
   const toggle = async () => {
     visible.value = !visible.value
     await settingStore.set('Comfy.Minimap.Visible', visible.value)

src/renderer/extensions/minimap/composables/useMinimapGraph.test.ts

@@ -22,9 +22,13 @@ vi.mock('@vueuse/core', () => ({
   useThrottleFn: vi.fn((fn) => fn)
 }))
 
+const { mockProgressStates } = vi.hoisted(() => ({
+  mockProgressStates: {} as Record<string, { state: string }>
+}))
+
 vi.mock('@/stores/executionStore', () => ({
   useExecutionStore: vi.fn(() => ({
-    nodeProgressStates: {}
+    nodeProgressStates: mockProgressStates
   }))
 }))
 
@@ -54,6 +58,9 @@ describe('useMinimapGraph', () => {
     })
 
     onGraphChangedMock = vi.fn()
+    for (const key of Object.keys(mockProgressStates)) {
+      delete mockProgressStates[key]
+    }
   })
 
   it('should initialize with empty state', () => {
@@ -399,6 +406,64 @@ describe('useMinimapGraph', () => {
     expect(graphManager.checkForChanges()).toBe(false)
   })
 
+  it('should detect a background colour change', () => {
+    const graphRef = ref(mockGraph) as Ref<LGraph | null>
+    const graphManager = useMinimapGraph(graphRef, onGraphChangedMock)
+
+    graphManager.checkForChanges()
+    expect(graphManager.checkForChanges()).toBe(false)
+
+    mockGraph._nodes[0].bgcolor = '#ff0000'
+
+    expect(graphManager.checkForChanges()).toBe(true)
+  })
+
+  it('should detect a group move', () => {
+    mockGraph._groups = [
+      { pos: [0, 0], size: [400, 300], color: '#111111' }
+    ] as LGraph['_groups']
+
+    const graphRef = ref(mockGraph) as Ref<LGraph | null>
+    const graphManager = useMinimapGraph(graphRef, onGraphChangedMock)
+
+    graphManager.checkForChanges()
+    expect(graphManager.checkForChanges()).toBe(false)
+
+    mockGraph._groups[0].pos[0] = 250
+
+    expect(graphManager.checkForChanges()).toBe(true)
+  })
+
+  it('should detect an execution-state transition', () => {
+    const graphRef = ref(mockGraph) as Ref<LGraph | null>
+    const graphManager = useMinimapGraph(graphRef, onGraphChangedMock)
+
+    graphManager.checkForChanges()
+    expect(graphManager.checkForChanges()).toBe(false)
+
+    mockProgressStates['1'] = { state: 'running' }
+    expect(graphManager.checkForChanges()).toBe(true)
+    expect(graphManager.checkForChanges()).toBe(false)
+
+    mockProgressStates['1'] = { state: 'finished' }
+    expect(graphManager.checkForChanges()).toBe(true)
+  })
+
+  it('a visual-only change repaints without recomputing bounds', () => {
+    const graphRef = ref(mockGraph) as Ref<LGraph | null>
+    const graphManager = useMinimapGraph(graphRef, onGraphChangedMock)
+
+    graphManager.checkForChanges()
+    graphManager.updateFlags.value.bounds = false
+    graphManager.updateFlags.value.nodes = false
+
+    mockGraph._nodes[0].bgcolor = '#00ff00'
+    graphManager.checkForChanges()
+
+    expect(graphManager.updateFlags.value.nodes).toBe(true)
+    expect(graphManager.updateFlags.value.bounds).toBe(false)
+  })
+
   it('should detect an error-state change', () => {
     const graphRef = ref(mockGraph) as Ref<LGraph | null>
     const graphManager = useMinimapGraph(graphRef, onGraphChangedMock)