From 0646bb368a799394b44a186b86a516fdfc5380e8 Mon Sep 17 00:00:00 2001
From: Christian Byrne <cbyrne@comfy.org>
Date: Fri, 12 Dec 2025 14:41:13 -0800
Subject: [PATCH] perf: add gpu hint and transform settle to prevent
 rasterizing while zooming (scale transform) (#7417)

## Summary

Ensures the nodes get their own compositing layers during scale
transform (tracked via mouse wheel events), which prevents rasterization
during transform. Adds forced reflow at end of transform to ensure
layers are always at correct resolution (fixes blurriness and some
readability issues).

Videos show testing this branch first then testing main - doing layer
visualization, paint (include paint operations calculations and actual
raster) visualizations, and cpu usage monitoring.


https://github.com/user-attachments/assets/c5fab219-0b32-4822-9238-c4572f0d6a44



https://github.com/user-attachments/assets/7e172e8d-cc5b-4dcd-aa07-1dfc3eb65bac
---
 packages/design-system/src/css/style.css      |   9 +
 .../layout/__tests__/TransformPane.test.ts    |  71 +++++++-
 .../core/layout/transform/TransformPane.vue   |  21 ++-
 .../layout/transform/useTransformSettling.ts  |  84 +++++++++
 .../graph/useTransformSettling.test.ts        | 171 ++++++++++++++++++
 5 files changed, 354 insertions(+), 2 deletions(-)
 create mode 100644 src/renderer/core/layout/transform/useTransformSettling.ts
 create mode 100644 tests-ui/tests/composables/graph/useTransformSettling.test.ts

diff --git a/packages/design-system/src/css/style.css b/packages/design-system/src/css/style.css
index 1efc86194..1153d4543 100644
--- a/packages/design-system/src/css/style.css
+++ b/packages/design-system/src/css/style.css
@@ -1328,6 +1328,15 @@ audio.comfy-audio.empty-audio-widget {
     font-size 0.1s ease;
 }
 
+/* Performance optimization during canvas interaction */
+.transform-pane--interacting .lg-node * {
+  transition: none !important;
+}
+
+.transform-pane--interacting .lg-node {
+  will-change: transform;
+}
+
 /* ===================== Mask Editor Styles ===================== */
 /* To be migrated to Tailwind later */
   #maskEditor_brush {
diff --git a/src/renderer/core/layout/__tests__/TransformPane.test.ts b/src/renderer/core/layout/__tests__/TransformPane.test.ts
index 4876115b9..64952a629 100644
--- a/src/renderer/core/layout/__tests__/TransformPane.test.ts
+++ b/src/renderer/core/layout/__tests__/TransformPane.test.ts
@@ -117,6 +117,73 @@ describe('TransformPane', () => {
     })
   })
 
