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

@@ -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 {

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 () => {

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>

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
+  }
+}

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 })
+    )
+  })
+})