+  describe('canvas event listeners', () => {
+    it('should add event listeners to canvas on mount', async () => {
+      const mockCanvas = createMockCanvas()
+      mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      await nextTick()
+
+      expect(mockCanvas.canvas.addEventListener).toHaveBeenCalledWith(
+        'wheel',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.addEventListener).not.toHaveBeenCalledWith(
+        'pointerdown',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.addEventListener).not.toHaveBeenCalledWith(
+        'pointerup',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.addEventListener).not.toHaveBeenCalledWith(
+        'pointercancel',
+        expect.any(Function),
+        expect.any(Object)
+      )
+    })
+
+    it('should remove event listeners on unmount', async () => {
+      const mockCanvas = createMockCanvas()
+      const wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      await nextTick()
+      wrapper.unmount()
+
+      expect(mockCanvas.canvas.removeEventListener).toHaveBeenCalledWith(
+        'wheel',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.removeEventListener).not.toHaveBeenCalledWith(
+        'pointerdown',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.removeEventListener).not.toHaveBeenCalledWith(
+        'pointerup',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.removeEventListener).not.toHaveBeenCalledWith(
+        'pointercancel',
+        expect.any(Function),
+        expect.any(Object)
+      )
+    })
+  })
+
   describe('interaction state management', () => {
     it('should apply interacting class during interactions', async () => {
       const mockCanvas = createMockCanvas()
@@ -131,7 +198,9 @@ describe('TransformPane', () => {
       const transformPane = wrapper.find('[data-testid="transform-pane"]')
 
       // Initially should not have interacting class
-      expect(transformPane.classes()).not.toContain('will-change-transform')
+      expect(transformPane.classes()).not.toContain(
+        'transform-pane--interacting'
+      )
     })
 
     it('should handle pointer events for node delegation', async () => {
diff --git a/src/renderer/core/layout/transform/TransformPane.vue b/src/renderer/core/layout/transform/TransformPane.vue
index b39f67140..cf542bb89 100644
--- a/src/renderer/core/layout/transform/TransformPane.vue
+++ b/src/renderer/core/layout/transform/TransformPane.vue
@@ -1,7 +1,12 @@
 <template>
   <div
     data-testid="transform-pane"
-    class="absolute inset-0 w-full h-full pointer-events-none"
+    :class="
+      cn(
+        'absolute inset-0 w-full h-full pointer-events-none',
+        isInteracting ? 'transform-pane--interacting' : 'will-change-auto'
+      )
+    "
     :style="transformStyle"
   >
     <!-- Vue nodes will be rendered here -->
@@ -11,9 +16,12 @@
 
 <script setup lang="ts">
 import { useRafFn } from '@vueuse/core'
+import { computed } from 'vue'
 
 import type { LGraphCanvas } from '@/lib/litegraph/src/litegraph'
+import { useTransformSettling } from '@/renderer/core/layout/transform/useTransformSettling'
 import { useTransformState } from '@/renderer/core/layout/transform/useTransformState'
+import { cn } from '@/utils/tailwindUtil'
 
 interface TransformPaneProps {
   canvas?: LGraphCanvas
@@ -23,6 +31,11 @@ const props = defineProps<TransformPaneProps>()
 
 const { transformStyle, syncWithCanvas } = useTransformState()
 
+const canvasElement = computed(() => props.canvas?.canvas)
+const { isTransforming: isInteracting } = useTransformSettling(canvasElement, {
+  settleDelay: 16
+})
+
 useRafFn(
   () => {
     if (!props.canvas) {
@@ -33,3 +46,9 @@ useRafFn(
   { immediate: true }
 )
 </script>
+
+<style scoped>
+.transform-pane--interacting {
+  will-change: transform;
+}
+</style>
diff --git a/src/renderer/core/layout/transform/useTransformSettling.ts b/src/renderer/core/layout/transform/useTransformSettling.ts
new file mode 100644
index 000000000..a336eef7e
--- /dev/null
+++ b/src/renderer/core/layout/transform/useTransformSettling.ts
@@ -0,0 +1,84 @@
+import { useDebounceFn, useEventListener } from '@vueuse/core'
+import { ref } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
+
+interface TransformSettlingOptions {
+  /**
+   * Delay in ms before transform is considered "settled" after last interaction
+   * @default 200
+   */
+  settleDelay?: number
+  /**
+   * Whether to use passive event listeners (better performance but can't preventDefault)
+   * @default true
+   */
+  passive?: boolean
+}
+
+/**
+ * Tracks when canvas zoom transforms are actively changing vs settled.
+ *
+ * This composable helps optimize rendering quality during zoom transformations.
+ * When the user is actively zooming, we can reduce rendering quality
+ * for better performance. Once the transform "settles" (stops changing), we can
+ * trigger high-quality re-rasterization.
+ *
+ * The settling concept prevents constant quality switching during interactions
+ * by waiting for a period of inactivity before considering the transform complete.
+ *
+ * Uses VueUse's useEventListener for automatic cleanup and useDebounceFn for
+ * efficient settle detection.
+ *
+ * @example
+ * ```ts
+ * const { isTransforming } = useTransformSettling(canvasRef, {
+ *   settleDelay: 200
+ * })
+ *
+ * // Use in CSS classes or rendering logic
+ * const cssClass = computed(() => ({
+ *   'low-quality': isTransforming.value,
+ *   'high-quality': !isTransforming.value
+ * }))
+ * ```
+ */
+export function useTransformSettling(
+  target: MaybeRefOrGetter<HTMLElement | null | undefined>,
+  options: TransformSettlingOptions = {}
+) {
+  const { settleDelay = 256, passive = true } = options
+
+  const isTransforming = ref(false)
+
+  /**
+   * Mark transform as active
+   */
+  const markTransformActive = () => {
+    isTransforming.value = true
+  }
+
+  /**
+   * Mark transform as settled (debounced)
+   */
+  const markTransformSettled = useDebounceFn(() => {
+    isTransforming.value = false
+  }, settleDelay)
+
+  /**
+   * Handle zoom transform event - mark active then queue settle
+   */
+  const handleWheel = () => {
+    markTransformActive()
+    void markTransformSettled()
+  }
+
+  // Register wheel event listener with auto-cleanup
+  useEventListener(target, 'wheel', handleWheel, {
+    capture: true,
+    passive
+  })
+
+  return {
+    isTransforming
+  }
+}
diff --git a/tests-ui/tests/composables/graph/useTransformSettling.test.ts b/tests-ui/tests/composables/graph/useTransformSettling.test.ts
new file mode 100644
index 000000000..bbd4002cd
--- /dev/null
+++ b/tests-ui/tests/composables/graph/useTransformSettling.test.ts
@@ -0,0 +1,171 @@
+import { mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+
+import { useTransformSettling } from '@/renderer/core/layout/transform/useTransformSettling'
+
+describe('useTransformSettling', () => {
+  let element: HTMLDivElement
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    element = document.createElement('div')
+    document.body.appendChild(element)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    document.body.removeChild(element)
+  })
+
+  it('should track wheel events and settle after delay', async () => {
+    const { isTransforming } = useTransformSettling(element, {
+      settleDelay: 200
+    })
+
+    // Initially not transforming
+    expect(isTransforming.value).toBe(false)
+
+    // Dispatch wheel event
+    element.dispatchEvent(new WheelEvent('wheel', { bubbles: true }))
+    await nextTick()
+
+    // Should be transforming
+    expect(isTransforming.value).toBe(true)
+
+    // Advance time but not past settle delay
+    vi.advanceTimersByTime(100)
+    expect(isTransforming.value).toBe(true)
+
+    // Advance past settle delay
+    vi.advanceTimersByTime(150)
+    expect(isTransforming.value).toBe(false)
+  })
+
+  it('should reset settle timer on subsequent wheel events', async () => {
+    const { isTransforming } = useTransformSettling(element, {
+      settleDelay: 300
+    })
+
+    // First wheel event
+    element.dispatchEvent(new WheelEvent('wheel', { bubbles: true }))
+    await nextTick()
+    expect(isTransforming.value).toBe(true)
+
+    // Advance time partially
+    vi.advanceTimersByTime(200)
+    expect(isTransforming.value).toBe(true)
+
+    // Another wheel event should reset the timer
+    element.dispatchEvent(new WheelEvent('wheel', { bubbles: true }))
+    await nextTick()
+
+    // Advance 200ms more - should still be transforming
+    vi.advanceTimersByTime(200)
+    expect(isTransforming.value).toBe(true)
+
+    // Need another 100ms to settle (300ms total from last event)
+    vi.advanceTimersByTime(100)
+    expect(isTransforming.value).toBe(false)
+  })
+
+  it('should not track pan events', async () => {
+    const { isTransforming } = useTransformSettling(element)
+
+    // Pointer events should not trigger transform
+    element.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+    element.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }))
+    await nextTick()
+
+    expect(isTransforming.value).toBe(false)
+  })
+
+  it('should work with ref target', async () => {
+    const targetRef = ref<HTMLElement | null>(null)
+    const { isTransforming } = useTransformSettling(targetRef, {
+      settleDelay: 200
+    })
+
+    // No target yet
+    expect(isTransforming.value).toBe(false)
+
+    // Set target
+    targetRef.value = element
+    await nextTick()
+
+    // Now events should work
+    element.dispatchEvent(new WheelEvent('wheel', { bubbles: true }))
+    await nextTick()
+    expect(isTransforming.value).toBe(true)
+
+    vi.advanceTimersByTime(200)
+    expect(isTransforming.value).toBe(false)
+  })
+
+  it('should use capture phase for events', async () => {
+    const captureHandler = vi.fn()
+    const bubbleHandler = vi.fn()
+
+    // Add handlers to verify capture phase
+    element.addEventListener('wheel', captureHandler, true)
+    element.addEventListener('wheel', bubbleHandler, false)
+
+    const { isTransforming } = useTransformSettling(element)
+
+    // Create child element
+    const child = document.createElement('div')
+    element.appendChild(child)
+
+    // Dispatch event on child
+    child.dispatchEvent(new WheelEvent('wheel', { bubbles: true }))
+    await nextTick()
+
+    // Capture handler should be called before bubble handler
+    expect(captureHandler).toHaveBeenCalled()
+    expect(isTransforming.value).toBe(true)
+
+    element.removeEventListener('wheel', captureHandler, true)
+    element.removeEventListener('wheel', bubbleHandler, false)
+  })
+
+  it('should clean up event listeners when component unmounts', async () => {
+    const removeEventListenerSpy = vi.spyOn(element, 'removeEventListener')
+
+    // Create a test component
+    const TestComponent = {
+      setup() {
+        const { isTransforming } = useTransformSettling(element)
+        return { isTransforming }
+      },
+      template: '<div>{{ isTransforming }}</div>'
+    }
+
+    const wrapper = mount(TestComponent)
+    await nextTick()
+
+    // Unmount component
+    wrapper.unmount()
+
+    // Should have removed wheel event listener
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      'wheel',
+      expect.any(Function),
+      expect.objectContaining({ capture: true })
+    )
+  })
+
+  it('should use passive listeners when specified', async () => {
+    const addEventListenerSpy = vi.spyOn(element, 'addEventListener')
+
+    useTransformSettling(element, {
+      passive: true
+    })
+
+    // Check that passive option was used for wheel event
+    expect(addEventListenerSpy).toHaveBeenCalledWith(
+      'wheel',
+      expect.any(Function),
+      expect.objectContaining({ passive: true, capture: true })
+    )
+  })
+})