[perf] Add global CSS optimizations for LOD system

Remove expensive paint effects (shadows, filters, backdrop-filters) at lower LOD levels
Simplify rendering for minimal LOD (no border-radius, no background images)
These optimizations reduce paint complexity without causing unwanted layerization

src/assets/css/style.css

@@ -5,6 +5,7 @@
   @tailwind utilities;
 }
 
+
 :root {
   --fg-color: #000;
   --bg-color: #fff;
@@ -637,3 +638,92 @@ audio.comfy-audio.empty-audio-widget {
   width: calc(100vw - env(titlebar-area-width, 100vw));
 }
 /* End of [Desktop] Electron window specific styles */
+
+/* Vue Node LOD (Level of Detail) System */
+/* These classes control rendering detail based on zoom level */
+
+/* Minimal LOD (zoom <= 0.4) - Title only for performance */
+.lg-node--lod-minimal {
+  min-height: 32px;
+  transition: min-height 0.2s ease;
+  /* Performance optimizations */
+  text-shadow: none;
+  backdrop-filter: none;
+}
+
+.lg-node--lod-minimal .lg-node-body {
+  display: none !important;
+}
+
+/* Reduced LOD (0.4 < zoom <= 0.8) - Essential widgets, simplified styling */
+.lg-node--lod-reduced {
+  transition: opacity 0.1s ease;
+  /* Performance optimizations */
+  text-shadow: none;
+}
+
+.lg-node--lod-reduced .lg-widget-label,
+.lg-node--lod-reduced .lg-slot-label {
+  display: none;
+}
+
+.lg-node--lod-reduced .lg-slot {
+  opacity: 0.6;
+  font-size: 0.75rem;
+}
+
+.lg-node--lod-reduced .lg-widget {
+  margin: 2px 0;
+  font-size: 0.875rem;
+}
+
+/* Full LOD (zoom > 0.8) - Complete detail rendering */
+.lg-node--lod-full {
+  /* Uses default styling - no overrides needed */
+}
+
+/* Smooth transitions between LOD levels */
+.lg-node {
+  transition: min-height 0.2s ease;
+  /* Disable text selection on all nodes */
+  user-select: none;
+  -webkit-user-select: none;
+  -moz-user-select: none;
+  -ms-user-select: none;
+}
+
+.lg-node .lg-slot,
+.lg-node .lg-widget {
+  transition: opacity 0.1s ease, 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;
+}
+
+/* Global performance optimizations for LOD */
+.lg-node--lod-minimal,
+.lg-node--lod-reduced {
+  /* Remove ALL expensive paint effects */
+  box-shadow: none !important;
+  filter: none !important;
+  backdrop-filter: none !important;
+  text-shadow: none !important;
+  -webkit-mask-image: none !important;
+  mask-image: none !important;
+  clip-path: none !important;
+}
+
+/* Reduce paint complexity for minimal LOD */
+.lg-node--lod-minimal {
+  /* Skip complex borders */
+  border-radius: 0 !important;
+  /* Use solid colors only */
+  background-image: none !important;
+}
+

src/components/graph/GraphCanvas.vue

@@ -29,6 +29,52 @@
     class="w-full h-full touch-none"
   />
 
+  <!-- TransformPane for Vue node rendering (development) -->
+  <TransformPane
+    v-if="transformPaneEnabled && canvasStore.canvas && comfyAppReady"
+    :canvas="canvasStore.canvas as LGraphCanvas"
+    :viewport="canvasViewport"
+    :show-debug-overlay="showPerformanceOverlay"
+    @raf-status-change="rafActive = $event"
+    @transform-update="handleTransformUpdate"
+  >
+    <!-- Vue nodes rendered based on graph nodes -->
+    <VueGraphNode
+      v-for="nodeData in nodesToRender"
+      :key="nodeData.id"
+      :node-data="nodeData"
+      :position="nodePositions.get(nodeData.id)"
+      :size="nodeSizes.get(nodeData.id)"
+      :selected="nodeData.selected"
+      :readonly="false"
+      :executing="executionStore.executingNodeId === nodeData.id"
+      :error="
+        executionStore.lastExecutionError?.node_id === nodeData.id
+          ? 'Execution error'
+          : null
+      "
+      :zoom-level="canvasStore.canvas?.ds?.scale || 1"
+      :data-node-id="nodeData.id"
+      @node-click="handleNodeSelect"
+    />
+  </TransformPane>
+
+  <!-- Debug Panel (Development Only) -->
+  <VueNodeDebugPanel
+    v-model:debug-override-vue-nodes="debugOverrideVueNodes"
+    v-model:show-performance-overlay="showPerformanceOverlay"
+    :canvas-viewport="canvasViewport"
+    :vue-nodes-count="vueNodesCount"
+    :nodes-in-viewport="nodesInViewport"
+    :performance-metrics="performanceMetrics"
+    :current-f-p-s="currentFPS"
+    :last-transform-time="lastTransformTime"
+    :raf-active="rafActive"
+    :is-dev-mode-enabled="isDevModeEnabled"
+    :should-render-vue-nodes="shouldRenderVueNodes"
+    :transform-pane-enabled="transformPaneEnabled"
+  />
+
   <NodeTooltip v-if="tooltipEnabled" />
   <NodeSearchboxPopover />
 
@@ -44,9 +90,18 @@
 </template>
 
 <script setup lang="ts">
-import type { LGraphNode } from '@comfyorg/litegraph'
+import type { LGraphCanvas, LGraphNode } from '@comfyorg/litegraph'
 import { useEventListener, whenever } from '@vueuse/core'
-import { computed, onMounted, ref, watch, watchEffect } from 'vue'
+import {
+  computed,
+  onMounted,
+  onUnmounted,
+  reactive,
+  ref,
+  shallowRef,
+  watch,
+  watchEffect
+} from 'vue'
 
 import LiteGraphCanvasSplitterOverlay from '@/components/LiteGraphCanvasSplitterOverlay.vue'
 import BottomPanel from '@/components/bottomPanel/BottomPanel.vue'
@@ -57,14 +112,24 @@ import NodeTooltip from '@/components/graph/NodeTooltip.vue'
 import SelectionOverlay from '@/components/graph/SelectionOverlay.vue'
 import SelectionToolbox from '@/components/graph/SelectionToolbox.vue'
 import TitleEditor from '@/components/graph/TitleEditor.vue'
+import TransformPane from '@/components/graph/TransformPane.vue'
+import VueNodeDebugPanel from '@/components/graph/debug/VueNodeDebugPanel.vue'
+import VueGraphNode from '@/components/graph/vueNodes/LGraphNode.vue'
 import NodeSearchboxPopover from '@/components/searchbox/NodeSearchBoxPopover.vue'
 import SideToolbar from '@/components/sidebar/SideToolbar.vue'
 import SecondRowWorkflowTabs from '@/components/topbar/SecondRowWorkflowTabs.vue'
+import { useTransformState } from '@/composables/element/useTransformState'
 import { useChainCallback } from '@/composables/functional/useChainCallback'
+import { useGraphNodeManager } from '@/composables/graph/useGraphNodeManager'
+import type {
+  NodeState,
+  VueNodeData
+} from '@/composables/graph/useGraphNodeManager'
 import { useNodeBadge } from '@/composables/node/useNodeBadge'
 import { useCanvasDrop } from '@/composables/useCanvasDrop'
 import { useContextMenuTranslation } from '@/composables/useContextMenuTranslation'
 import { useCopy } from '@/composables/useCopy'
+import { useFeatureFlags } from '@/composables/useFeatureFlags'
 import { useGlobalLitegraph } from '@/composables/useGlobalLitegraph'
 import { useLitegraphSettings } from '@/composables/useLitegraphSettings'
 import { usePaste } from '@/composables/usePaste'
@@ -113,6 +178,286 @@ const selectionToolboxEnabled = computed(() =>
   settingStore.get('Comfy.Canvas.SelectionToolbox')
 )
 
+// Feature flags
+const { shouldRenderVueNodes, isDevModeEnabled } = useFeatureFlags()
+
+// TransformPane enabled when Vue nodes are enabled OR debug override
+const debugOverrideVueNodes = ref(true) // Default to true for development
+const transformPaneEnabled = computed(
+  () => shouldRenderVueNodes.value || debugOverrideVueNodes.value
+)
+// Account for browser zoom/DPI scaling
+const getActualViewport = () => {
+  // Get the actual canvas element dimensions which account for zoom
+  const canvas = canvasRef.value
+  if (canvas) {
+    return {
+      width: canvas.clientWidth,
+      height: canvas.clientHeight
+    }
+  }
+  // Fallback to window dimensions
+  return {
+    width: window.innerWidth,
+    height: window.innerHeight
+  }
+}
+
+const canvasViewport = ref(getActualViewport())
+
+// Debug metrics - use shallowRef for frequently updating values
+const vueNodesCount = shallowRef(0)
+const nodesInViewport = shallowRef(0)
+const currentFPS = shallowRef(0)
+const lastTransformTime = shallowRef(0)
+const rafActive = shallowRef(false)
+
+// Rendering options
+const showPerformanceOverlay = ref(false)
+
+// FPS tracking
+let lastTime = performance.now()
+let frameCount = 0
+let fpsRafId: number | null = null
+
+const updateFPS = () => {
+  frameCount++
+  const currentTime = performance.now()
+  if (currentTime >= lastTime + 1000) {
+    currentFPS.value = Math.round(
+      (frameCount * 1000) / (currentTime - lastTime)
+    )
+    frameCount = 0
+    lastTime = currentTime
+  }
+  if (transformPaneEnabled.value) {
+    fpsRafId = requestAnimationFrame(updateFPS)
+  }
+}
+
+// Start FPS tracking when TransformPane is enabled
+watch(transformPaneEnabled, (enabled) => {
+  if (enabled) {
+    fpsRafId = requestAnimationFrame(updateFPS)
+  } else {
+    // Stop FPS tracking
+    if (fpsRafId !== null) {
+      cancelAnimationFrame(fpsRafId)
+      fpsRafId = null
+    }
+  }
+})
+
+// Update viewport on resize
+useEventListener(window, 'resize', () => {
+  canvasViewport.value = getActualViewport()
+})
+
+// Also update when canvas is ready
+watch(canvasRef, () => {
+  if (canvasRef.value) {
+    canvasViewport.value = getActualViewport()
+  }
+})
+
+// Vue node lifecycle management - initialize after graph is ready
+let nodeManager: ReturnType<typeof useGraphNodeManager> | null = null
+const vueNodeData = ref<ReadonlyMap<string, VueNodeData>>(new Map())
+const nodeState = ref<ReadonlyMap<string, NodeState>>(new Map())
+const nodePositions = ref<ReadonlyMap<string, { x: number; y: number }>>(
+  new Map()
+)
+const nodeSizes = ref<ReadonlyMap<string, { width: number; height: number }>>(
+  new Map()
+)
+let detectChangesInRAF = () => {}
+const performanceMetrics = reactive({
+  frameTime: 0,
+  updateTime: 0,
+  nodeCount: 0,
+  culledCount: 0,
+  adaptiveQuality: false
+})
+
+// Initialize node manager when graph becomes available
+// Add a reactivity trigger to force computed re-evaluation
+const nodeDataTrigger = ref(0)
+
+const initializeNodeManager = () => {
+  if (!comfyApp.graph || nodeManager) {
+    return
+  }
+
+  nodeManager = useGraphNodeManager(comfyApp.graph)
+
+  // Use the manager's reactive maps directly
+  vueNodeData.value = nodeManager.vueNodeData
+  nodeState.value = nodeManager.nodeState
+  nodePositions.value = nodeManager.nodePositions
+  nodeSizes.value = nodeManager.nodeSizes
+
+  detectChangesInRAF = nodeManager.detectChangesInRAF
+  Object.assign(performanceMetrics, nodeManager.performanceMetrics)
+
+  // Force computed properties to re-evaluate
+  nodeDataTrigger.value++
+}
+
+// Watch for graph availability
+watch(
+  () => comfyApp.graph,
+  (graph) => {
+    if (graph) {
+      initializeNodeManager()
+    }
+  },
+  { immediate: true }
+)
+
+// Transform state for viewport culling
+const { syncWithCanvas } = useTransformState()
+
+// Replace problematic computed property with proper reactive system
+const nodesToRender = computed(() => {
+  // Access performanceMetrics to trigger on RAF updates
+  void performanceMetrics.updateTime
+  // Access trigger to force re-evaluation after nodeManager initialization
+  void nodeDataTrigger.value
+
+  if (!comfyApp.graph || !transformPaneEnabled.value) {
+    return []
+  }
+
+  const allNodes = Array.from(vueNodeData.value.values())
+
+  // Apply viewport culling - check if node bounds intersect with viewport
+  if (nodeManager && canvasStore.canvas && comfyApp.canvas) {
+    const canvas = canvasStore.canvas
+    const manager = nodeManager
+
+    // Ensure transform is synced before checking visibility
+    syncWithCanvas(comfyApp.canvas)
+
+    const ds = canvas.ds
+
+    // Access transform time to make this reactive to transform changes
+    void lastTransformTime.value
+
+    // Work in screen space - viewport is simply the canvas element size
+    const viewport_width = canvas.canvas.width
+    const viewport_height = canvas.canvas.height
+
+    // Add margin that represents a constant distance in canvas space
+    // Convert canvas units to screen pixels by multiplying by scale
+    const canvasMarginDistance = 200 // Fixed margin in canvas units
+    const margin_x = canvasMarginDistance * ds.scale
+    const margin_y = canvasMarginDistance * ds.scale
+
+    const filtered = allNodes.filter((nodeData) => {
+      const node = manager.getNode(nodeData.id)
+      if (!node) return false
+
+      // Transform node position to screen space (same as DOM widgets)
+      const screen_x = (node.pos[0] + ds.offset[0]) * ds.scale
+      const screen_y = (node.pos[1] + ds.offset[1]) * ds.scale
+      const screen_width = node.size[0] * ds.scale
+      const screen_height = node.size[1] * ds.scale
+
+      // Check if node bounds intersect with expanded viewport (in screen space)
+      const isVisible = !(
+        screen_x + screen_width < -margin_x ||
+        screen_x > viewport_width + margin_x ||
+        screen_y + screen_height < -margin_y ||
+        screen_y > viewport_height + margin_y
+      )
+
+      return isVisible
+    })
+
+    return filtered
+  }
+
+  return allNodes
+})
+
+// Remove side effects from computed - use watchers instead
+watch(
+  () => vueNodeData.value.size,
+  (count) => {
+    vueNodesCount.value = count
+  },
+  { immediate: true }
+)
+
+watch(
+  () => nodesToRender.value.length,
+  (count) => {
+    nodesInViewport.value = count
+  }
+)
+
+// Update performance metrics when node counts change
+watch(
+  () => [vueNodeData.value.size, nodesToRender.value.length],
+  ([totalNodes, visibleNodes]) => {
+    performanceMetrics.nodeCount = totalNodes
+    performanceMetrics.culledCount = totalNodes - visibleNodes
+  }
+)
+
+// Integrate change detection with TransformPane RAF
+// Track previous transform to detect changes
+let lastScale = 1
+let lastOffsetX = 0
+let lastOffsetY = 0
+
+const handleTransformUpdate = (time: number) => {
+  lastTransformTime.value = time
+
+  // Sync transform state only when it changes (avoids reflows)
+  if (comfyApp.canvas?.ds) {
+    const currentScale = comfyApp.canvas.ds.scale
+    const currentOffsetX = comfyApp.canvas.ds.offset[0]
+    const currentOffsetY = comfyApp.canvas.ds.offset[1]
+
+    if (
+      currentScale !== lastScale ||
+      currentOffsetX !== lastOffsetX ||
+      currentOffsetY !== lastOffsetY
+    ) {
+      syncWithCanvas(comfyApp.canvas)
+      lastScale = currentScale
+      lastOffsetX = currentOffsetX
+      lastOffsetY = currentOffsetY
+    }
+  }
+
+  // Detect node changes during transform updates
+  detectChangesInRAF()
+
+  // Update performance metrics
+  performanceMetrics.frameTime = time
+
+  void nodesToRender.value.length
+}
+
+// Node event handlers
+const handleNodeSelect = (event: PointerEvent, nodeData: VueNodeData) => {
+  if (!canvasStore.canvas || !nodeManager) return
+
+  const node = nodeManager.getNode(nodeData.id)
+  if (!node) return
+
+  if (!event.ctrlKey && !event.metaKey) {
+    canvasStore.canvas.deselectAllNodes()
+  }
+
+  canvasStore.canvas.selectNode(node)
+  node.selected = true
+
+  canvasStore.updateSelectedItems()
+}
+
 watchEffect(() => {
   nodeDefStore.showDeprecated = settingStore.get('Comfy.Node.ShowDeprecated')
 })
@@ -260,7 +605,7 @@ const loadCustomNodesI18n = async () => {
       i18n.global.mergeLocaleMessage(locale, message)
     })
   } catch (error) {
-    console.error('Failed to load custom nodes i18n', error)
+    // Ignore i18n loading errors - not critical
   }
 }
 
@@ -289,9 +634,6 @@ onMounted(async () => {
     await settingStore.loadSettingValues()
   } catch (error) {
     if (error instanceof UnauthorizedError) {
-      console.log(
-        'Failed loading user settings, user unauthorized, cleaning local Comfy.userId'
-      )
       localStorage.removeItem('Comfy.userId')
       localStorage.removeItem('Comfy.userName')
       window.location.reload()
@@ -313,6 +655,11 @@ onMounted(async () => {
 
   comfyAppReady.value = true
 
+  // Initialize node manager after setup is complete
+  if (comfyApp.graph) {
+    initializeNodeManager()
+  }
+
   comfyApp.canvas.onSelectionChange = useChainCallback(
     comfyApp.canvas.onSelectionChange,
     () => canvasStore.updateSelectedItems()
@@ -353,4 +700,18 @@ onMounted(async () => {
 
   emit('ready')
 })
+
+onUnmounted(() => {
+  // Clean up FPS tracking
+  if (fpsRafId !== null) {
+    cancelAnimationFrame(fpsRafId)
+    fpsRafId = null
+  }
+
+  // Clean up node manager
+  if (nodeManager) {
+    nodeManager.cleanup()
+    nodeManager = null
+  }
+})
 </script>

src/components/graph/TransformPane.spec.ts

@@ -0,0 +1,438 @@
+import { mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+
+import TransformPane from './TransformPane.vue'
+
+// Mock the transform state composable
+const mockTransformState = {
+  camera: ref({ x: 0, y: 0, z: 1 }),
+  transformStyle: ref({
+    transform: 'scale(1) translate(0px, 0px)',
+    transformOrigin: '0 0'
+  }),
+  syncWithCanvas: vi.fn(),
+  canvasToScreen: vi.fn(),
+  screenToCanvas: vi.fn(),
+  isNodeInViewport: vi.fn()
+}
+
+vi.mock('@/composables/element/useTransformState', () => ({
+  useTransformState: () => mockTransformState
+}))
+
+// Mock requestAnimationFrame/cancelAnimationFrame
+global.requestAnimationFrame = vi.fn((cb) => {
+  setTimeout(cb, 16)
+  return 1
+})
+global.cancelAnimationFrame = vi.fn()
+
+describe('TransformPane', () => {
+  let wrapper: ReturnType<typeof mount>
+  let mockCanvas: any
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    // Create mock canvas with LiteGraph interface
+    mockCanvas = {
+      canvas: {
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn()
+      },
+      ds: {
+        offset: [0, 0],
+        scale: 1
+      }
+    }
+
+    // Reset mock transform state
+    mockTransformState.camera.value = { x: 0, y: 0, z: 1 }
+    mockTransformState.transformStyle.value = {
+      transform: 'scale(1) translate(0px, 0px)',
+      transformOrigin: '0 0'
+    }
+  })
+
+  afterEach(() => {
+    if (wrapper) {
+      wrapper.unmount()
+    }
+  })
+
+  describe('component mounting', () => {
+    it('should mount successfully with minimal props', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      expect(wrapper.exists()).toBe(true)
+      expect(wrapper.find('.transform-pane').exists()).toBe(true)
+    })
+
+    it('should apply transform style from composable', () => {
+      mockTransformState.transformStyle.value = {
+        transform: 'scale(2) translate(100px, 50px)',
+        transformOrigin: '0 0'
+      }
+
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      const transformPane = wrapper.find('.transform-pane')
+      const style = transformPane.attributes('style')
+      expect(style).toContain('transform: scale(2) translate(100px, 50px)')
+    })
+
+    it('should render slot content', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        },
+        slots: {
+          default: '<div class="test-content">Test Node</div>'
+        }
+      })
+
+      expect(wrapper.find('.test-content').exists()).toBe(true)
+      expect(wrapper.find('.test-content').text()).toBe('Test Node')
+    })
+  })
+
+  describe('debug overlay', () => {
+    it('should not show debug overlay by default', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      expect(wrapper.find('.viewport-debug-overlay').exists()).toBe(false)
+    })
+
+    it('should show debug overlay when enabled', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas,
+          viewport: { width: 1920, height: 1080 },
+          showDebugOverlay: true
+        }
+      })
+
+      expect(wrapper.find('.viewport-debug-overlay').exists()).toBe(true)
+    })
+
+    it('should display viewport dimensions in debug overlay', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas,
+          viewport: { width: 1280, height: 720 },
+          showDebugOverlay: true
+        }
+      })
+
+      const debugOverlay = wrapper.find('.viewport-debug-overlay')
+      expect(debugOverlay.text()).toContain('Viewport: 1280x720')
+    })
+
+    it('should include device pixel ratio in debug overlay', () => {
+      // Mock device pixel ratio
+      Object.defineProperty(window, 'devicePixelRatio', {
+        writable: true,
+        value: 2
+      })
+
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas,
+          viewport: { width: 1920, height: 1080 },
+          showDebugOverlay: true
+        }
+      })
+
+      const debugOverlay = wrapper.find('.viewport-debug-overlay')
+      expect(debugOverlay.text()).toContain('DPR: 2')
+    })
+  })
+
+  describe('RAF synchronization', () => {
+    it('should start RAF sync on mount', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      await nextTick()
+
+      // Should emit RAF status change to true
+      expect(wrapper.emitted('rafStatusChange')).toBeTruthy()
+      expect(wrapper.emitted('rafStatusChange')?.[0]).toEqual([true])
+    })
+
+    it('should call syncWithCanvas during RAF updates', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      await nextTick()
+
+      // Allow RAF to execute
+      await new Promise((resolve) => setTimeout(resolve, 20))
+
+      expect(mockTransformState.syncWithCanvas).toHaveBeenCalledWith(mockCanvas)
+    })
+
+    it('should emit transform update timing', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      await nextTick()
+
+      // Allow RAF to execute
+      await new Promise((resolve) => setTimeout(resolve, 20))
+
+      expect(wrapper.emitted('transformUpdate')).toBeTruthy()
+      const updateEvent = wrapper.emitted('transformUpdate')?.[0]
+      expect(typeof updateEvent?.[0]).toBe('number')
+      expect(updateEvent?.[0]).toBeGreaterThanOrEqual(0)
+    })
+
+    it('should stop RAF sync on unmount', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      await nextTick()
+      wrapper.unmount()
+
+      expect(wrapper.emitted('rafStatusChange')).toBeTruthy()
+      const events = wrapper.emitted('rafStatusChange') as any[]
+      expect(events[events.length - 1]).toEqual([false])
+      expect(global.cancelAnimationFrame).toHaveBeenCalled()
+    })
+  })
+
+  describe('canvas event listeners', () => {
+    it('should add event listeners to canvas on mount', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      await nextTick()
+
+      expect(mockCanvas.canvas.addEventListener).toHaveBeenCalledWith(
+        'wheel',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.addEventListener).toHaveBeenCalledWith(
+        'pointerdown',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.addEventListener).toHaveBeenCalledWith(
+        'pointerup',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.addEventListener).toHaveBeenCalledWith(
+        'pointercancel',
+        expect.any(Function),
+        expect.any(Object)
+      )
+    })
+
+    it('should remove event listeners on unmount', async () => {
+      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).toHaveBeenCalledWith(
+        'pointerdown',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.removeEventListener).toHaveBeenCalledWith(
+        'pointerup',
+        expect.any(Function),
+        expect.any(Object)
+      )
+      expect(mockCanvas.canvas.removeEventListener).toHaveBeenCalledWith(
+        'pointercancel',
+        expect.any(Function),
+        expect.any(Object)
+      )
+    })
+  })
+
+  describe('interaction state management', () => {
+    it('should apply interacting class during interactions', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      // Simulate interaction start by checking internal state
+      // Note: This tests the CSS class application logic
+      const transformPane = wrapper.find('.transform-pane')
+
+      // Initially should not have interacting class
+      expect(transformPane.classes()).not.toContain(
+        'transform-pane--interacting'
+      )
+    })
+
+    it('should handle pointer events for node delegation', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      const transformPane = wrapper.find('.transform-pane')
+
+      // Simulate pointer down - we can't test the exact delegation logic
+      // in unit tests due to vue-test-utils limitations, but we can verify
+      // the event handler is set up correctly
+      await transformPane.trigger('pointerdown')
+
+      // The test passes if no errors are thrown during event handling
+      expect(transformPane.exists()).toBe(true)
+    })
+  })
+
+  describe('transform state integration', () => {
+    it('should provide transform utilities to child components', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      // The component should provide transform state via Vue's provide/inject
+      // This is tested indirectly through the composable integration
+      expect(mockTransformState.syncWithCanvas).toBeDefined()
+      expect(mockTransformState.canvasToScreen).toBeDefined()
+      expect(mockTransformState.screenToCanvas).toBeDefined()
+    })
+  })
+
+  describe('error handling', () => {
+    it('should handle null canvas gracefully', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: undefined
+        }
+      })
+
+      expect(wrapper.exists()).toBe(true)
+      expect(wrapper.find('.transform-pane').exists()).toBe(true)
+    })
+
+    it('should handle missing canvas properties', () => {
+      const incompleteCanvas = {} as any
+
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: incompleteCanvas
+        }
+      })
+
+      expect(wrapper.exists()).toBe(true)
+      // Should not throw errors during mount
+    })
+  })
+
+  describe('performance optimizations', () => {
+    it('should use contain CSS property for layout optimization', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        }
+      })
+
+      const transformPane = wrapper.find('.transform-pane')
+
+      // This test verifies the CSS contains the performance optimization
+      // Note: In JSDOM, computed styles might not reflect all CSS properties
+      expect(transformPane.element.className).toContain('transform-pane')
+    })
+
+    it('should disable pointer events on container but allow on children', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas
+        },
+        slots: {
+          default: '<div data-node-id="test">Test Node</div>'
+        }
+      })
+
+      const transformPane = wrapper.find('.transform-pane')
+
+      // The CSS should handle pointer events optimization
+      // This is primarily a CSS concern, but we verify the structure
+      expect(transformPane.exists()).toBe(true)
+      expect(wrapper.find('[data-node-id="test"]').exists()).toBe(true)
+    })
+  })
+
+  describe('viewport prop handling', () => {
+    it('should handle missing viewport prop', () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas,
+          showDebugOverlay: true
+        }
+      })
+
+      // Should not crash when viewport is undefined
+      expect(wrapper.exists()).toBe(true)
+    })
+
+    it('should update debug overlay when viewport changes', async () => {
+      wrapper = mount(TransformPane, {
+        props: {
+          canvas: mockCanvas,
+          viewport: { width: 800, height: 600 },
+          showDebugOverlay: true
+        }
+      })
+
+      expect(wrapper.text()).toContain('800x600')
+
+      await wrapper.setProps({
+        viewport: { width: 1920, height: 1080 }
+      })
+
+      expect(wrapper.text()).toContain('1920x1080')
+    })
+  })
+})

src/components/graph/TransformPane.vue

@@ -0,0 +1,132 @@
+<template>
+  <div
+    class="transform-pane"
+    :class="{ 'transform-pane--interacting': isInteracting }"
+    :style="transformStyle"
+    @pointerdown="handlePointerDown"
+  >
+    <!-- Vue nodes will be rendered here -->
+    <slot />
+
+    <!-- DEV ONLY: Viewport bounds visualization -->
+    <div
+      v-if="props.showDebugOverlay"
+      class="viewport-debug-overlay"
+      :style="{
+        position: 'absolute',
+        left: '10px',
+        top: '10px',
+        border: '2px solid red',
+        width: (props.viewport?.width || 0) - 20 + 'px',
+        height: (props.viewport?.height || 0) - 20 + 'px',
+        pointerEvents: 'none',
+        opacity: 0.5
+      }"
+    >
+      <div
+        style="
+          position: absolute;
+          top: 0;
+          left: 0;
+          background: red;
+          color: white;
+          padding: 2px 5px;
+          font-size: 10px;
+        "
+      >
+        Viewport: {{ props.viewport?.width }}x{{ props.viewport?.height }} DPR:
+        {{ devicePixelRatio }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { LGraphCanvas } from '@comfyorg/litegraph'
+import { computed, provide } from 'vue'
+
+import { useTransformState } from '@/composables/element/useTransformState'
+import { useCanvasTransformSync } from '@/composables/graph/useCanvasTransformSync'
+import { useTransformSettling } from '@/composables/graph/useTransformSettling'
+
+interface TransformPaneProps {
+  canvas?: LGraphCanvas
+  viewport?: { width: number; height: number }
+  showDebugOverlay?: boolean
+}
+
+const props = defineProps<TransformPaneProps>()
+
+// Get device pixel ratio for display
+const devicePixelRatio = window.devicePixelRatio || 1
+
+// Transform state management
+const {
+  camera,
+  transformStyle,
+  syncWithCanvas,
+  canvasToScreen,
+  screenToCanvas,
+  isNodeInViewport
+} = useTransformState()
+
+// Transform settling detection for re-rasterization optimization
+const canvasElement = computed(() => props.canvas?.canvas)
+const { isTransforming } = useTransformSettling(canvasElement, {
+  settleDelay: 200,
+  trackPan: true
+})
+
+// Use isTransforming for the CSS class (aliased for clarity)
+const isInteracting = isTransforming
+
+// Provide transform utilities to child components
+provide('transformState', {
+  camera,
+  canvasToScreen,
+  screenToCanvas,
+  isNodeInViewport
+})
+
+// Event delegation for node interactions
+const handlePointerDown = (event: PointerEvent) => {
+  const target = event.target as HTMLElement
+  const nodeElement = target.closest('[data-node-id]')
+
+  if (nodeElement) {
+    // TODO: Emit event for node interaction
+    // Node interaction with nodeId will be handled in future implementation
+  }
+}
+
+// Canvas transform synchronization
+const emit = defineEmits<{
+  rafStatusChange: [active: boolean]
+  transformUpdate: [time: number]
+}>()
+
+useCanvasTransformSync(props.canvas, syncWithCanvas, {
+  onStart: () => emit('rafStatusChange', true),
+  onUpdate: (duration) => emit('transformUpdate', duration),
+  onStop: () => emit('rafStatusChange', false)
+})
+</script>
+
+<style scoped>
+.transform-pane {
+  position: absolute;
+  inset: 0;
+  contain: layout style paint;
+  transform-origin: 0 0;
+  pointer-events: none;
+}
+
+.transform-pane--interacting {
+  will-change: transform;
+}
+
+/* Allow pointer events on nodes */
+.transform-pane :deep([data-node-id]) {
+  pointer-events: auto;
+}
+</style>

src/components/graph/debug/QuadTreeDebugSection.vue

@@ -0,0 +1,111 @@
+<template>
+  <div class="pt-2 border-t border-surface-200 dark-theme:border-surface-700">
+    <h4 class="font-semibold mb-1">QuadTree Spatial Index</h4>
+
+    <!-- Enable/Disable Toggle -->
+    <div class="mb-2">
+      <label class="flex items-center gap-2">
+        <input
+          :checked="enabled"
+          type="checkbox"
+          @change="$emit('toggle', ($event.target as HTMLInputElement).checked)"
+        />
+        <span>Enable Spatial Indexing</span>
+      </label>
+    </div>
+
+    <!-- Status Message -->
+    <p v-if="!enabled" class="text-muted text-xs italic">
+      {{ statusMessage }}
+    </p>
+
+    <!-- Metrics when enabled -->
+    <template v-if="enabled && metrics">
+      <p class="text-muted">Strategy: {{ strategy }}</p>
+      <p class="text-muted">Total Nodes: {{ metrics.totalNodes }}</p>
+      <p class="text-muted">Visible Nodes: {{ metrics.visibleNodes }}</p>
+      <p class="text-muted">Query Time: {{ metrics.queryTime.toFixed(2) }}ms</p>
+      <p class="text-muted">Tree Depth: {{ metrics.treeDepth }}</p>
+      <p class="text-muted">Culling Efficiency: {{ cullingEfficiency }}</p>
+      <p class="text-muted">Rebuilds: {{ metrics.rebuildCount }}</p>
+
+      <!-- Show debug visualization toggle -->
+      <div class="mt-2">
+        <label class="flex items-center gap-2">
+          <input
+            :checked="showVisualization"
+            type="checkbox"
+            @change="
+              $emit(
+                'toggle-visualization',
+                ($event.target as HTMLInputElement).checked
+              )
+            "
+          />
+          <span>Show QuadTree Boundaries</span>
+        </label>
+      </div>
+    </template>
+
+    <!-- Performance Comparison -->
+    <template v-if="enabled && performanceComparison">
+      <div class="mt-2 text-xs">
+        <p class="text-muted font-semibold">Performance vs Linear:</p>
+        <p class="text-muted">Speedup: {{ performanceComparison.speedup }}x</p>
+        <p class="text-muted">
+          Break-even: ~{{ performanceComparison.breakEvenNodeCount }} nodes
+        </p>
+      </div>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+interface Props {
+  enabled: boolean
+  metrics?: {
+    totalNodes: number
+    visibleNodes: number
+    queryTime: number
+    treeDepth: number
+    rebuildCount: number
+  }
+  strategy?: string
+  threshold?: number
+  showVisualization?: boolean
+  performanceComparison?: {
+    speedup: number
+    breakEvenNodeCount: number
+  }
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  metrics: undefined,
+  strategy: 'quadtree',
+  threshold: 100,
+  showVisualization: false,
+  performanceComparison: undefined
+})
+
+defineEmits<{
+  toggle: [enabled: boolean]
+  'toggle-visualization': [show: boolean]
+}>()
+
+const statusMessage = computed(() => {
+  if (!props.enabled && props.metrics) {
+    return `Disabled (threshold: ${props.threshold} nodes, current: ${props.metrics.totalNodes})`
+  }
+  return `Spatial indexing will enable at ${props.threshold}+ nodes`
+})
+
+const cullingEfficiency = computed(() => {
+  if (!props.metrics || props.metrics.totalNodes === 0) return 'N/A'
+
+  const culled = props.metrics.totalNodes - props.metrics.visibleNodes
+  const percentage = ((culled / props.metrics.totalNodes) * 100).toFixed(1)
+  return `${culled} nodes (${percentage}%)`
+})
+</script>

src/components/graph/debug/QuadTreeVisualization.vue

@@ -0,0 +1,112 @@
+<template>
+  <svg
+    v-if="visible && debugInfo"
+    :width="svgSize.width"
+    :height="svgSize.height"
+    :style="svgStyle"
+    class="quadtree-visualization"
+  >
+    <!-- QuadTree boundaries -->
+    <g v-for="(node, index) in flattenedNodes" :key="`quad-${index}`">
+      <rect
+        :x="node.bounds.x"
+        :y="node.bounds.y"
+        :width="node.bounds.width"
+        :height="node.bounds.height"
+        :stroke="getDepthColor(node.depth)"
+        :stroke-width="getStrokeWidth(node.depth)"
+        fill="none"
+        :opacity="0.3 + node.depth * 0.05"
+      />
+    </g>
+
+    <!-- Viewport bounds (optional) -->
+    <rect
+      v-if="viewportBounds"
+      :x="viewportBounds.x"
+      :y="viewportBounds.y"
+      :width="viewportBounds.width"
+      :height="viewportBounds.height"
+      stroke="#00ff00"
+      stroke-width="3"
+      fill="none"
+      stroke-dasharray="10,5"
+      opacity="0.8"
+    />
+  </svg>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+
+import type { Bounds } from '@/utils/spatial/QuadTree'
+
+interface Props {
+  visible: boolean
+  debugInfo: any | null
+  transformStyle: any
+  viewportBounds?: Bounds
+}
+
+const props = defineProps<Props>()
+
+// Flatten the tree structure for rendering
+const flattenedNodes = computed(() => {
+  if (!props.debugInfo?.tree) return []
+
+  const nodes: any[] = []
+  const traverse = (node: any, depth = 0) => {
+    nodes.push({
+      bounds: node.bounds,
+      depth,
+      itemCount: node.itemCount,
+      divided: node.divided
+    })
+
+    if (node.children) {
+      node.children.forEach((child: any) => traverse(child, depth + 1))
+    }
+  }
+
+  traverse(props.debugInfo.tree)
+  return nodes
+})
+
+// SVG size (matches the transform pane size)
+const svgSize = ref({ width: 20000, height: 20000 })
+
+// Apply the same transform as the TransformPane
+const svgStyle = computed(() => ({
+  ...props.transformStyle,
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  pointerEvents: 'none'
+}))
+
+// Color based on depth
+const getDepthColor = (depth: number): string => {
+  const colors = [
+    '#ff6b6b', // Red
+    '#ffa500', // Orange
+    '#ffd93d', // Yellow
+    '#6bcf7f', // Green
+    '#4da6ff', // Blue
+    '#a78bfa' // Purple
+  ]
+  return colors[depth % colors.length]
+}
+
+// Stroke width based on depth
+const getStrokeWidth = (depth: number): number => {
+  return Math.max(0.5, 2 - depth * 0.3)
+}
+</script>
+
+<style scoped>
+.quadtree-visualization {
+  position: absolute;
+  overflow: visible;
+  z-index: 10; /* Above nodes but below UI */
+}
+</style>

src/components/graph/debug/VueNodeDebugPanel.vue

@@ -0,0 +1,164 @@
+<template>
+  <!-- TransformPane Debug Controls -->
+  <div
+    class="fixed top-20 right-4 bg-surface-0 dark-theme:bg-surface-800 p-4 rounded-lg shadow-lg border border-surface-300 dark-theme:border-surface-600 z-50 pointer-events-auto w-80"
+    style="contain: layout style"
+  >
+    <h3 class="font-bold mb-2 text-sm">TransformPane Debug</h3>
+    <div class="space-y-2 text-xs">
+      <div>
+        <label class="flex items-center gap-2">
+          <input v-model="debugOverrideVueNodes" type="checkbox" />
+          <span>Enable TransformPane</span>
+        </label>
+      </div>
+
+      <!-- Canvas Metrics -->
+      <div
+        class="pt-2 border-t border-surface-200 dark-theme:border-surface-700"
+      >
+        <h4 class="font-semibold mb-1">Canvas State</h4>
+        <p class="text-muted">
+          Status: {{ canvasStore.canvas ? 'Ready' : 'Not Ready' }}
+        </p>
+        <p class="text-muted">
+          Viewport: {{ Math.round(canvasViewport.width) }}x{{
+            Math.round(canvasViewport.height)
+          }}
+        </p>
+        <template v-if="canvasStore.canvas?.ds">
+          <p class="text-muted">
+            Offset: ({{ Math.round(canvasStore.canvas.ds.offset[0]) }},
+            {{ Math.round(canvasStore.canvas.ds.offset[1]) }})
+          </p>
+          <p class="text-muted">
+            Scale: {{ canvasStore.canvas.ds.scale?.toFixed(3) || 1 }}
+          </p>
+        </template>
+      </div>
+
+      <!-- Node Metrics -->
+      <div
+        class="pt-2 border-t border-surface-200 dark-theme:border-surface-700"
+      >
+        <h4 class="font-semibold mb-1">Graph Metrics</h4>
+        <p class="text-muted">
+          Total Nodes: {{ comfyApp.graph?.nodes?.length || 0 }}
+        </p>
+        <p class="text-muted">
+          Selected Nodes: {{ canvasStore.canvas?.selectedItems?.size || 0 }}
+        </p>
+        <p class="text-muted">Vue Nodes Rendered: {{ vueNodesCount }}</p>
+        <p class="text-muted">Nodes in Viewport: {{ nodesInViewport }}</p>
+        <p class="text-muted">
+          Culled Nodes: {{ performanceMetrics.culledCount }}
+        </p>
+        <p class="text-muted">
+          Cull Percentage:
+          {{
+            Math.round(
+              ((vueNodesCount - nodesInViewport) / Math.max(vueNodesCount, 1)) *
+                100
+            )
+          }}%
+        </p>
+      </div>
+
+      <!-- Performance Metrics -->
+      <div
+        class="pt-2 border-t border-surface-200 dark-theme:border-surface-700"
+      >
+        <h4 class="font-semibold mb-1">Performance</h4>
+        <p v-memo="[currentFPS]" class="text-muted">FPS: {{ currentFPS }}</p>
+        <p v-memo="[Math.round(lastTransformTime)]" class="text-muted">
+          Transform Update: {{ Math.round(lastTransformTime) }}ms
+        </p>
+        <p
+          v-memo="[Math.round(performanceMetrics.updateTime)]"
+          class="text-muted"
+        >
+          Lifecycle Update: {{ Math.round(performanceMetrics.updateTime) }}ms
+        </p>
+        <p v-memo="[rafActive]" class="text-muted">
+          RAF Active: {{ rafActive ? 'Yes' : 'No' }}
+        </p>
+        <p v-memo="[performanceMetrics.adaptiveQuality]" class="text-muted">
+          Adaptive Quality:
+          {{ performanceMetrics.adaptiveQuality ? 'On' : 'Off' }}
+        </p>
+      </div>
+
+      <!-- Feature Flags Status -->
+      <div
+        v-if="isDevModeEnabled"
+        class="pt-2 border-t border-surface-200 dark-theme:border-surface-700"
+      >
+        <h4 class="font-semibold mb-1">Feature Flags</h4>
+        <p class="text-muted text-xs">
+          Vue Nodes: {{ shouldRenderVueNodes ? 'Enabled' : 'Disabled' }}
+        </p>
+        <p class="text-muted text-xs">
+          Dev Mode: {{ isDevModeEnabled ? 'Enabled' : 'Disabled' }}
+        </p>
+      </div>
+
+      <!-- Performance Options -->
+      <div
+        v-if="transformPaneEnabled"
+        class="pt-2 border-t border-surface-200 dark-theme:border-surface-700"
+      >
+        <h4 class="font-semibold mb-1">Debug Options</h4>
+        <label class="flex items-center gap-2">
+          <input v-model="showPerformanceOverlay" type="checkbox" />
+          <span>Show Performance Overlay</span>
+        </label>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import { app as comfyApp } from '@/scripts/app'
+import { useCanvasStore } from '@/stores/graphStore'
+
+interface Props {
+  debugOverrideVueNodes: boolean
+  canvasViewport: { width: number; height: number }
+  vueNodesCount: number
+  nodesInViewport: number
+  performanceMetrics: {
+    culledCount: number
+    updateTime: number
+    adaptiveQuality: boolean
+  }
+  currentFPS: number
+  lastTransformTime: number
+  rafActive: boolean
+  isDevModeEnabled: boolean
+  shouldRenderVueNodes: boolean
+  transformPaneEnabled: boolean
+  showPerformanceOverlay: boolean
+}
+
+interface Emits {
+  (e: 'update:debugOverrideVueNodes', value: boolean): void
+  (e: 'update:showPerformanceOverlay', value: boolean): void
+}
+
+const props = defineProps<Props>()
+const emit = defineEmits<Emits>()
+
+const canvasStore = useCanvasStore()
+
+const debugOverrideVueNodes = computed({
+  get: () => props.debugOverrideVueNodes,
+  set: (value: boolean) => emit('update:debugOverrideVueNodes', value)
+})
+
+const showPerformanceOverlay = computed({
+  get: () => props.showPerformanceOverlay,
+  set: (value: boolean) => emit('update:showPerformanceOverlay', value)
+})
+</script>

src/components/graph/vueNodes/InputSlot.vue

@@ -0,0 +1,70 @@
+<template>
+  <div v-if="renderError" class="node-error p-1 text-red-500 text-xs">⚠️</div>
+  <div
+    v-else
+    class="lg-slot lg-slot--input flex items-center gap-2 py-1 pl-2 pr-4 cursor-crosshair hover:bg-black/5"
+    :class="{
+      'opacity-70': readonly,
+      'lg-slot--connected': connected,
+      'lg-slot--compatible': compatible
+    }"
+    @pointerdown="handleClick"
+  >
+    <!-- Connection Dot -->
+    <div
+      class="lg-slot__dot w-3 h-3 rounded-full border-2"
+      :style="{
+        backgroundColor: connected ? slotColor : 'transparent',
+        borderColor: slotColor
+      }"
+    />
+
+    <!-- Slot Name -->
+    <span class="text-xs text-surface-700 whitespace-nowrap">
+      {{ slotData.name || `Input ${index}` }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { INodeSlot, LGraphNode } from '@comfyorg/litegraph'
+import { computed, onErrorCaptured, ref } from 'vue'
+
+import { useErrorHandling } from '@/composables/useErrorHandling'
+import { getSlotColor } from '@/constants/slotColors'
+
+interface InputSlotProps {
+  node: LGraphNode
+  slotData: INodeSlot
+  index: number
+  connected?: boolean
+  compatible?: boolean
+  readonly?: boolean
+}
+
+const props = defineProps<InputSlotProps>()
+
+const emit = defineEmits<{
+  'slot-click': [event: PointerEvent]
+}>()
+
+// Error boundary implementation
+const renderError = ref<string | null>(null)
+const { toastErrorHandler } = useErrorHandling()
+
+onErrorCaptured((error) => {
+  renderError.value = error.message
+  toastErrorHandler(error)
+  return false
+})
+
+// Get slot color based on type
+const slotColor = computed(() => getSlotColor(props.slotData.type))
+
+// Handle click events
+const handleClick = (event: PointerEvent) => {
+  if (!props.readonly) {
+    emit('slot-click', event)
+  }
+}
+</script>

src/components/graph/vueNodes/LGraphNode.vue

@@ -0,0 +1,184 @@
+<template>
+  <div v-if="renderError" class="node-error p-2 text-red-500 text-sm">
+    ⚠️ Node Render Error
+  </div>
+  <div
+    v-else
+    :class="[
+      'lg-node absolute border-2 rounded',
+      'contain-layout contain-style contain-paint',
+      selected ? 'border-blue-500 ring-2 ring-blue-300' : 'border-gray-600',
+      executing ? 'animate-pulse' : '',
+      nodeData.mode === 4 ? 'opacity-50' : '', // bypassed
+      error ? 'border-red-500 bg-red-50' : '',
+      isDragging ? 'will-change-transform' : '',
+      lodCssClass
+    ]"
+    :style="{
+      transform: `translate(${position?.x ?? 0}px, ${position?.y ?? 0}px)`,
+      width: size ? `${size.width}px` : '200px',
+      height: size ? `${size.height}px` : 'auto',
+      backgroundColor: '#353535'
+    }"
+    @pointerdown="handlePointerDown"
+  >
+    <!-- Header only updates on title/color changes -->
+    <NodeHeader
+      v-memo="[nodeData.title, lodLevel]"
+      :node-data="nodeData"
+      :readonly="readonly"
+      :lod-level="lodLevel"
+      @collapse="handleCollapse"
+    />
+
+    <!-- Node Body - rendered based on LOD level -->
+    <div v-if="!isMinimalLOD" class="flex flex-col gap-2 p-2">
+      <!-- Slots only rendered at full detail -->
+      <NodeSlots
+        v-if="shouldRenderSlots"
+        v-memo="[nodeData.inputs?.length, nodeData.outputs?.length, lodLevel]"
+        :node-data="nodeData"
+        :readonly="readonly"
+        :lod-level="lodLevel"
+        @slot-click="handleSlotClick"
+      />
+
+      <!-- Widgets rendered at reduced+ detail -->
+      <NodeWidgets
+        v-if="shouldRenderWidgets && nodeData.widgets?.length"
+        v-memo="[nodeData.widgets?.length, lodLevel]"
+        :node-data="nodeData"
+        :readonly="readonly"
+        :lod-level="lodLevel"
+      />
+
+      <!-- Custom content at reduced+ detail -->
+      <NodeContent
+        v-if="shouldRenderContent && hasCustomContent"
+        :node-data="nodeData"
+        :readonly="readonly"
+        :lod-level="lodLevel"
+      />
+
+      <!-- Placeholder if no widgets and in reduced+ mode -->
+      <div
+        v-if="!nodeData.widgets?.length && !hasCustomContent && !isMinimalLOD"
+        class="text-gray-500 text-sm text-center py-4"
+      >
+        No widgets
+      </div>
+    </div>
+
+    <!-- Progress bar for executing state -->
+    <div
+      v-if="executing && progress !== undefined"
+      class="absolute bottom-0 left-0 h-1 bg-primary-500 transition-all duration-300"
+      :style="{ width: `${progress * 100}%` }"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onErrorCaptured, ref, toRef } from 'vue'
+
+// Import the VueNodeData type
+import type { VueNodeData } from '@/composables/graph/useGraphNodeManager'
+import { LODLevel, useLOD } from '@/composables/graph/useLOD'
+import { useErrorHandling } from '@/composables/useErrorHandling'
+
+import NodeContent from './NodeContent.vue'
+import NodeHeader from './NodeHeader.vue'
+import NodeSlots from './NodeSlots.vue'
+import NodeWidgets from './NodeWidgets.vue'
+
+// Extended props for main node component
+interface LGraphNodeProps {
+  nodeData: VueNodeData
+  position?: { x: number; y: number }
+  size?: { width: number; height: number }
+  readonly?: boolean
+  selected?: boolean
+  executing?: boolean
+  progress?: number
+  error?: string | null
+  zoomLevel?: number
+}
+
+const props = defineProps<LGraphNodeProps>()
+
+const emit = defineEmits<{
+  'node-click': [event: PointerEvent, nodeData: VueNodeData]
+  'slot-click': [
+    event: PointerEvent,
+    nodeData: VueNodeData,
+    slotIndex: number,
+    isInput: boolean
+  ]
+  collapse: []
+}>()
+
+// LOD (Level of Detail) system based on zoom level
+const zoomRef = toRef(() => props.zoomLevel ?? 1)
+const {
+  lodLevel,
+  shouldRenderWidgets,
+  shouldRenderSlots,
+  shouldRenderContent,
+  lodCssClass
+} = useLOD(zoomRef)
+
+// Computed properties for template usage
+const isMinimalLOD = computed(() => lodLevel.value === LODLevel.MINIMAL)
+
+// Error boundary implementation
+const renderError = ref<string | null>(null)
+const { toastErrorHandler } = useErrorHandling()
+
+onErrorCaptured((error) => {
+  renderError.value = error.message
+  toastErrorHandler(error)
+  return false // Prevent error propagation
+})
+
+// Track dragging state for will-change optimization
+const isDragging = ref(false)
+
+// Check if node has custom content
+const hasCustomContent = computed(() => {
+  // Currently all content is handled through widgets
+  // This remains false but provides extensibility point
+  return false
+})
+
+// Event handlers
+const handlePointerDown = (event: PointerEvent) => {
+  if (!props.nodeData) {
+    console.warn('LGraphNode: nodeData is null/undefined in handlePointerDown')
+    return
+  }
+  emit('node-click', event, props.nodeData)
+}
+
+const handleCollapse = () => {
+  emit('collapse')
+}
+
+const handleSlotClick = (
+  event: PointerEvent,
+  slotIndex: number,
+  isInput: boolean
+) => {
+  if (!props.nodeData) {
+    console.warn('LGraphNode: nodeData is null/undefined in handleSlotClick')
+    return
+  }
+  emit('slot-click', event, props.nodeData, slotIndex, isInput)
+}
+
+// Expose methods for parent to control dragging state
+defineExpose({
+  setDragging(dragging: boolean) {
+    isDragging.value = dragging
+  }
+})
+</script>

src/components/graph/vueNodes/NodeContent.vue

@@ -0,0 +1,40 @@
+<template>
+  <div v-if="renderError" class="node-error p-2 text-red-500 text-sm">
+    ⚠️ Node Content Error
+  </div>
+  <div v-else class="lg-node-content">
+    <!-- Default slot for custom content -->
+    <slot>
+      <!-- This component serves as a placeholder for future extensibility -->
+      <!-- Currently all node content is rendered through the widget system -->
+    </slot>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { LGraphNode } from '@comfyorg/litegraph'
+import { onErrorCaptured, ref } from 'vue'
+
+import type { VueNodeData } from '@/composables/graph/useGraphNodeManager'
+import type { LODLevel } from '@/composables/graph/useLOD'
+import { useErrorHandling } from '@/composables/useErrorHandling'
+
+interface NodeContentProps {
+  node?: LGraphNode // For backwards compatibility
+  nodeData?: VueNodeData // New clean data structure
+  readonly?: boolean
+  lodLevel?: LODLevel
+}
+
+defineProps<NodeContentProps>()
+
+// Error boundary implementation
+const renderError = ref<string | null>(null)
+const { toastErrorHandler } = useErrorHandling()
+
+onErrorCaptured((error) => {
+  renderError.value = error.message
+  toastErrorHandler(error)
+  return false
+})
+</script>

src/components/graph/vueNodes/NodeHeader.vue

@@ -0,0 +1,116 @@
+<template>
+  <div v-if="renderError" class="node-error p-2 text-red-500 text-sm">
+    ⚠️ Node Header Error
+  </div>
+  <div
+    v-else
+    class="lg-node-header flex items-center justify-between px-3 py-2 rounded-t cursor-move"
+    :style="{
+      backgroundColor: headerColor,
+      color: textColor
+    }"
+    @dblclick="handleDoubleClick"
+  >
+    <!-- Node Title -->
+    <span class="text-sm font-medium truncate flex-1">
+      {{ nodeInfo?.title || 'Untitled' }}
+    </span>
+
+    <!-- Node Controls -->
+    <div class="flex items-center gap-1 ml-2">
+      <!-- Collapse/Expand Button -->
+      <button
+        v-if="!readonly"
+        class="lg-node-header__control p-0.5 rounded hover:bg-white/20 dark-theme:hover:bg-black/20 transition-colors opacity-60 hover:opacity-100"
+        title="Toggle collapse"
+        @click.stop="handleCollapse"
+      >
+        <svg
+          class="w-3 h-3 transition-transform"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+        >
+          <polyline points="6 9 12 15 18 9"></polyline>
+        </svg>
+      </button>
+
+      <!-- Additional controls can be added here -->
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { LGraphNode } from '@comfyorg/litegraph'
+import { computed, onErrorCaptured, ref } from 'vue'
+
+import type { VueNodeData } from '@/composables/graph/useGraphNodeManager'
+import type { LODLevel } from '@/composables/graph/useLOD'
+import { useErrorHandling } from '@/composables/useErrorHandling'
+
+interface NodeHeaderProps {
+  node?: LGraphNode // For backwards compatibility
+  nodeData?: VueNodeData // New clean data structure
+  readonly?: boolean
+  lodLevel?: LODLevel
+}
+
+const props = defineProps<NodeHeaderProps>()
+
+const emit = defineEmits<{
+  collapse: []
+  'title-edit': []
+}>()
+
+// Error boundary implementation
+const renderError = ref<string | null>(null)
+const { toastErrorHandler } = useErrorHandling()
+
+onErrorCaptured((error) => {
+  renderError.value = error.message
+  toastErrorHandler(error)
+  return false
+})
+
+const nodeInfo = computed(() => props.nodeData || props.node)
+
+// Compute header color based on node color property or type
+const headerColor = computed(() => {
+  const info = nodeInfo.value
+  if (!info) return '#353535'
+
+  if (info.mode === 4) return '#666' // Bypassed
+  if (info.mode === 2) return '#444' // Muted
+  return '#353535' // Default
+})
+
+// Compute text color for contrast
+const textColor = computed(() => {
+  const color = headerColor.value
+  if (!color || color === '#353535' || color === '#444' || color === '#666') {
+    return '#fff'
+  }
+  const colorStr = String(color)
+  const rgb = parseInt(
+    colorStr.startsWith('#') ? colorStr.slice(1) : colorStr,
+    16
+  )
+  const r = (rgb >> 16) & 255
+  const g = (rgb >> 8) & 255
+  const b = rgb & 255
+  const brightness = (r * 299 + g * 587 + b * 114) / 1000
+  return brightness > 128 ? '#000' : '#fff'
+})
+
+// Event handlers
+const handleCollapse = () => {
+  emit('collapse')
+}
+
+const handleDoubleClick = () => {
+  if (!props.readonly) {
+    emit('title-edit')
+  }
+}
+</script>

src/components/graph/vueNodes/NodeSlots.vue

@@ -0,0 +1,91 @@
+<template>
+  <div v-if="renderError" class="node-error p-2 text-red-500 text-sm">
+    ⚠️ Node Slots Error
+  </div>
+  <div v-else class="lg-node-slots">
+    <!-- For now, render slots info as text to see what's there -->
+    <div v-if="nodeInfo?.inputs?.length" class="mb-2">
+      <div class="text-xs text-gray-400 mb-1">Inputs:</div>
+      <div
+        v-for="(input, index) in nodeInfo.inputs"
+        :key="`input-${index}`"
+        class="text-xs text-gray-300"
+      >
+        {{ getInputName(input, index) }} ({{ getInputType(input) }})
+      </div>
+    </div>
+
+    <div v-if="nodeInfo?.outputs?.length">
+      <div class="text-xs text-gray-400 mb-1">Outputs:</div>
+      <div
+        v-for="(output, index) in nodeInfo.outputs"
+        :key="`output-${index}`"
+        class="text-xs text-gray-300"
+      >
+        {{ getOutputName(output, index) }} ({{ getOutputType(output) }})
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { LGraphNode } from '@comfyorg/litegraph'
+import { computed, onErrorCaptured, ref } from 'vue'
+
+// import InputSlot from './InputSlot.vue'
+// import OutputSlot from './OutputSlot.vue'
+
+import type { VueNodeData } from '@/composables/graph/useGraphNodeManager'
+import type { LODLevel } from '@/composables/graph/useLOD'
+import { useErrorHandling } from '@/composables/useErrorHandling'
+import { isSlotObject } from '@/utils/typeGuardUtil'
+
+interface NodeSlotsProps {
+  node?: LGraphNode // For backwards compatibility
+  nodeData?: VueNodeData // New clean data structure
+  readonly?: boolean
+  lodLevel?: LODLevel
+}
+
+const props = defineProps<NodeSlotsProps>()
+
+const nodeInfo = computed(() => props.nodeData || props.node)
+
+const getInputName = (input: unknown, index: number): string => {
+  if (isSlotObject(input) && input.name) {
+    return input.name
+  }
+  return `Input ${index}`
+}
+
+const getInputType = (input: unknown): string => {
+  if (isSlotObject(input) && input.type) {
+    return input.type
+  }
+  return 'any'
+}
+
+const getOutputName = (output: unknown, index: number): string => {
+  if (isSlotObject(output) && output.name) {
+    return output.name
+  }
+  return `Output ${index}`
+}
+
+const getOutputType = (output: unknown): string => {
+  if (isSlotObject(output) && output.type) {
+    return output.type
+  }
+  return 'any'
+}
+
+// Error boundary implementation
+const renderError = ref<string | null>(null)
+const { toastErrorHandler } = useErrorHandling()
+
+onErrorCaptured((error) => {
+  renderError.value = error.message
+  toastErrorHandler(error)
+  return false
+})
+</script>

src/components/graph/vueNodes/NodeWidgets.vue

@@ -0,0 +1,122 @@
+<template>
+  <div v-if="renderError" class="node-error p-2 text-red-500 text-sm">
+    ⚠️ Node Widgets Error
+  </div>
+  <div v-else class="lg-node-widgets flex flex-col gap-2">
+    <component
+      :is="widget.vueComponent"
+      v-for="(widget, index) in processedWidgets"
+      :key="`widget-${index}-${widget.name}`"
+      :widget="widget.simplified"
+      :model-value="widget.value"
+      :readonly="readonly"
+      @update:model-value="widget.updateHandler"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { LGraphNode } from '@comfyorg/litegraph'
+import { computed, onErrorCaptured, ref } from 'vue'
+
+// Import widget components directly
+import WidgetInputText from '@/components/graph/vueWidgets/WidgetInputText.vue'
+import { widgetTypeToComponent } from '@/components/graph/vueWidgets/widgetRegistry'
+import type {
+  SafeWidgetData,
+  VueNodeData
+} from '@/composables/graph/useGraphNodeManager'
+import { LODLevel } from '@/composables/graph/useLOD'
+import {
+  ESSENTIAL_WIDGET_TYPES,
+  useWidgetRenderer
+} from '@/composables/graph/useWidgetRenderer'
+import { useErrorHandling } from '@/composables/useErrorHandling'
+import type { SimplifiedWidget, WidgetValue } from '@/types/simplifiedWidget'
+
+interface NodeWidgetsProps {
+  node?: LGraphNode
+  nodeData?: VueNodeData
+  readonly?: boolean
+  lodLevel?: LODLevel
+}
+
+const props = defineProps<NodeWidgetsProps>()
+
+// Use widget renderer composable
+const { getWidgetComponent, shouldRenderAsVue } = useWidgetRenderer()
+
+// Error boundary implementation
+const renderError = ref<string | null>(null)
+
+const { toastErrorHandler } = useErrorHandling()
+
+onErrorCaptured((error) => {
+  renderError.value = error.message
+  toastErrorHandler(error)
+  return false
+})
+
+const nodeInfo = computed(() => props.nodeData || props.node)
+
+interface ProcessedWidget {
+  name: string
+  vueComponent: any
+  simplified: SimplifiedWidget
+  value: WidgetValue
+  updateHandler: (value: unknown) => void
+}
+
+const processedWidgets = computed((): ProcessedWidget[] => {
+  const info = nodeInfo.value
+  if (!info?.widgets) return []
+
+  const widgets = info.widgets as SafeWidgetData[]
+  const lodLevel = props.lodLevel
+  const result: ProcessedWidget[] = []
+
+  if (lodLevel === LODLevel.MINIMAL) {
+    return []
+  }
+
+  for (const widget of widgets) {
+    if (widget.options?.hidden) continue
+    if (widget.options?.canvasOnly) continue
+    if (!widget.type) continue
+    if (!shouldRenderAsVue(widget)) continue
+
+    if (
+      lodLevel === LODLevel.REDUCED &&
+      !ESSENTIAL_WIDGET_TYPES.has(widget.type)
+    )
+      continue
+
+    const componentName = getWidgetComponent(widget.type)
+    const vueComponent = widgetTypeToComponent[componentName] || WidgetInputText
+
+    const simplified: SimplifiedWidget = {
+      name: widget.name,
+      type: widget.type,
+      value: widget.value,
+      options: widget.options,
+      callback: widget.callback
+    }
+
+    const updateHandler = (value: unknown) => {
+      if (widget.callback) {
+        widget.callback(value)
+      }
+    }
+
+    result.push({
+      name: widget.name,
+      vueComponent,
+      simplified,
+      value: widget.value,
+      updateHandler
+    })
+  }
+
+  return result
+})
+</script>

src/components/graph/vueNodes/OutputSlot.vue

@@ -0,0 +1,71 @@
+<template>
+  <div v-if="renderError" class="node-error p-1 text-red-500 text-xs">⚠️</div>
+  <div
+    v-else
+    class="lg-slot lg-slot--output flex items-center gap-2 py-1 pr-2 pl-4 cursor-crosshair hover:bg-black/5 justify-end"
+    :class="{
+      'opacity-70': readonly,
+      'lg-slot--connected': connected,
+      'lg-slot--compatible': compatible
+    }"
+    @pointerdown="handleClick"
+  >
+    <!-- Slot Name -->
+    <span class="text-xs text-surface-700 whitespace-nowrap">
+      {{ slotData.name || `Output ${index}` }}
+    </span>
+
+    <!-- Connection Dot -->
+    <div
+      class="lg-slot__dot w-3 h-3 rounded-full border-2"
+      :style="{
+        backgroundColor: connected ? slotColor : 'transparent',
+        borderColor: slotColor
+      }"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { INodeSlot, LGraphNode } from '@comfyorg/litegraph'
+import { computed, onErrorCaptured, ref } from 'vue'
+
+import { useErrorHandling } from '@/composables/useErrorHandling'
+import { getSlotColor } from '@/constants/slotColors'
+
+interface OutputSlotProps {
+  node: LGraphNode
+  slotData: INodeSlot
+  index: number
+  connected?: boolean
+  compatible?: boolean
+  readonly?: boolean
+}
+
+const props = defineProps<OutputSlotProps>()
+
+const emit = defineEmits<{
+  'slot-click': [event: PointerEvent]
+}>()
+
+// Error boundary implementation
+const renderError = ref<string | null>(null)
+
+const { toastErrorHandler } = useErrorHandling()
+
+onErrorCaptured((error) => {
+  renderError.value = error.message
+  toastErrorHandler(error)
+  return false
+})
+
+// Get slot color based on type
+const slotColor = computed(() => getSlotColor(props.slotData.type))
+
+// Handle click events
+const handleClick = (event: PointerEvent) => {
+  if (!props.readonly) {
+    emit('slot-click', event)
+  }
+}
+</script>

src/components/graph/vueNodes/widgets/LOD_IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,295 @@
+# Level of Detail (LOD) Implementation Guide for Widgets
+
+## What is Level of Detail (LOD)?
+
+Level of Detail is a technique used to optimize performance by showing different amounts of detail based on how zoomed in the user is. Think of it like Google Maps - when you're zoomed out looking at the whole country, you only see major cities and highways. When you zoom in close, you see street names, building details, and restaurants.
+
+For ComfyUI nodes, this means:
+- **Zoomed out** (viewing many nodes): Show only essential controls, hide labels and descriptions
+- **Zoomed in** (focusing on specific nodes): Show all details, labels, help text, and visual polish
+
+## Why LOD Matters
+
+Without LOD optimization:
+- 1000+ nodes with full detail = browser lag and poor performance
+- Text that's too small to read still gets rendered (wasted work)
+- Visual effects that are invisible at distance still consume GPU
+
+With LOD optimization:
+- Smooth performance even with large node graphs
+- Battery life improvement on laptops
+- Better user experience across different zoom levels
+
+## How to Implement LOD in Your Widget
+
+### Step 1: Get the LOD Context
+
+Every widget component gets a `zoomLevel` prop. Use this to determine how much detail to show:
+
+```vue
+<script setup lang="ts">
+import { computed, toRef } from 'vue'
+import { useLOD } from '@/composables/graph/useLOD'
+
+const props = defineProps<{
+  widget: any
+  zoomLevel: number
+  // ... other props
+}>()
+
+// Get LOD information
+const { lodScore, lodLevel } = useLOD(toRef(() => props.zoomLevel))
+</script>
+```
+
+**Primary API:** Use `lodScore` (0-1) for granular control and smooth transitions  
+**Convenience API:** Use `lodLevel` ('minimal'|'reduced'|'full') for simple on/off decisions
+
+### Step 2: Choose What to Show at Different Zoom Levels
+
+#### Understanding the LOD Score
+- `lodScore` is a number from 0 to 1
+- 0 = completely zoomed out (show minimal detail)
+- 1 = fully zoomed in (show everything)
+- 0.5 = medium zoom (show some details)
+
+#### Understanding LOD Levels
+- `'minimal'` = zoom level 0.4 or below (very zoomed out)
+- `'reduced'` = zoom level 0.4 to 0.8 (medium zoom)
+- `'full'` = zoom level 0.8 or above (zoomed in close)
+
+### Step 3: Implement Your Widget's LOD Strategy
+
+Here's a complete example of a slider widget with LOD:
+
+```vue
+<template>
+  <div class="number-widget">
+    <!-- The main control always shows -->
+    <input 
+      v-model="value"
+      type="range"
+      :min="widget.min"
+      :max="widget.max"
+      class="widget-slider"
+    />
+    
+    <!-- Show label only when zoomed in enough to read it -->
+    <label 
+      v-if="showLabel"
+      class="widget-label"
+    >
+      {{ widget.name }}
+    </label>
+    
+    <!-- Show precise value only when fully zoomed in -->
+    <span 
+      v-if="showValue"
+      class="widget-value"
+    >
+      {{ formattedValue }}
+    </span>
+    
+    <!-- Show description only at full detail -->
+    <div 
+      v-if="showDescription && widget.description"
+      class="widget-description"
+    >
+      {{ widget.description }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, toRef } from 'vue'
+import { useLOD } from '@/composables/graph/useLOD'
+
+const props = defineProps<{
+  widget: any
+  zoomLevel: number
+}>()
+
+const { lodScore, lodLevel } = useLOD(toRef(() => props.zoomLevel))
+
+// Define when to show each element
+const showLabel = computed(() => {
+  // Show label when user can actually read it
+  return lodScore.value > 0.4  // Roughly 12px+ text size
+})
+
+const showValue = computed(() => {
+  // Show precise value only when zoomed in close
+  return lodScore.value > 0.7  // User is focused on this specific widget
+})
+
+const showDescription = computed(() => {
+  // Description only at full detail
+  return lodLevel.value === 'full'  // Maximum zoom level
+})
+
+// You can also use LOD for styling
+const widgetClasses = computed(() => {
+  const classes = ['number-widget']
+  
+  if (lodLevel.value === 'minimal') {
+    classes.push('widget--minimal')
+  }
+  
+  return classes
+})
+</script>
+
+<style scoped>
+/* Apply different styles based on LOD */
+.widget--minimal {
+  /* Simplified appearance when zoomed out */
+  .widget-slider {
+    height: 4px;  /* Thinner slider */
+    opacity: 0.9;
+  }
+}
+
+/* Normal styling */
+.widget-slider {
+  height: 8px;
+  transition: height 0.2s ease;
+}
+
+.widget-label {
+  font-size: 0.8rem;
+  color: var(--text-secondary);
+}
+
+.widget-value {
+  font-family: monospace;
+  font-size: 0.7rem;
+  color: var(--text-accent);
+}
+
+.widget-description {
+  font-size: 0.6rem;
+  color: var(--text-muted);
+  margin-top: 4px;
+}
+</style>
+```
+
+## Common LOD Patterns
+
+### Pattern 1: Essential vs. Nice-to-Have
+```typescript
+// Always show the main functionality
+const showMainControl = computed(() => true)
+
+// Granular control with lodScore
+const showLabels = computed(() => lodScore.value > 0.4)
+const labelOpacity = computed(() => Math.max(0.3, lodScore.value))
+
+// Simple control with lodLevel  
+const showExtras = computed(() => lodLevel.value === 'full')
+```
+
+### Pattern 2: Smooth Opacity Transitions
+```typescript
+// Gradually fade elements based on zoom
+const labelOpacity = computed(() => {
+  // Fade in from zoom 0.3 to 0.6
+  return Math.max(0, Math.min(1, (lodScore.value - 0.3) / 0.3))
+})
+```
+
+### Pattern 3: Progressive Detail
+```typescript
+const detailLevel = computed(() => {
+  if (lodScore.value < 0.3) return 'none'
+  if (lodScore.value < 0.6) return 'basic'
+  if (lodScore.value < 0.8) return 'standard'
+  return 'full'
+})
+```
+
+## LOD Guidelines by Widget Type
+
+### Text Input Widgets
+- **Always show**: The input field itself
+- **Medium zoom**: Show label
+- **High zoom**: Show placeholder text, validation messages
+- **Full zoom**: Show character count, format hints
+
+### Button Widgets  
+- **Always show**: The button
+- **Medium zoom**: Show button text
+- **High zoom**: Show button description
+- **Full zoom**: Show keyboard shortcuts, tooltips
+
+### Selection Widgets (Dropdown, Radio)
+- **Always show**: The current selection
+- **Medium zoom**: Show option labels
+- **High zoom**: Show all options when expanded
+- **Full zoom**: Show option descriptions, icons
+
+### Complex Widgets (Color Picker, File Browser)
+- **Always show**: Simplified representation (color swatch, filename)
+- **Medium zoom**: Show basic controls
+- **High zoom**: Show full interface
+- **Full zoom**: Show advanced options, previews
+
+## Design Collaboration Guidelines
+
+### For Designers
+When designing widgets, consider creating variants for different zoom levels:
+
+1. **Minimal Design** (far away view)
+   - Essential elements only
+   - Higher contrast for visibility
+   - Simplified shapes and fewer details
+
+2. **Standard Design** (normal view)
+   - Balanced detail and simplicity
+   - Clear labels and readable text
+   - Good for most use cases
+
+3. **Full Detail Design** (close-up view)
+   - All labels, descriptions, and help text
+   - Rich visual effects and polish
+   - Maximum information density
+
+### Design Handoff Checklist
+- [ ] Specify which elements are essential vs. nice-to-have
+- [ ] Define minimum readable sizes for text elements
+- [ ] Provide simplified versions for distant viewing
+- [ ] Consider color contrast at different opacity levels
+- [ ] Test designs at multiple zoom levels
+
+## Testing Your LOD Implementation
+
+### Manual Testing
+1. Create a workflow with your widget
+2. Zoom out until nodes are very small
+3. Verify essential functionality still works
+4. Zoom in gradually and check that details appear smoothly
+5. Test performance with 50+ nodes containing your widget
+
+### Performance Considerations
+- Avoid complex calculations in LOD computed properties
+- Use `v-if` instead of `v-show` for elements that won't render
+- Consider using `v-memo` for expensive widget content
+- Test on lower-end devices
+
+### Common Mistakes
+❌ **Don't**: Hide the main widget functionality at any zoom level
+❌ **Don't**: Use complex animations that trigger at every zoom change  
+❌ **Don't**: Make LOD thresholds too sensitive (causes flickering)
+❌ **Don't**: Forget to test with real content and edge cases
+
+✅ **Do**: Keep essential functionality always visible
+✅ **Do**: Use smooth transitions between LOD levels
+✅ **Do**: Test with varying content lengths and types
+✅ **Do**: Consider accessibility at all zoom levels
+
+## Getting Help
+
+- Check existing widgets in `src/components/graph/vueNodes/widgets/` for examples
+- Ask in the ComfyUI frontend Discord for LOD implementation questions
+- Test your changes with the LOD debug panel (top-right in GraphCanvas)
+- Profile performance impact using browser dev tools

src/components/graph/vueWidgets/WidgetButton.vue

@@ -0,0 +1,38 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <Button v-bind="filteredProps" :disabled="readonly" @click="handleClick" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import Button from 'primevue/button'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  BADGE_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+// Button widgets don't have a v-model value, they trigger actions
+const props = defineProps<{
+  widget: SimplifiedWidget<void>
+  readonly?: boolean
+}>()
+
+// Button specific excluded props
+const BUTTON_EXCLUDED_PROPS = [...BADGE_EXCLUDED_PROPS, 'iconClass'] as const
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, BUTTON_EXCLUDED_PROPS)
+)
+
+const handleClick = () => {
+  if (!props.readonly && props.widget.callback) {
+    props.widget.callback()
+  }
+}
+</script>

src/components/graph/vueWidgets/WidgetChart.vue

@@ -0,0 +1,65 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <div class="p-4 border border-gray-300 dark-theme:border-gray-600 rounded">
+      <!-- Simple chart placeholder - can be enhanced with Chart.js when available -->
+      <div
+        v-if="!value || !Array.isArray(value.data)"
+        class="text-center text-gray-500 dark-theme:text-gray-400"
+      >
+        No chart data available
+      </div>
+      <div v-else class="space-y-2">
+        <div v-if="value.title" class="text-center font-semibold">
+          {{ value.title }}
+        </div>
+        <div class="space-y-1">
+          <div
+            v-for="(item, index) in value.data"
+            :key="index"
+            class="flex justify-between items-center"
+          >
+            <span class="text-sm">{{ item.label || `Item ${index + 1}` }}</span>
+            <div class="flex items-center gap-2">
+              <div
+                class="h-3 bg-blue-500 rounded"
+                :style="{
+                  width: `${Math.max((item.value / maxValue) * 100, 5)}px`
+                }"
+              ></div>
+              <span class="text-sm font-mono">{{ item.value }}</span>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+
+interface ChartData {
+  title?: string
+  data: Array<{
+    label: string
+    value: number
+  }>
+}
+
+const value = defineModel<ChartData>({ required: true })
+
+defineProps<{
+  widget: SimplifiedWidget<ChartData>
+  readonly?: boolean
+}>()
+
+const maxValue = computed(() => {
+  if (!value.value?.data?.length) return 1
+  return Math.max(...value.value.data.map((item) => item.value))
+})
+</script>

src/components/graph/vueWidgets/WidgetColorPicker.vue

@@ -0,0 +1,33 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <ColorPicker v-model="value" v-bind="filteredProps" :disabled="readonly" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import ColorPicker from 'primevue/colorpicker'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  PANEL_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const value = defineModel<string>({ required: true })
+
+const props = defineProps<{
+  widget: SimplifiedWidget<string>
+  readonly?: boolean
+}>()
+
+// ColorPicker specific excluded props include panel/overlay classes
+const COLOR_PICKER_EXCLUDED_PROPS = [...PANEL_EXCLUDED_PROPS] as const
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, COLOR_PICKER_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetFileUpload.vue

@@ -0,0 +1,66 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <FileUpload
+      v-bind="filteredProps"
+      :disabled="readonly"
+      @upload="handleUpload"
+      @select="handleSelect"
+      @remove="handleRemove"
+      @clear="handleClear"
+      @error="handleError"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import FileUpload from 'primevue/fileupload'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  STANDARD_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+// FileUpload doesn't have a traditional v-model, it handles files through events
+const props = defineProps<{
+  widget: SimplifiedWidget<File[] | null>
+  readonly?: boolean
+}>()
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, STANDARD_EXCLUDED_PROPS)
+)
+
+const handleUpload = (event: any) => {
+  if (!props.readonly && props.widget.callback) {
+    props.widget.callback(event.files)
+  }
+}
+
+const handleSelect = (event: any) => {
+  if (!props.readonly && props.widget.callback) {
+    props.widget.callback(event.files)
+  }
+}
+
+const handleRemove = (event: any) => {
+  if (!props.readonly && props.widget.callback) {
+    props.widget.callback(event.files)
+  }
+}
+
+const handleClear = () => {
+  if (!props.readonly && props.widget.callback) {
+    props.widget.callback([])
+  }
+}
+
+const handleError = (event: any) => {
+  // Could be extended to handle error reporting
+  console.warn('File upload error:', event)
+}
+</script>

src/components/graph/vueWidgets/WidgetGalleria.vue

@@ -0,0 +1,101 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <Galleria
+      v-model:activeIndex="activeIndex"
+      :value="galleryImages"
+      v-bind="filteredProps"
+      :disabled="readonly"
+      :show-thumbnails="showThumbnails"
+      :show-indicators="showIndicators"
+      :show-nav-buttons="showNavButtons"
+      class="max-w-full"
+    >
+      <template #item="{ item }">
+        <img
+          :src="item.itemImageSrc || item.src || item"
+          :alt="item.alt || 'Gallery image'"
+          class="w-full h-auto max-h-64 object-contain"
+        />
+      </template>
+      <template #thumbnail="{ item }">
+        <img
+          :src="item.thumbnailImageSrc || item.src || item"
+          :alt="item.alt || 'Gallery thumbnail'"
+          class="w-16 h-16 object-cover"
+        />
+      </template>
+    </Galleria>
+  </div>
+</template>
+
+<script setup lang="ts">
+import Galleria from 'primevue/galleria'
+import { computed, ref } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  GALLERIA_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+interface GalleryImage {
+  itemImageSrc?: string
+  thumbnailImageSrc?: string
+  src?: string
+  alt?: string
+}
+
+type GalleryValue = string[] | GalleryImage[]
+
+const value = defineModel<GalleryValue>({ required: true })
+
+const props = defineProps<{
+  widget: SimplifiedWidget<GalleryValue>
+  readonly?: boolean
+}>()
+
+const activeIndex = ref(0)
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, GALLERIA_EXCLUDED_PROPS)
+)
+
+const galleryImages = computed(() => {
+  if (!value.value || !Array.isArray(value.value)) return []
+
+  return value.value.map((item, index) => {
+    if (typeof item === 'string') {
+      return {
+        itemImageSrc: item,
+        thumbnailImageSrc: item,
+        alt: `Image ${index + 1}`
+      }
+    }
+    return item
+  })
+})
+
+const showThumbnails = computed(() => {
+  return (
+    props.widget.options?.showThumbnails !== false &&
+    galleryImages.value.length > 1
+  )
+})
+
+const showIndicators = computed(() => {
+  return (
+    props.widget.options?.showIndicators !== false &&
+    galleryImages.value.length > 1
+  )
+})
+
+const showNavButtons = computed(() => {
+  return (
+    props.widget.options?.showNavButtons !== false &&
+    galleryImages.value.length > 1
+  )
+})
+</script>

src/components/graph/vueWidgets/WidgetImage.vue

@@ -0,0 +1,29 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <Image v-bind="filteredProps" :src="widget.value" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import Image from 'primevue/image'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  IMAGE_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+// Image widgets typically don't have v-model, they display a source URL/path
+const props = defineProps<{
+  widget: SimplifiedWidget<string>
+  readonly?: boolean
+}>()
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, IMAGE_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetImageCompare.vue

@@ -0,0 +1,172 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <div
+      class="image-compare-container relative overflow-hidden rounded border border-gray-300 dark-theme:border-gray-600"
+    >
+      <div
+        v-if="!beforeImage || !afterImage"
+        class="p-4 text-center text-gray-500 dark-theme:text-gray-400"
+      >
+        Before and after images required
+      </div>
+      <div v-else class="relative">
+        <!-- After image (base layer) -->
+        <Image
+          v-bind="filteredProps"
+          :src="afterImage"
+          class="w-full h-auto"
+          :alt="afterAlt"
+        />
+        <!-- Before image (overlay layer) -->
+        <div
+          class="absolute top-0 left-0 h-full overflow-hidden transition-all duration-300 ease-in-out"
+          :style="{ width: `${sliderPosition}%` }"
+        >
+          <Image
+            v-bind="filteredProps"
+            :src="beforeImage"
+            class="w-full h-auto"
+            :alt="beforeAlt"
+          />
+        </div>
+        <!-- Slider handle -->
+        <div
+          class="absolute top-0 h-full w-0.5 bg-white shadow-lg cursor-col-resize z-10 transition-all duration-100"
+          :style="{ left: `${sliderPosition}%` }"
+          @mousedown="startDrag"
+          @touchstart="startDrag"
+        >
+          <div
+            class="absolute top-1/2 -translate-y-1/2 -translate-x-1/2 w-8 h-8 bg-white rounded-full shadow-md flex items-center justify-center"
+          >
+            <div class="w-4 h-4 flex items-center justify-center">
+              <div class="w-0.5 h-3 bg-gray-600 mr-0.5"></div>
+              <div class="w-0.5 h-3 bg-gray-600"></div>
+            </div>
+          </div>
+        </div>
+        <!-- Labels -->
+        <div
+          v-if="showLabels"
+          class="absolute top-2 left-2 px-2 py-1 bg-black bg-opacity-50 text-white text-xs rounded"
+        >
+          {{ beforeLabel }}
+        </div>
+        <div
+          v-if="showLabels"
+          class="absolute top-2 right-2 px-2 py-1 bg-black bg-opacity-50 text-white text-xs rounded"
+        >
+          {{ afterLabel }}
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import Image from 'primevue/image'
+import { computed, onMounted, onUnmounted, ref } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  IMAGE_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+interface ImageCompareValue {
+  before: string
+  after: string
+  beforeAlt?: string
+  afterAlt?: string
+  beforeLabel?: string
+  afterLabel?: string
+  showLabels?: boolean
+  initialPosition?: number
+}
+
+// Image compare widgets typically don't have v-model, they display comparison
+const props = defineProps<{
+  widget: SimplifiedWidget<ImageCompareValue>
+  readonly?: boolean
+}>()
+
+const sliderPosition = ref(50) // Default to 50% (middle)
+const isDragging = ref(false)
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, IMAGE_EXCLUDED_PROPS)
+)
+
+const beforeImage = computed(() => {
+  const value = props.widget.value
+  return typeof value === 'string' ? value : value?.before
+})
+
+const afterImage = computed(() => {
+  const value = props.widget.value
+  return typeof value === 'string' ? value : value?.after
+})
+
+const beforeAlt = computed(
+  () => props.widget.value?.beforeAlt || 'Before image'
+)
+const afterAlt = computed(() => props.widget.value?.afterAlt || 'After image')
+const beforeLabel = computed(() => props.widget.value?.beforeLabel || 'Before')
+const afterLabel = computed(() => props.widget.value?.afterLabel || 'After')
+const showLabels = computed(() => props.widget.value?.showLabels !== false)
+
+onMounted(() => {
+  if (props.widget.value?.initialPosition !== undefined) {
+    sliderPosition.value = Math.max(
+      0,
+      Math.min(100, props.widget.value.initialPosition)
+    )
+  }
+})
+
+const startDrag = (event: MouseEvent | TouchEvent) => {
+  if (props.readonly) return
+
+  isDragging.value = true
+  event.preventDefault()
+
+  const handleMouseMove = (e: MouseEvent | TouchEvent) => {
+    if (!isDragging.value) return
+    updateSliderPosition(e)
+  }
+
+  const handleMouseUp = () => {
+    isDragging.value = false
+    document.removeEventListener('mousemove', handleMouseMove)
+    document.removeEventListener('mouseup', handleMouseUp)
+    document.removeEventListener('touchmove', handleMouseMove)
+    document.removeEventListener('touchend', handleMouseUp)
+  }
+
+  document.addEventListener('mousemove', handleMouseMove)
+  document.addEventListener('mouseup', handleMouseUp)
+  document.addEventListener('touchmove', handleMouseMove)
+  document.addEventListener('touchend', handleMouseUp)
+}
+
+const updateSliderPosition = (event: MouseEvent | TouchEvent) => {
+  const container = (event.target as HTMLElement).closest(
+    '.image-compare-container'
+  )
+  if (!container) return
+
+  const rect = container.getBoundingClientRect()
+  const clientX = 'touches' in event ? event.touches[0].clientX : event.clientX
+  const x = clientX - rect.left
+  const percentage = Math.max(0, Math.min(100, (x / rect.width) * 100))
+
+  sliderPosition.value = percentage
+}
+
+onUnmounted(() => {
+  isDragging.value = false
+})
+</script>

src/components/graph/vueWidgets/WidgetInputText.vue

@@ -0,0 +1,46 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <InputText
+      v-model="localValue"
+      v-bind="filteredProps"
+      :disabled="readonly"
+      @update:model-value="onChange"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import InputText from 'primevue/inputtext'
+import { computed } from 'vue'
+
+import { useStringWidgetValue } from '@/composables/graph/useWidgetValue'
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  INPUT_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const props = defineProps<{
+  widget: SimplifiedWidget<string>
+  modelValue: string
+  readonly?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+// Use the composable for consistent widget value handling
+const { localValue, onChange } = useStringWidgetValue(
+  props.widget,
+  props.modelValue,
+  emit
+)
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, INPUT_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetMultiSelect.vue

@@ -0,0 +1,36 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <MultiSelect v-model="value" v-bind="filteredProps" :disabled="readonly" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import MultiSelect from 'primevue/multiselect'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  PANEL_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const value = defineModel<any[]>({ required: true })
+
+const props = defineProps<{
+  widget: SimplifiedWidget<any[]>
+  readonly?: boolean
+}>()
+
+// MultiSelect specific excluded props include overlay styles
+const MULTISELECT_EXCLUDED_PROPS = [
+  ...PANEL_EXCLUDED_PROPS,
+  'overlayStyle'
+] as const
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, MULTISELECT_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetSelect.vue

@@ -0,0 +1,59 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <Select
+      v-model="localValue"
+      :options="selectOptions"
+      v-bind="filteredProps"
+      :disabled="readonly"
+      @update:model-value="onChange"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import Select from 'primevue/select'
+import { computed } from 'vue'
+
+import { useWidgetValue } from '@/composables/graph/useWidgetValue'
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  PANEL_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const props = defineProps<{
+  widget: SimplifiedWidget<string | number | undefined>
+  modelValue: string | number | undefined
+  readonly?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string | number | undefined]
+}>()
+
+// Use the composable for consistent widget value handling
+const { localValue, onChange } = useWidgetValue({
+  widget: props.widget,
+  modelValue: props.modelValue,
+  defaultValue: props.widget.options?.values?.[0] || '',
+  emit
+})
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, PANEL_EXCLUDED_PROPS)
+)
+
+// Extract select options from widget options
+const selectOptions = computed(() => {
+  const options = props.widget.options
+
+  if (options?.values && Array.isArray(options.values)) {
+    return options.values
+  }
+
+  return []
+})
+</script>

src/components/graph/vueWidgets/WidgetSelectButton.vue

@@ -0,0 +1,30 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <SelectButton v-model="value" v-bind="filteredProps" :disabled="readonly" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import SelectButton from 'primevue/selectbutton'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  STANDARD_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const value = defineModel<any>({ required: true })
+
+const props = defineProps<{
+  widget: SimplifiedWidget<any>
+  readonly?: boolean
+}>()
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, STANDARD_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetSlider.vue

@@ -0,0 +1,46 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <Slider
+      v-model="localValue"
+      v-bind="filteredProps"
+      :disabled="readonly"
+      @update:model-value="onChange"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import Slider from 'primevue/slider'
+import { computed } from 'vue'
+
+import { useNumberWidgetValue } from '@/composables/graph/useWidgetValue'
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  STANDARD_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const props = defineProps<{
+  widget: SimplifiedWidget<number>
+  modelValue: number
+  readonly?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: number]
+}>()
+
+// Use the composable for consistent widget value handling
+const { localValue, onChange } = useNumberWidgetValue(
+  props.widget,
+  props.modelValue,
+  emit
+)
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, STANDARD_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetTextarea.vue

@@ -0,0 +1,30 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <Textarea v-model="value" v-bind="filteredProps" :disabled="readonly" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import Textarea from 'primevue/textarea'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  INPUT_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const value = defineModel<string>({ required: true })
+
+const props = defineProps<{
+  widget: SimplifiedWidget<string>
+  readonly?: boolean
+}>()
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, INPUT_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetToggleSwitch.vue

@@ -0,0 +1,46 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <ToggleSwitch
+      v-model="localValue"
+      v-bind="filteredProps"
+      :disabled="readonly"
+      @update:model-value="onChange"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import ToggleSwitch from 'primevue/toggleswitch'
+import { computed } from 'vue'
+
+import { useBooleanWidgetValue } from '@/composables/graph/useWidgetValue'
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  STANDARD_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const props = defineProps<{
+  widget: SimplifiedWidget<boolean>
+  modelValue: boolean
+  readonly?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+}>()
+
+// Use the composable for consistent widget value handling
+const { localValue, onChange } = useBooleanWidgetValue(
+  props.widget,
+  props.modelValue,
+  emit
+)
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, STANDARD_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/WidgetTreeSelect.vue

@@ -0,0 +1,37 @@
+<template>
+  <div class="flex flex-col gap-1">
+    <label v-if="widget.name" class="text-sm opacity-80">{{
+      widget.name
+    }}</label>
+    <TreeSelect v-model="value" v-bind="filteredProps" :disabled="readonly" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import TreeSelect from 'primevue/treeselect'
+import { computed } from 'vue'
+
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+import {
+  PANEL_EXCLUDED_PROPS,
+  filterWidgetProps
+} from '@/utils/widgetPropFilter'
+
+const value = defineModel<any>({ required: true })
+
+const props = defineProps<{
+  widget: SimplifiedWidget<any>
+  readonly?: boolean
+}>()
+
+// TreeSelect specific excluded props
+const TREE_SELECT_EXCLUDED_PROPS = [
+  ...PANEL_EXCLUDED_PROPS,
+  'inputClass',
+  'inputStyle'
+] as const
+
+const filteredProps = computed(() =>
+  filterWidgetProps(props.widget.options, TREE_SELECT_EXCLUDED_PROPS)
+)
+</script>

src/components/graph/vueWidgets/widgetRegistry.ts

@@ -0,0 +1,80 @@
+/**
+ * Widget type registry and component mapping for Vue-based widgets
+ */
+import type { Component } from 'vue'
+
+// Component imports
+import WidgetButton from './WidgetButton.vue'
+import WidgetChart from './WidgetChart.vue'
+import WidgetColorPicker from './WidgetColorPicker.vue'
+import WidgetFileUpload from './WidgetFileUpload.vue'
+import WidgetGalleria from './WidgetGalleria.vue'
+import WidgetImage from './WidgetImage.vue'
+import WidgetImageCompare from './WidgetImageCompare.vue'
+import WidgetInputText from './WidgetInputText.vue'
+import WidgetMultiSelect from './WidgetMultiSelect.vue'
+import WidgetSelect from './WidgetSelect.vue'
+import WidgetSelectButton from './WidgetSelectButton.vue'
+import WidgetSlider from './WidgetSlider.vue'
+import WidgetTextarea from './WidgetTextarea.vue'
+import WidgetToggleSwitch from './WidgetToggleSwitch.vue'
+import WidgetTreeSelect from './WidgetTreeSelect.vue'
+
+/**
+ * Enum of all available widget types
+ */
+export enum WidgetType {
+  BUTTON = 'BUTTON',
+  STRING = 'STRING',
+  INT = 'INT',
+  FLOAT = 'FLOAT',
+  NUMBER = 'NUMBER',
+  BOOLEAN = 'BOOLEAN',
+  COMBO = 'COMBO',
+  COLOR = 'COLOR',
+  MULTISELECT = 'MULTISELECT',
+  SELECTBUTTON = 'SELECTBUTTON',
+  SLIDER = 'SLIDER',
+  TEXTAREA = 'TEXTAREA',
+  TOGGLESWITCH = 'TOGGLESWITCH',
+  CHART = 'CHART',
+  IMAGE = 'IMAGE',
+  IMAGECOMPARE = 'IMAGECOMPARE',
+  GALLERIA = 'GALLERIA',
+  FILEUPLOAD = 'FILEUPLOAD',
+  TREESELECT = 'TREESELECT'
+}
+
+/**
+ * Maps widget types to their corresponding Vue components
+ * Components will be added as they are implemented
+ */
+export const widgetTypeToComponent: Record<string, Component> = {
+  // Components will be uncommented as they are implemented
+  [WidgetType.BUTTON]: WidgetButton,
+  [WidgetType.STRING]: WidgetInputText,
+  [WidgetType.INT]: WidgetSlider,
+  [WidgetType.FLOAT]: WidgetSlider,
+  [WidgetType.NUMBER]: WidgetSlider, // For compatibility
+  [WidgetType.BOOLEAN]: WidgetToggleSwitch,
+  [WidgetType.COMBO]: WidgetSelect,
+  [WidgetType.COLOR]: WidgetColorPicker,
+  [WidgetType.MULTISELECT]: WidgetMultiSelect,
+  [WidgetType.SELECTBUTTON]: WidgetSelectButton,
+  [WidgetType.SLIDER]: WidgetSlider,
+  [WidgetType.TEXTAREA]: WidgetTextarea,
+  [WidgetType.TOGGLESWITCH]: WidgetToggleSwitch,
+  [WidgetType.CHART]: WidgetChart,
+  [WidgetType.IMAGE]: WidgetImage,
+  [WidgetType.IMAGECOMPARE]: WidgetImageCompare,
+  [WidgetType.GALLERIA]: WidgetGalleria,
+  [WidgetType.FILEUPLOAD]: WidgetFileUpload,
+  [WidgetType.TREESELECT]: WidgetTreeSelect
+}
+
+/**
+ * Helper function to get widget component by type
+ */
+export function getWidgetComponent(type: string): Component | undefined {
+  return widgetTypeToComponent[type]
+}

src/composables/element/useTransformState.ts

@@ -0,0 +1,241 @@
+/**
+ * Composable for managing transform state synchronized with LiteGraph canvas
+ *
+ * This composable is a critical part of the hybrid rendering architecture that
+ * allows Vue components to render in perfect alignment with LiteGraph's canvas.
+ *
+ * ## Core Concept
+ *
+ * LiteGraph uses a canvas for rendering connections, grid, and handling interactions.
+ * Vue components need to render nodes on top of this canvas. The challenge is
+ * synchronizing the coordinate systems:
+ *
+ * - LiteGraph: Uses canvas coordinates with its own transform matrix
+ * - Vue/DOM: Uses screen coordinates with CSS transforms
+ *
+ * ## Solution: Transform Container Pattern
+ *
+ * Instead of transforming individual nodes (O(n) complexity), we:
+ * 1. Mirror LiteGraph's transform matrix to a single CSS container
+ * 2. Place all Vue nodes as children with simple absolute positioning
+ * 3. Achieve O(1) transform updates regardless of node count
+ *
+ * ## Coordinate Systems
+ *
+ * - **Canvas coordinates**: LiteGraph's internal coordinate system
+ * - **Screen coordinates**: Browser's viewport coordinate system
+ * - **Transform sync**: camera.x/y/z mirrors canvas.ds.offset/scale
+ *
+ * ## Performance Benefits
+ *
+ * - GPU acceleration via CSS transforms
+ * - No layout thrashing (only transform changes)
+ * - Efficient viewport culling calculations
+ * - Scales to 1000+ nodes while maintaining 60 FPS
+ *
+ * @example
+ * ```typescript
+ * const { camera, transformStyle, canvasToScreen } = useTransformState()
+ *
+ * // In template
+ * <div :style="transformStyle">
+ *   <NodeComponent
+ *     v-for="node in nodes"
+ *     :style="{ left: node.x + 'px', top: node.y + 'px' }"
+ *   />
+ * </div>
+ *
+ * // Convert coordinates
+ * const screenPos = canvasToScreen({ x: nodeX, y: nodeY })
+ * ```
+ */
+import type { LGraphCanvas } from '@comfyorg/litegraph'
+import { computed, reactive, readonly } from 'vue'
+
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface Camera {
+  x: number
+  y: number
+  z: number // scale/zoom
+}
+
+export const useTransformState = () => {
+  // Reactive state mirroring LiteGraph's canvas transform
+  const camera = reactive<Camera>({
+    x: 0,
+    y: 0,
+    z: 1
+  })
+
+  // Computed transform string for CSS
+  const transformStyle = computed(() => ({
+    transform: `scale(${camera.z}) translate(${camera.x}px, ${camera.y}px)`,
+    transformOrigin: '0 0'
+  }))
+
+  /**
+   * Synchronizes Vue's reactive camera state with LiteGraph's canvas transform
+   *
+   * Called every frame via RAF to ensure Vue components stay aligned with canvas.
+   * This is the heart of the hybrid rendering system - it bridges the gap between
+   * LiteGraph's canvas transforms and Vue's reactive system.
+   *
+   * @param canvas - LiteGraph canvas instance with DragAndScale (ds) transform state
+   */
+  const syncWithCanvas = (canvas: LGraphCanvas) => {
+    if (!canvas || !canvas.ds) return
+
+    // Mirror LiteGraph's transform state to Vue's reactive state
+    // ds.offset = pan offset, ds.scale = zoom level
+    camera.x = canvas.ds.offset[0]
+    camera.y = canvas.ds.offset[1]
+    camera.z = canvas.ds.scale || 1
+  }
+
+  /**
+   * Converts canvas coordinates to screen coordinates
+   *
+   * Applies the same transform that LiteGraph uses for rendering.
+   * Essential for positioning Vue components to align with canvas elements.
+   *
+   * Formula: screen = canvas * scale + offset
+   *
+   * @param point - Point in canvas coordinate system
+   * @returns Point in screen coordinate system
+   */
+  const canvasToScreen = (point: Point): Point => {
+    return {
+      x: point.x * camera.z + camera.x,
+      y: point.y * camera.z + camera.y
+    }
+  }
+
+  /**
+   * Converts screen coordinates to canvas coordinates
+   *
+   * Inverse of canvasToScreen. Useful for hit testing and converting
+   * mouse events back to canvas space.
+   *
+   * Formula: canvas = (screen - offset) / scale
+   *
+   * @param point - Point in screen coordinate system
+   * @returns Point in canvas coordinate system
+   */
+  const screenToCanvas = (point: Point): Point => {
+    return {
+      x: (point.x - camera.x) / camera.z,
+      y: (point.y - camera.y) / camera.z
+    }
+  }
+
+  // Get node's screen bounds for culling
+  const getNodeScreenBounds = (
+    pos: ArrayLike<number>,
+    size: ArrayLike<number>
+  ): DOMRect => {
+    const topLeft = canvasToScreen({ x: pos[0], y: pos[1] })
+    const width = size[0] * camera.z
+    const height = size[1] * camera.z
+
+    return new DOMRect(topLeft.x, topLeft.y, width, height)
+  }
+
+  // Helper: Calculate zoom-adjusted margin for viewport culling
+  const calculateAdjustedMargin = (baseMargin: number): number => {
+    if (camera.z < 0.1) return Math.min(baseMargin * 5, 2.0)
+    if (camera.z > 3.0) return Math.max(baseMargin * 0.5, 0.05)
+    return baseMargin
+  }
+
+  // Helper: Check if node is too small to be visible at current zoom
+  const isNodeTooSmall = (nodeSize: ArrayLike<number>): boolean => {
+    const nodeScreenSize = Math.max(nodeSize[0], nodeSize[1]) * camera.z
+    return nodeScreenSize < 4
+  }
+
+  // Helper: Calculate expanded viewport bounds with margin
+  const getExpandedViewportBounds = (
+    viewport: { width: number; height: number },
+    margin: number
+  ) => {
+    const marginX = viewport.width * margin
+    const marginY = viewport.height * margin
+    return {
+      left: -marginX,
+      right: viewport.width + marginX,
+      top: -marginY,
+      bottom: viewport.height + marginY
+    }
+  }
+
+  // Helper: Test if node intersects with viewport bounds
+  const testViewportIntersection = (
+    screenPos: { x: number; y: number },
+    nodeSize: ArrayLike<number>,
+    bounds: { left: number; right: number; top: number; bottom: number }
+  ): boolean => {
+    const nodeRight = screenPos.x + nodeSize[0] * camera.z
+    const nodeBottom = screenPos.y + nodeSize[1] * camera.z
+
+    return !(
+      nodeRight < bounds.left ||
+      screenPos.x > bounds.right ||
+      nodeBottom < bounds.top ||
+      screenPos.y > bounds.bottom
+    )
+  }
+
+  // Check if node is within viewport with frustum and size-based culling
+  const isNodeInViewport = (
+    nodePos: ArrayLike<number>,
+    nodeSize: ArrayLike<number>,
+    viewport: { width: number; height: number },
+    margin: number = 0.2
+  ): boolean => {
+    // Early exit for tiny nodes
+    if (isNodeTooSmall(nodeSize)) return false
+
+    const screenPos = canvasToScreen({ x: nodePos[0], y: nodePos[1] })
+    const adjustedMargin = calculateAdjustedMargin(margin)
+    const bounds = getExpandedViewportBounds(viewport, adjustedMargin)
+
+    return testViewportIntersection(screenPos, nodeSize, bounds)
+  }
+
+  // Get viewport bounds in canvas coordinates (for spatial index queries)
+  const getViewportBounds = (
+    viewport: { width: number; height: number },
+    margin: number = 0.2
+  ) => {
+    const marginX = viewport.width * margin
+    const marginY = viewport.height * margin
+
+    const topLeft = screenToCanvas({ x: -marginX, y: -marginY })
+    const bottomRight = screenToCanvas({
+      x: viewport.width + marginX,
+      y: viewport.height + marginY
+    })
+
+    return {
+      x: topLeft.x,
+      y: topLeft.y,
+      width: bottomRight.x - topLeft.x,
+      height: bottomRight.y - topLeft.y
+    }
+  }
+
+  return {
+    camera: readonly(camera),
+    transformStyle,
+    syncWithCanvas,
+    canvasToScreen,
+    screenToCanvas,
+    getNodeScreenBounds,
+    isNodeInViewport,
+    getViewportBounds
+  }
+}

src/composables/graph/useCanvasTransformSync.ts

@@ -0,0 +1,114 @@
+import type { LGraphCanvas } from '@comfyorg/litegraph'
+import { onUnmounted, ref } from 'vue'
+
+export interface CanvasTransformSyncOptions {
+  /**
+   * Whether to automatically start syncing when canvas is available
+   * @default true
+   */
+  autoStart?: boolean
+}
+
+export interface CanvasTransformSyncCallbacks {
+  /**
+   * Called when sync starts
+   */
+  onStart?: () => void
+  /**
+   * Called after each sync update with timing information
+   */
+  onUpdate?: (duration: number) => void
+  /**
+   * Called when sync stops
+   */
+  onStop?: () => void
+}
+
+/**
+ * Manages requestAnimationFrame-based synchronization with LiteGraph canvas transforms.
+ *
+ * This composable provides a clean way to sync Vue transform state with LiteGraph canvas
+ * on every frame. It handles RAF lifecycle management, provides performance timing,
+ * and ensures proper cleanup.
+ *
+ * The sync function typically reads canvas.ds (draw state) properties like offset and scale
+ * to keep Vue components aligned with the canvas coordinate system.
+ *
+ * @example
+ * ```ts
+ * const { isActive, startSync, stopSync } = useCanvasTransformSync(
+ *   canvas,
+ *   (canvas) => syncWithCanvas(canvas),
+ *   {
+ *     onStart: () => emit('rafStatusChange', true),
+ *     onUpdate: (time) => emit('transformUpdate', time),
+ *     onStop: () => emit('rafStatusChange', false)
+ *   }
+ * )
+ * ```
+ */
+export function useCanvasTransformSync(
+  canvas: LGraphCanvas | undefined | null,
+  syncFn: (canvas: LGraphCanvas) => void,
+  callbacks: CanvasTransformSyncCallbacks = {},
+  options: CanvasTransformSyncOptions = {}
+) {
+  const { autoStart = true } = options
+  const { onStart, onUpdate, onStop } = callbacks
+
+  const isActive = ref(false)
+  let rafId: number | null = null
+
+  const startSync = () => {
+    if (isActive.value || !canvas) return
+
+    isActive.value = true
+    onStart?.()
+
+    const sync = () => {
+      if (!isActive.value || !canvas) return
+
+      try {
+        const startTime = performance.now()
+        syncFn(canvas)
+        const endTime = performance.now()
+
+        onUpdate?.(endTime - startTime)
+      } catch (error) {
+        console.warn('Canvas transform sync error:', error)
+      }
+
+      rafId = requestAnimationFrame(sync)
+    }
+
+    sync()
+  }
+
+  const stopSync = () => {
+    if (!isActive.value) return
+
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
+
+    isActive.value = false
+    onStop?.()
+  }
+
+  // Auto-start if canvas is available and autoStart is enabled
+  if (autoStart && canvas) {
+    startSync()
+  }
+
+  // Clean up on unmount
+  onUnmounted(() => {
+    stopSync()
+  })
+
+  return {
+    isActive,
+    startSync,
+    stopSync
+  }
+}

src/composables/graph/useGraphNodeManager.ts

@@ -0,0 +1,718 @@
+/**
+ * Vue node lifecycle management for LiteGraph integration
+ * Provides event-driven reactivity with performance optimizations
+ */
+import type { LGraph, LGraphNode } from '@comfyorg/litegraph'
+import { nextTick, reactive, readonly } from 'vue'
+
+import type { WidgetValue } from '@/types/simplifiedWidget'
+import type { SpatialIndexDebugInfo } from '@/types/spatialIndex'
+
+import { type Bounds, QuadTree } from '../../utils/spatial/QuadTree'
+
+export interface NodeState {
+  visible: boolean
+  dirty: boolean
+  lastUpdate: number
+  culled: boolean
+}
+
+export interface NodeMetadata {
+  lastRenderTime: number
+  cachedBounds: DOMRect | null
+  lodLevel: 'high' | 'medium' | 'low'
+  spatialIndex?: QuadTree<string>
+}
+
+export interface PerformanceMetrics {
+  fps: number
+  frameTime: number
+  updateTime: number
+  nodeCount: number
+  culledCount: number
+  callbackUpdateCount: number
+  rafUpdateCount: number
+  adaptiveQuality: boolean
+}
+
+export interface SafeWidgetData {
+  name: string
+  type: string
+  value: WidgetValue
+  options?: Record<string, unknown>
+  callback?: ((value: unknown) => void) | undefined
+}
+
+export interface VueNodeData {
+  id: string
+  title: string
+  type: string
+  mode: number
+  selected: boolean
+  executing: boolean
+  widgets?: SafeWidgetData[]
+  inputs?: unknown[]
+  outputs?: unknown[]
+}
+
+export interface SpatialMetrics {
+  queryTime: number
+  nodesInIndex: number
+}
+
+export interface GraphNodeManager {
+  // Reactive state - safe data extracted from LiteGraph nodes
+  vueNodeData: ReadonlyMap<string, VueNodeData>
+  nodeState: ReadonlyMap<string, NodeState>
+  nodePositions: ReadonlyMap<string, { x: number; y: number }>
+  nodeSizes: ReadonlyMap<string, { width: number; height: number }>
+
+  // Access to original LiteGraph nodes (non-reactive)
+  getNode(id: string): LGraphNode | undefined
+
+  // Lifecycle methods
+  setupEventListeners(): () => void
+  cleanup(): void
+
+  // Update methods
+  scheduleUpdate(
+    nodeId?: string,
+    priority?: 'critical' | 'normal' | 'low'
+  ): void
+  forceSync(): void
+  detectChangesInRAF(): void
+
+  // Spatial queries
+  getVisibleNodeIds(viewportBounds: Bounds): Set<string>
+
+  // Performance
+  performanceMetrics: PerformanceMetrics
+  spatialMetrics: SpatialMetrics
+
+  // Debug
+  getSpatialIndexDebugInfo(): SpatialIndexDebugInfo | null
+}
+
+export const useGraphNodeManager = (graph: LGraph): GraphNodeManager => {
+  // Safe reactive data extracted from LiteGraph nodes
+  const vueNodeData = reactive(new Map<string, VueNodeData>())
+  const nodeState = reactive(new Map<string, NodeState>())
+  const nodePositions = reactive(new Map<string, { x: number; y: number }>())
+  const nodeSizes = reactive(
+    new Map<string, { width: number; height: number }>()
+  )
+
+  // Non-reactive storage for original LiteGraph nodes
+  const nodeRefs = new Map<string, LGraphNode>()
+
+  // WeakMap for heavy data that auto-GCs when nodes are removed
+  const nodeMetadata = new WeakMap<LGraphNode, NodeMetadata>()
+
+  // Performance tracking
+  const performanceMetrics = reactive<PerformanceMetrics>({
+    fps: 0,
+    frameTime: 0,
+    updateTime: 0,
+    nodeCount: 0,
+    culledCount: 0,
+    callbackUpdateCount: 0,
+    rafUpdateCount: 0,
+    adaptiveQuality: false
+  })
+
+  // Spatial indexing using QuadTree
+  const spatialIndex = new QuadTree<string>(
+    { x: -10000, y: -10000, width: 20000, height: 20000 },
+    { maxDepth: 6, maxItemsPerNode: 4 }
+  )
+  let lastSpatialQueryTime = 0
+
+  // Spatial metrics
+  const spatialMetrics = reactive<SpatialMetrics>({
+    queryTime: 0,
+    nodesInIndex: 0
+  })
+
+  // Update batching
+  const pendingUpdates = new Set<string>()
+  const criticalUpdates = new Set<string>()
+  const lowPriorityUpdates = new Set<string>()
+  let updateScheduled = false
+  let batchTimeoutId: number | null = null
+
+  // Change detection state
+  const lastNodesSnapshot = new Map<
+    string,
+    { pos: [number, number]; size: [number, number] }
+  >()
+
+  const attachMetadata = (node: LGraphNode) => {
+    nodeMetadata.set(node, {
+      lastRenderTime: performance.now(),
+      cachedBounds: null,
+      lodLevel: 'high',
+      spatialIndex: undefined
+    })
+  }
+
+  // Extract safe data from LiteGraph node for Vue consumption
+  const extractVueNodeData = (node: LGraphNode): VueNodeData => {
+    // Extract safe widget data
+    const safeWidgets = node.widgets?.map((widget) => {
+      try {
+        // TODO: Use widget.getReactiveData() once TypeScript types are updated
+        let value = widget.value
+
+        // For combo widgets, if value is undefined, use the first option as default
+        if (
+          value === undefined &&
+          widget.type === 'combo' &&
+          widget.options?.values &&
+          Array.isArray(widget.options.values) &&
+          widget.options.values.length > 0
+        ) {
+          value = widget.options.values[0]
+        }
+
+        return {
+          name: widget.name,
+          type: widget.type,
+          value: value,
+          options: widget.options ? { ...widget.options } : undefined,
+          callback: widget.callback
+        }
+      } catch (error) {
+        return {
+          name: widget.name || 'unknown',
+          type: widget.type || 'text',
+          value: undefined, // Already a valid WidgetValue
+          options: undefined,
+          callback: undefined
+        }
+      }
+    })
+
+    return {
+      id: String(node.id),
+      title: node.title || 'Untitled',
+      type: node.type || 'Unknown',
+      mode: node.mode || 0,
+      selected: node.selected || false,
+      executing: false, // Will be updated separately based on execution state
+      widgets: safeWidgets,
+      inputs: node.inputs ? [...node.inputs] : undefined,
+      outputs: node.outputs ? [...node.outputs] : undefined
+    }
+  }
+
+  // Get access to original LiteGraph node (non-reactive)
+  const getNode = (id: string): LGraphNode | undefined => {
+    return nodeRefs.get(id)
+  }
+
+  /**
+   * Validates that a value is a valid WidgetValue type
+   */
+  const validateWidgetValue = (value: unknown): WidgetValue => {
+    if (value === null || value === undefined || value === void 0) {
+      return undefined
+    }
+    if (
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean'
+    ) {
+      return value
+    }
+    if (typeof value === 'object') {
+      // Check if it's a File array
+      if (Array.isArray(value) && value.every((item) => item instanceof File)) {
+        return value as File[]
+      }
+      // Otherwise it's a generic object
+      return value as object
+    }
+    // If none of the above, return undefined
+    console.warn(`Invalid widget value type: ${typeof value}`, value)
+    return undefined
+  }
+
+  /**
+   * Updates Vue state when widget values change
+   */
+  const updateVueWidgetState = (
+    nodeId: string,
+    widgetName: string,
+    value: unknown
+  ): void => {
+    try {
+      const currentData = vueNodeData.get(nodeId)
+      if (!currentData?.widgets) return
+
+      const updatedWidgets = currentData.widgets.map((w) =>
+        w.name === widgetName ? { ...w, value: validateWidgetValue(value) } : w
+      )
+      vueNodeData.set(nodeId, {
+        ...currentData,
+        widgets: updatedWidgets
+      })
+      performanceMetrics.callbackUpdateCount++
+    } catch (error) {
+      // Ignore widget update errors to prevent cascade failures
+    }
+  }
+
+  /**
+   * Creates a wrapped callback for a widget that maintains LiteGraph/Vue sync
+   */
+  const createWrappedWidgetCallback = (
+    widget: { value?: unknown; name: string }, // LiteGraph widget with minimal typing
+    originalCallback: ((value: unknown) => void) | undefined,
+    nodeId: string
+  ) => {
+    return (value: unknown) => {
+      // 1. Update the widget value in LiteGraph (critical for LiteGraph state)
+      // Validate that the value is of an acceptable type
+      if (
+        value !== null &&
+        value !== undefined &&
+        typeof value !== 'string' &&
+        typeof value !== 'number' &&
+        typeof value !== 'boolean' &&
+        typeof value !== 'object'
+      ) {
+        console.warn(`Invalid widget value type: ${typeof value}`)
+        return
+      }
+      widget.value = value
+
+      // 2. Call the original callback if it exists
+      if (originalCallback) {
+        originalCallback.call(widget, value)
+      }
+
+      // 3. Update Vue state to maintain synchronization
+      updateVueWidgetState(nodeId, widget.name, value)
+    }
+  }
+
+  /**
+   * Sets up widget callbacks for a node - now with reduced nesting
+   */
+  const setupNodeWidgetCallbacks = (node: LGraphNode) => {
+    if (!node.widgets) return
+
+    const nodeId = String(node.id)
+
+    node.widgets.forEach((widget) => {
+      const originalCallback = widget.callback
+      widget.callback = createWrappedWidgetCallback(
+        widget,
+        originalCallback,
+        nodeId
+      )
+    })
+  }
+
+  // Uncomment when needed for future features
+  // const getNodeMetadata = (node: LGraphNode): NodeMetadata => {
+  //   let metadata = nodeMetadata.get(node)
+  //   if (!metadata) {
+  //     attachMetadata(node)
+  //     metadata = nodeMetadata.get(node)!
+  //   }
+  //   return metadata
+  // }
+
+  const scheduleUpdate = (
+    nodeId?: string,
+    priority: 'critical' | 'normal' | 'low' = 'normal'
+  ) => {
+    if (nodeId) {
+      const state = nodeState.get(nodeId)
+      if (state) state.dirty = true
+
+      // Priority queuing
+      if (priority === 'critical') {
+        criticalUpdates.add(nodeId)
+        flush() // Immediate flush for critical updates
+        return
+      } else if (priority === 'low') {
+        lowPriorityUpdates.add(nodeId)
+      } else {
+        pendingUpdates.add(nodeId)
+      }
+    }
+
+    if (!updateScheduled) {
+      updateScheduled = true
+
+      // Adaptive batching strategy
+      if (pendingUpdates.size > 10) {
+        // Many updates - batch in nextTick
+        void nextTick(() => flush())
+      } else {
+        // Few updates - small delay for more batching
+        batchTimeoutId = window.setTimeout(() => flush(), 4)
+      }
+    }
+  }
+
+  const flush = () => {
+    const startTime = performance.now()
+
+    if (batchTimeoutId !== null) {
+      clearTimeout(batchTimeoutId)
+      batchTimeoutId = null
+    }
+
+    // Clear all pending updates
+    criticalUpdates.clear()
+    pendingUpdates.clear()
+    lowPriorityUpdates.clear()
+    updateScheduled = false
+
+    // Sync with graph state
+    syncWithGraph()
+
+    const endTime = performance.now()
+    performanceMetrics.updateTime = endTime - startTime
+  }
+
+  const syncWithGraph = () => {
+    if (!graph?._nodes) return
+
+    const currentNodes = new Set(graph._nodes.map((n) => String(n.id)))
+
+    // Remove deleted nodes
+    for (const id of Array.from(vueNodeData.keys())) {
+      if (!currentNodes.has(id)) {
+        nodeRefs.delete(id)
+        vueNodeData.delete(id)
+        nodeState.delete(id)
+        nodePositions.delete(id)
+        nodeSizes.delete(id)
+        lastNodesSnapshot.delete(id)
+        spatialIndex.remove(id)
+      }
+    }
+
+    // Add/update existing nodes
+    graph._nodes.forEach((node) => {
+      const id = String(node.id)
+
+      // Store non-reactive reference
+      nodeRefs.set(id, node)
+
+      // Set up widget callbacks BEFORE extracting data (critical order)
+      setupNodeWidgetCallbacks(node)
+
+      // Extract and store safe data for Vue
+      vueNodeData.set(id, extractVueNodeData(node))
+
+      if (!nodeState.has(id)) {
+        nodeState.set(id, {
+          visible: true,
+          dirty: false,
+          lastUpdate: performance.now(),
+          culled: false
+        })
+        nodePositions.set(id, { x: node.pos[0], y: node.pos[1] })
+        nodeSizes.set(id, { width: node.size[0], height: node.size[1] })
+        attachMetadata(node)
+
+        // Add to spatial index
+        const bounds: Bounds = {
+          x: node.pos[0],
+          y: node.pos[1],
+          width: node.size[0],
+          height: node.size[1]
+        }
+        spatialIndex.insert(id, bounds, id)
+      }
+    })
+
+    // Update performance metrics
+    performanceMetrics.nodeCount = vueNodeData.size
+    performanceMetrics.culledCount = Array.from(nodeState.values()).filter(
+      (s) => s.culled
+    ).length
+  }
+
+  // Most performant: Direct position sync without re-setting entire node
+  // Query visible nodes using QuadTree spatial index
+  const getVisibleNodeIds = (viewportBounds: Bounds): Set<string> => {
+    const startTime = performance.now()
+
+    // Use QuadTree for fast spatial query
+    const results: string[] = spatialIndex.query(viewportBounds)
+    const visibleIds = new Set(results)
+
+    lastSpatialQueryTime = performance.now() - startTime
+    spatialMetrics.queryTime = lastSpatialQueryTime
+
+    return visibleIds
+  }
+
+  /**
+   * Detects position changes for a single node and updates reactive state
+   */
+  const detectPositionChanges = (node: LGraphNode, id: string): boolean => {
+    const currentPos = nodePositions.get(id)
+
+    if (
+      !currentPos ||
+      currentPos.x !== node.pos[0] ||
+      currentPos.y !== node.pos[1]
+    ) {
+      nodePositions.set(id, { x: node.pos[0], y: node.pos[1] })
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Detects size changes for a single node and updates reactive state
+   */
+  const detectSizeChanges = (node: LGraphNode, id: string): boolean => {
+    const currentSize = nodeSizes.get(id)
+
+    if (
+      !currentSize ||
+      currentSize.width !== node.size[0] ||
+      currentSize.height !== node.size[1]
+    ) {
+      nodeSizes.set(id, { width: node.size[0], height: node.size[1] })
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Updates spatial index for a node if bounds changed
+   */
+  const updateSpatialIndex = (node: LGraphNode, id: string): void => {
+    const bounds: Bounds = {
+      x: node.pos[0],
+      y: node.pos[1],
+      width: node.size[0],
+      height: node.size[1]
+    }
+    spatialIndex.update(id, bounds)
+  }
+
+  /**
+   * Updates performance metrics after change detection
+   */
+  const updatePerformanceMetrics = (
+    startTime: number,
+    positionUpdates: number,
+    sizeUpdates: number
+  ): void => {
+    const endTime = performance.now()
+    performanceMetrics.updateTime = endTime - startTime
+    performanceMetrics.nodeCount = vueNodeData.size
+    performanceMetrics.culledCount = Array.from(nodeState.values()).filter(
+      (state) => state.culled
+    ).length
+    spatialMetrics.nodesInIndex = spatialIndex.size
+
+    if (positionUpdates > 0 || sizeUpdates > 0) {
+      performanceMetrics.rafUpdateCount++
+    }
+  }
+
+  /**
+   * Main RAF change detection function - now simplified with extracted helpers
+   */
+  const detectChangesInRAF = () => {
+    const startTime = performance.now()
+
+    if (!graph?._nodes) return
+
+    let positionUpdates = 0
+    let sizeUpdates = 0
+
+    // Process each node for changes
+    for (const node of graph._nodes) {
+      const id = String(node.id)
+
+      const posChanged = detectPositionChanges(node, id)
+      const sizeChanged = detectSizeChanges(node, id)
+
+      if (posChanged) positionUpdates++
+      if (sizeChanged) sizeUpdates++
+
+      // Update spatial index if geometry changed
+      if (posChanged || sizeChanged) {
+        updateSpatialIndex(node, id)
+      }
+    }
+
+    updatePerformanceMetrics(startTime, positionUpdates, sizeUpdates)
+  }
+
+  /**
+   * Handles node addition to the graph - sets up Vue state and spatial indexing
+   */
+  const handleNodeAdded = (
+    node: LGraphNode,
+    originalCallback?: (node: LGraphNode) => void
+  ) => {
+    const id = String(node.id)
+
+    // Store non-reactive reference to original node
+    nodeRefs.set(id, node)
+
+    // Set up widget callbacks BEFORE extracting data (critical order)
+    setupNodeWidgetCallbacks(node)
+
+    // Extract safe data for Vue (now with proper callbacks)
+    vueNodeData.set(id, extractVueNodeData(node))
+
+    // Set up reactive tracking state
+    nodeState.set(id, {
+      visible: true,
+      dirty: false,
+      lastUpdate: performance.now(),
+      culled: false
+    })
+    nodePositions.set(id, { x: node.pos[0], y: node.pos[1] })
+    nodeSizes.set(id, { width: node.size[0], height: node.size[1] })
+    attachMetadata(node)
+
+    // Add to spatial index for viewport culling
+    const bounds: Bounds = {
+      x: node.pos[0],
+      y: node.pos[1],
+      width: node.size[0],
+      height: node.size[1]
+    }
+    spatialIndex.insert(id, bounds, id)
+
+    // Call original callback if provided
+    if (originalCallback) {
+      void originalCallback(node)
+    }
+  }
+
+  /**
+   * Handles node removal from the graph - cleans up all references
+   */
+  const handleNodeRemoved = (
+    node: LGraphNode,
+    originalCallback?: (node: LGraphNode) => void
+  ) => {
+    const id = String(node.id)
+
+    // Remove from spatial index
+    spatialIndex.remove(id)
+
+    // Clean up all tracking references
+    nodeRefs.delete(id)
+    vueNodeData.delete(id)
+    nodeState.delete(id)
+    nodePositions.delete(id)
+    nodeSizes.delete(id)
+    lastNodesSnapshot.delete(id)
+
+    // Call original callback if provided
+    if (originalCallback) {
+      originalCallback(node)
+    }
+  }
+
+  /**
+   * Creates cleanup function for event listeners and state
+   */
+  const createCleanupFunction = (
+    originalOnNodeAdded: ((node: LGraphNode) => void) | undefined,
+    originalOnNodeRemoved: ((node: LGraphNode) => void) | undefined
+  ) => {
+    return () => {
+      // Restore original callbacks
+      graph.onNodeAdded = originalOnNodeAdded || undefined
+      graph.onNodeRemoved = originalOnNodeRemoved || undefined
+
+      // Clear pending updates
+      if (batchTimeoutId !== null) {
+        clearTimeout(batchTimeoutId)
+        batchTimeoutId = null
+      }
+
+      // Clear all state maps
+      nodeRefs.clear()
+      vueNodeData.clear()
+      nodeState.clear()
+      nodePositions.clear()
+      nodeSizes.clear()
+      lastNodesSnapshot.clear()
+      pendingUpdates.clear()
+      criticalUpdates.clear()
+      lowPriorityUpdates.clear()
+      spatialIndex.clear()
+    }
+  }
+
+  /**
+   * Sets up event listeners - now simplified with extracted handlers
+   */
+  const setupEventListeners = (): (() => void) => {
+    // Store original callbacks
+    const originalOnNodeAdded = graph.onNodeAdded
+    const originalOnNodeRemoved = graph.onNodeRemoved
+
+    // Set up graph event handlers
+    graph.onNodeAdded = (node: LGraphNode) => {
+      handleNodeAdded(node, originalOnNodeAdded)
+    }
+
+    graph.onNodeRemoved = (node: LGraphNode) => {
+      handleNodeRemoved(node, originalOnNodeRemoved)
+    }
+
+    // Initialize state
+    syncWithGraph()
+
+    // Return cleanup function
+    return createCleanupFunction(
+      originalOnNodeAdded || undefined,
+      originalOnNodeRemoved || undefined
+    )
+  }
+
+  // Set up event listeners immediately
+  const cleanup = setupEventListeners()
+
+  // Process any existing nodes after event listeners are set up
+  if (graph._nodes && graph._nodes.length > 0) {
+    graph._nodes.forEach((node: LGraphNode) => {
+      if (graph.onNodeAdded) {
+        graph.onNodeAdded(node)
+      }
+    })
+  }
+
+  return {
+    vueNodeData: readonly(vueNodeData) as ReadonlyMap<string, VueNodeData>,
+    nodeState: readonly(nodeState) as ReadonlyMap<string, NodeState>,
+    nodePositions: readonly(nodePositions) as ReadonlyMap<
+      string,
+      { x: number; y: number }
+    >,
+    nodeSizes: readonly(nodeSizes) as ReadonlyMap<
+      string,
+      { width: number; height: number }
+    >,
+    getNode,
+    setupEventListeners,
+    cleanup,
+    scheduleUpdate,
+    forceSync: syncWithGraph,
+    detectChangesInRAF,
+    getVisibleNodeIds,
+    performanceMetrics,
+    spatialMetrics: readonly(spatialMetrics),
+    getSpatialIndexDebugInfo: () => spatialIndex.getDebugInfo()
+  }
+}

src/composables/graph/useLOD.ts

@@ -0,0 +1,186 @@
+/**
+ * Level of Detail (LOD) composable for Vue-based node rendering
+ *
+ * Provides dynamic quality adjustment based on zoom level to maintain
+ * performance with large node graphs. Uses zoom thresholds to determine
+ * how much detail to render for each node component.
+ *
+ * ## LOD Levels
+ *
+ * - **FULL** (zoom > 0.8): Complete rendering with all widgets, slots, and content
+ * - **REDUCED** (0.4 < zoom <= 0.8): Essential widgets only, simplified slots
+ * - **MINIMAL** (zoom <= 0.4): Title only, no widgets or slots
+ *
+ * ## Performance Benefits
+ *
+ * - Reduces DOM element count by up to 80% at low zoom levels
+ * - Minimizes layout calculations and paint operations
+ * - Enables smooth performance with 1000+ nodes
+ * - Maintains visual fidelity when detail is actually visible
+ *
+ * @example
+ * ```typescript
+ * const { lodLevel, shouldRenderWidgets, shouldRenderSlots } = useLOD(zoomRef)
+ *
+ * // In template
+ * <NodeWidgets v-if="shouldRenderWidgets" />
+ * <NodeSlots v-if="shouldRenderSlots" />
+ * ```
+ */
+import { type Ref, computed, readonly } from 'vue'
+
+export enum LODLevel {
+  MINIMAL = 'minimal', // zoom <= 0.4
+  REDUCED = 'reduced', // 0.4 < zoom <= 0.8
+  FULL = 'full' // zoom > 0.8
+}
+
+export interface LODConfig {
+  renderWidgets: boolean
+  renderSlots: boolean
+  renderContent: boolean
+  renderSlotLabels: boolean
+  renderWidgetLabels: boolean
+  cssClass: string
+}
+
+// LOD configuration for each level
+const LOD_CONFIGS: Record<LODLevel, LODConfig> = {
+  [LODLevel.FULL]: {
+    renderWidgets: true,
+    renderSlots: true,
+    renderContent: true,
+    renderSlotLabels: true,
+    renderWidgetLabels: true,
+    cssClass: 'lg-node--lod-full'
+  },
+  [LODLevel.REDUCED]: {
+    renderWidgets: true,
+    renderSlots: true,
+    renderContent: false,
+    renderSlotLabels: false,
+    renderWidgetLabels: false,
+    cssClass: 'lg-node--lod-reduced'
+  },
+  [LODLevel.MINIMAL]: {
+    renderWidgets: false,
+    renderSlots: false,
+    renderContent: false,
+    renderSlotLabels: false,
+    renderWidgetLabels: false,
+    cssClass: 'lg-node--lod-minimal'
+  }
+}
+
+/**
+ * Create LOD (Level of Detail) state based on zoom level
+ *
+ * @param zoomRef - Reactive reference to current zoom level (camera.z)
+ * @returns LOD state and configuration
+ */
+export function useLOD(zoomRef: Ref<number>) {
+  // Continuous LOD score (0-1) for smooth transitions
+  const lodScore = computed(() => {
+    const zoom = zoomRef.value
+    return Math.max(0, Math.min(1, zoom))
+  })
+
+  // Determine current LOD level based on zoom
+  const lodLevel = computed<LODLevel>(() => {
+    const zoom = zoomRef.value
+
+    if (zoom > 0.8) return LODLevel.FULL
+    if (zoom > 0.4) return LODLevel.REDUCED
+    return LODLevel.MINIMAL
+  })
+
+  // Get configuration for current LOD level
+  const lodConfig = computed<LODConfig>(() => LOD_CONFIGS[lodLevel.value])
+
+  // Convenience computed properties for common rendering decisions
+  const shouldRenderWidgets = computed(() => lodConfig.value.renderWidgets)
+  const shouldRenderSlots = computed(() => lodConfig.value.renderSlots)
+  const shouldRenderContent = computed(() => lodConfig.value.renderContent)
+  const shouldRenderSlotLabels = computed(
+    () => lodConfig.value.renderSlotLabels
+  )
+  const shouldRenderWidgetLabels = computed(
+    () => lodConfig.value.renderWidgetLabels
+  )
+
+  // CSS class for styling based on LOD level
+  const lodCssClass = computed(() => lodConfig.value.cssClass)
+
+  // Get essential widgets for reduced LOD (only interactive controls)
+  const getEssentialWidgets = (widgets: unknown[]): unknown[] => {
+    if (lodLevel.value === LODLevel.FULL) return widgets
+    if (lodLevel.value === LODLevel.MINIMAL) return []
+
+    // For reduced LOD, filter to essential widget types only
+    return widgets.filter((widget: any) => {
+      const type = widget?.type?.toLowerCase()
+      return [
+        'combo',
+        'select',
+        'toggle',
+        'boolean',
+        'slider',
+        'number'
+      ].includes(type)
+    })
+  }
+
+  // Performance metrics for debugging
+  const lodMetrics = computed(() => ({
+    level: lodLevel.value,
+    zoom: zoomRef.value,
+    widgetCount: shouldRenderWidgets.value ? 'full' : 'none',
+    slotCount: shouldRenderSlots.value ? 'full' : 'none'
+  }))
+
+  return {
+    // Core LOD state
+    lodLevel: readonly(lodLevel),
+    lodConfig: readonly(lodConfig),
+    lodScore: readonly(lodScore),
+
+    // Rendering decisions
+    shouldRenderWidgets,
+    shouldRenderSlots,
+    shouldRenderContent,
+    shouldRenderSlotLabels,
+    shouldRenderWidgetLabels,
+
+    // Styling
+    lodCssClass,
+
+    // Utilities
+    getEssentialWidgets,
+    lodMetrics
+  }
+}
+
+/**
+ * Get LOD level thresholds for configuration or debugging
+ */
+export const LOD_THRESHOLDS = {
+  FULL_THRESHOLD: 0.8,
+  REDUCED_THRESHOLD: 0.4,
+  MINIMAL_THRESHOLD: 0.0
+} as const
+
+/**
+ * Check if zoom level supports a specific feature
+ */
+export function supportsFeatureAtZoom(
+  zoom: number,
+  feature: keyof LODConfig
+): boolean {
+  const level =
+    zoom > 0.8
+      ? LODLevel.FULL
+      : zoom > 0.4
+        ? LODLevel.REDUCED
+        : LODLevel.MINIMAL
+  return LOD_CONFIGS[level][feature] as boolean
+}

src/composables/graph/useSpatialIndex.ts

@@ -0,0 +1,212 @@
+/**
+ * Composable for spatial indexing of nodes using QuadTree
+ * Integrates with useGraphNodeManager for efficient viewport culling
+ */
+import { useDebounceFn } from '@vueuse/core'
+import { computed, reactive, ref } from 'vue'
+
+import { type Bounds, QuadTree } from '@/utils/spatial/QuadTree'
+
+export interface SpatialIndexOptions {
+  worldBounds?: Bounds
+  maxDepth?: number
+  maxItemsPerNode?: number
+  enableDebugVisualization?: boolean
+  updateDebounceMs?: number
+}
+
+interface SpatialMetrics {
+  queryTime: number
+  totalNodes: number
+  visibleNodes: number
+  treeDepth: number
+  rebuildCount: number
+}
+
+export const useSpatialIndex = (options: SpatialIndexOptions = {}) => {
+  // Default world bounds (can be expanded dynamically)
+  const defaultBounds: Bounds = {
+    x: -10000,
+    y: -10000,
+    width: 20000,
+    height: 20000
+  }
+
+  // QuadTree instance
+  const quadTree = ref<QuadTree<string> | null>(null)
+
+  // Performance metrics
+  const metrics = reactive<SpatialMetrics>({
+    queryTime: 0,
+    totalNodes: 0,
+    visibleNodes: 0,
+    treeDepth: 0,
+    rebuildCount: 0
+  })
+
+  // Debug visualization data (unused for now but may be used in future)
+  // const debugBounds = ref<Bounds[]>([])
+
+  // Initialize QuadTree
+  const initialize = (bounds: Bounds = defaultBounds) => {
+    quadTree.value = new QuadTree<string>(bounds, {
+      maxDepth: options.maxDepth ?? 6,
+      maxItemsPerNode: options.maxItemsPerNode ?? 4
+    })
+    metrics.rebuildCount++
+  }
+
+  // Add or update node in spatial index
+  const updateNode = (
+    nodeId: string,
+    position: { x: number; y: number },
+    size: { width: number; height: number }
+  ) => {
+    if (!quadTree.value) {
+      initialize()
+    }
+
+    const bounds: Bounds = {
+      x: position.x,
+      y: position.y,
+      width: size.width,
+      height: size.height
+    }
+
+    // Use insert instead of update - insert handles both new and existing nodes
+    quadTree.value!.insert(nodeId, bounds, nodeId)
+    metrics.totalNodes = quadTree.value!.size
+  }
+
+  // Batch update for multiple nodes
+  const batchUpdate = (
+    updates: Array<{
+      id: string
+      position: { x: number; y: number }
+      size: { width: number; height: number }
+    }>
+  ) => {
+    if (!quadTree.value) {
+      initialize()
+    }
+
+    for (const update of updates) {
+      const bounds: Bounds = {
+        x: update.position.x,
+        y: update.position.y,
+        width: update.size.width,
+        height: update.size.height
+      }
+      // Use insert instead of update - insert handles both new and existing nodes
+      quadTree.value!.insert(update.id, bounds, update.id)
+    }
+
+    metrics.totalNodes = quadTree.value!.size
+  }
+
+  // Remove node from spatial index
+  const removeNode = (nodeId: string) => {
+    if (!quadTree.value) return
+
+    quadTree.value.remove(nodeId)
+    metrics.totalNodes = quadTree.value.size
+  }
+
+  // Query nodes within viewport bounds
+  const queryViewport = (viewportBounds: Bounds): string[] => {
+    if (!quadTree.value) return []
+
+    const startTime = performance.now()
+    const nodeIds = quadTree.value.query(viewportBounds)
+    const queryTime = performance.now() - startTime
+
+    metrics.queryTime = queryTime
+    metrics.visibleNodes = nodeIds.length
+
+    return nodeIds
+  }
+
+  // Get nodes within a radius (for proximity queries)
+  const queryRadius = (
+    center: { x: number; y: number },
+    radius: number
+  ): string[] => {
+    if (!quadTree.value) return []
+
+    const bounds: Bounds = {
+      x: center.x - radius,
+      y: center.y - radius,
+      width: radius * 2,
+      height: radius * 2
+    }
+
+    return quadTree.value.query(bounds)
+  }
+
+  // Clear all nodes
+  const clear = () => {
+    if (!quadTree.value) return
+
+    quadTree.value.clear()
+    metrics.totalNodes = 0
+    metrics.visibleNodes = 0
+  }
+
+  // Rebuild tree (useful after major layout changes)
+  const rebuild = (
+    nodes: Map<
+      string,
+      {
+        position: { x: number; y: number }
+        size: { width: number; height: number }
+      }
+    >
+  ) => {
+    initialize()
+
+    const updates = Array.from(nodes.entries()).map(([id, data]) => ({
+      id,
+      position: data.position,
+      size: data.size
+    }))
+
+    batchUpdate(updates)
+  }
+
+  // Get debug visualization data
+  const getDebugVisualization = () => {
+    if (!quadTree.value || !options.enableDebugVisualization) return null
+
+    return quadTree.value.getDebugInfo()
+  }
+
+  // Debounced update for performance
+  const debouncedUpdateNode = useDebounceFn(
+    updateNode,
+    options.updateDebounceMs ?? 16
+  )
+
+  return {
+    // Core functions
+    initialize,
+    updateNode,
+    batchUpdate,
+    removeNode,
+    queryViewport,
+    queryRadius,
+    clear,
+    rebuild,
+
+    // Debounced version for high-frequency updates
+    debouncedUpdateNode,
+
+    // Metrics
+    metrics: computed(() => metrics),
+
+    // Debug
+    getDebugVisualization,
+
+    // Direct access to QuadTree (for advanced usage)
+    quadTree: computed(() => quadTree.value)
+  }
+}

src/composables/graph/useTransformSettling.ts

@@ -0,0 +1,151 @@
+import { useDebounceFn, useEventListener, useThrottleFn } from '@vueuse/core'
+import { ref } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
+
+export interface TransformSettlingOptions {
+  /**
+   * Delay in ms before transform is considered "settled" after last interaction
+   * @default 200
+   */
+  settleDelay?: number
+  /**
+   * Whether to track both zoom (wheel) and pan (pointer drag) interactions
+   * @default false
+   */
+  trackPan?: boolean
+  /**
+   * Throttle delay for high-frequency pointermove events (only used when trackPan is true)
+   * @default 16 (~60fps)
+   */
+  pointerMoveThrottle?: number
+  /**
+   * Whether to use passive event listeners (better performance but can't preventDefault)
+   * @default true
+   */
+  passive?: boolean
+}
+
+/**
+ * Tracks when canvas transforms (zoom/pan) are actively changing vs settled.
+ *
+ * This composable helps optimize rendering quality during transformations.
+ * When the user is actively zooming or panning, 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,
+ *   trackPan: true
+ * })
+ *
+ * // 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 = 200,
+    trackPan = false,
+    pointerMoveThrottle = 16,
+    passive = true
+  } = options
+
+  const isTransforming = ref(false)
+  let isPanning = false
+
+  /**
+   * Mark transform as active
+   */
+  const markTransformActive = () => {
+    isTransforming.value = true
+  }
+
+  /**
+   * Mark transform as settled (debounced)
+   */
+  const markTransformSettled = useDebounceFn(() => {
+    isTransforming.value = false
+  }, settleDelay)
+
+  /**
+   * Handle any transform event - mark active then queue settle
+   */
+  const handleTransformEvent = () => {
+    markTransformActive()
+    void markTransformSettled()
+  }
+
+  // Wheel handler
+  const handleWheel = () => {
+    handleTransformEvent()
+  }
+
+  // Pointer handlers for panning
+  const handlePointerDown = () => {
+    if (trackPan) {
+      isPanning = true
+      handleTransformEvent()
+    }
+  }
+
+  // Throttled pointer move handler for performance
+  const handlePointerMove = trackPan
+    ? useThrottleFn(() => {
+        if (isPanning) {
+          handleTransformEvent()
+        }
+      }, pointerMoveThrottle)
+    : undefined
+
+  const handlePointerEnd = () => {
+    if (trackPan) {
+      isPanning = false
+      // Don't immediately stop - let the debounced settle handle it
+    }
+  }
+
+  // Register event listeners with auto-cleanup
+  useEventListener(target, 'wheel', handleWheel, {
+    capture: true,
+    passive
+  })
+
+  if (trackPan) {
+    useEventListener(target, 'pointerdown', handlePointerDown, {
+      capture: true
+    })
+
+    if (handlePointerMove) {
+      useEventListener(target, 'pointermove', handlePointerMove, {
+        capture: true,
+        passive
+      })
+    }
+
+    useEventListener(target, 'pointerup', handlePointerEnd, {
+      capture: true
+    })
+
+    useEventListener(target, 'pointercancel', handlePointerEnd, {
+      capture: true
+    })
+  }
+
+  return {
+    isTransforming
+  }
+}

src/composables/graph/useWidgetRenderer.ts

@@ -0,0 +1,110 @@
+/**
+ * Widget renderer composable for Vue node system
+ * Maps LiteGraph widget types to Vue components
+ */
+import {
+  WidgetType,
+  widgetTypeToComponent
+} from '@/components/graph/vueWidgets/widgetRegistry'
+
+/**
+ * Static mapping of LiteGraph widget types to Vue widget component names
+ * Moved outside function to prevent recreation on every call
+ */
+const TYPE_TO_ENUM_MAP: Record<string, string> = {
+  // Number inputs
+  number: WidgetType.NUMBER,
+  slider: WidgetType.SLIDER,
+  INT: WidgetType.INT,
+  FLOAT: WidgetType.FLOAT,
+
+  // Text inputs
+  text: WidgetType.STRING,
+  string: WidgetType.STRING,
+  STRING: WidgetType.STRING,
+
+  // Selection
+  combo: WidgetType.COMBO,
+  COMBO: WidgetType.COMBO,
+
+  // Boolean
+  toggle: WidgetType.TOGGLESWITCH,
+  boolean: WidgetType.BOOLEAN,
+  BOOLEAN: WidgetType.BOOLEAN,
+
+  // Multiline text
+  multiline: WidgetType.TEXTAREA,
+  textarea: WidgetType.TEXTAREA,
+
+  // Advanced widgets
+  color: WidgetType.COLOR,
+  COLOR: WidgetType.COLOR,
+  image: WidgetType.IMAGE,
+  IMAGE: WidgetType.IMAGE,
+  file: WidgetType.FILEUPLOAD,
+  FILEUPLOAD: WidgetType.FILEUPLOAD,
+
+  // Button widget
+  button: WidgetType.BUTTON,
+  BUTTON: WidgetType.BUTTON,
+
+  // Text-based widgets that don't have dedicated components yet
+  MARKDOWN: WidgetType.TEXTAREA, // Markdown should use textarea for now
+  customtext: WidgetType.TEXTAREA // Custom text widgets use textarea for multiline
+} as const
+
+/**
+ * Pre-computed widget support map for O(1) lookups
+ * Maps widget type directly to boolean for fast shouldRenderAsVue checks
+ */
+const WIDGET_SUPPORT_MAP = new Map(
+  Object.entries(TYPE_TO_ENUM_MAP).map(([type, enumValue]) => [
+    type,
+    widgetTypeToComponent[enumValue] !== undefined
+  ])
+)
+
+export const ESSENTIAL_WIDGET_TYPES = new Set([
+  'combo',
+  'COMBO',
+  'select',
+  'toggle',
+  'boolean',
+  'BOOLEAN',
+  'slider',
+  'number',
+  'INT',
+  'FLOAT'
+])
+
+export const useWidgetRenderer = () => {
+  const getWidgetComponent = (widgetType: string): string => {
+    const enumKey = TYPE_TO_ENUM_MAP[widgetType]
+
+    if (enumKey && widgetTypeToComponent[enumKey]) {
+      return enumKey
+    }
+
+    return WidgetType.STRING
+  }
+
+  const shouldRenderAsVue = (widget: {
+    type?: string
+    options?: Record<string, unknown>
+  }): boolean => {
+    if (widget.options?.canvasOnly) return false
+    if (!widget.type) return false
+
+    // Check if widget type is explicitly supported
+    const isSupported = WIDGET_SUPPORT_MAP.get(widget.type)
+    if (isSupported !== undefined) return isSupported
+
+    // Fallback: unknown types are rendered as STRING widget
+    return widgetTypeToComponent[WidgetType.STRING] !== undefined
+  }
+
+  return {
+    getWidgetComponent,
+    shouldRenderAsVue
+  }
+}

src/composables/graph/useWidgetValue.ts

@@ -0,0 +1,160 @@
+/**
+ * Composable for managing widget value synchronization between Vue and LiteGraph
+ * Provides consistent pattern for immediate UI updates and LiteGraph callbacks
+ */
+import { type Ref, ref, watch } from 'vue'
+
+import type { SimplifiedWidget, WidgetValue } from '@/types/simplifiedWidget'
+
+export interface UseWidgetValueOptions<
+  T extends WidgetValue = WidgetValue,
+  U = T
+> {
+  /** The widget configuration from LiteGraph */
+  widget: SimplifiedWidget<T>
+  /** The current value from parent component */
+  modelValue: T
+  /** Default value if modelValue is null/undefined */
+  defaultValue: T
+  /** Emit function from component setup */
+  emit: (event: 'update:modelValue', value: T) => void
+  /** Optional value transformer before sending to LiteGraph */
+  transform?: (value: U) => T
+}
+
+export interface UseWidgetValueReturn<
+  T extends WidgetValue = WidgetValue,
+  U = T
+> {
+  /** Local value for immediate UI updates */
+  localValue: Ref<T>
+  /** Handler for user interactions */
+  onChange: (newValue: U) => void
+}
+
+/**
+ * Manages widget value synchronization with LiteGraph
+ *
+ * @example
+ * ```vue
+ * const { localValue, onChange } = useWidgetValue({
+ *   widget: props.widget,
+ *   modelValue: props.modelValue,
+ *   defaultValue: ''
+ * })
+ * ```
+ */
+export function useWidgetValue<T extends WidgetValue = WidgetValue, U = T>({
+  widget,
+  modelValue,
+  defaultValue,
+  emit,
+  transform
+}: UseWidgetValueOptions<T, U>): UseWidgetValueReturn<T, U> {
+  // Local value for immediate UI updates
+  const localValue = ref<T>(modelValue ?? defaultValue)
+
+  // Handle user changes
+  const onChange = (newValue: U) => {
+    // Handle different PrimeVue component signatures
+    let processedValue: T
+    if (transform) {
+      processedValue = transform(newValue)
+    } else {
+      // Ensure type safety - only cast when types are compatible
+      if (
+        typeof newValue === typeof defaultValue ||
+        newValue === null ||
+        newValue === undefined
+      ) {
+        processedValue = (newValue ?? defaultValue) as T
+      } else {
+        console.warn(
+          `useWidgetValue: Type mismatch for widget ${widget.name}. Expected ${typeof defaultValue}, got ${typeof newValue}`
+        )
+        processedValue = defaultValue
+      }
+    }
+
+    // 1. Update local state for immediate UI feedback
+    localValue.value = processedValue
+
+    // 2. Emit to parent component
+    emit('update:modelValue', processedValue)
+
+    // 3. Call LiteGraph callback to update authoritative state
+    if (widget.callback) {
+      widget.callback(processedValue)
+    }
+  }
+
+  // Watch for external updates from LiteGraph
+  watch(
+    () => modelValue,
+    (newValue) => {
+      localValue.value = newValue ?? defaultValue
+    }
+  )
+
+  return {
+    localValue: localValue as Ref<T>,
+    onChange
+  }
+}
+
+/**
+ * Type-specific helper for string widgets
+ */
+export function useStringWidgetValue(
+  widget: SimplifiedWidget<string>,
+  modelValue: string,
+  emit: (event: 'update:modelValue', value: string) => void
+) {
+  return useWidgetValue({
+    widget,
+    modelValue,
+    defaultValue: '',
+    emit,
+    transform: (value: string | undefined) => String(value || '') // Handle undefined from PrimeVue
+  })
+}
+
+/**
+ * Type-specific helper for number widgets
+ */
+export function useNumberWidgetValue(
+  widget: SimplifiedWidget<number>,
+  modelValue: number,
+  emit: (event: 'update:modelValue', value: number) => void
+) {
+  return useWidgetValue({
+    widget,
+    modelValue,
+    defaultValue: 0,
+    emit,
+    transform: (value: number | number[]) => {
+      // Handle PrimeVue Slider which can emit number | number[]
+      if (Array.isArray(value)) {
+        return value.length > 0 ? value[0] ?? 0 : 0
+      }
+      return Number(value) || 0
+    }
+  })
+}
+
+/**
+ * Type-specific helper for boolean widgets
+ */
+export function useBooleanWidgetValue(
+  widget: SimplifiedWidget<boolean>,
+  modelValue: boolean,
+  emit: (event: 'update:modelValue', value: boolean) => void
+) {
+  return useWidgetValue({
+    widget,
+    modelValue,
+    defaultValue: false,
+    emit,
+    transform: (value: boolean) => Boolean(value)
+  })
+}

src/composables/useFeatureFlags.ts

@@ -0,0 +1,68 @@
+/**
+ * Feature flags composable for Vue node system
+ * Provides safe toggles for experimental features
+ */
+import { computed } from 'vue'
+
+import { useSettingStore } from '@/stores/settingStore'
+
+export const useFeatureFlags = () => {
+  const settingStore = useSettingStore()
+
+  /**
+   * Enable Vue-based node rendering
+   * When disabled, falls back to standard LiteGraph canvas rendering
+   */
+  const isVueNodesEnabled = computed(() => {
+    try {
+      return settingStore.get('Comfy.VueNodes.Enabled' as any) ?? true // Default to true for development
+    } catch {
+      return true // Default to true for development
+    }
+  })
+
+  /**
+   * Enable Vue widget rendering within Vue nodes
+   * When disabled, Vue nodes render without widgets (structure only)
+   */
+  const isVueWidgetsEnabled = computed(() => {
+    try {
+      return settingStore.get('Comfy.VueNodes.Widgets' as any) ?? true
+    } catch {
+      return true
+    }
+  })
+
+  /**
+   * Development mode features (debug panel, etc.)
+   * Automatically enabled in development builds
+   */
+  const isDevModeEnabled = computed(() => {
+    try {
+      return (
+        settingStore.get('Comfy.DevMode' as any) ??
+        process.env.NODE_ENV === 'development'
+      )
+    } catch {
+      return process.env.NODE_ENV === 'development'
+    }
+  })
+
+  /**
+   * Check if Vue nodes should be rendered at all
+   * Combines multiple conditions for safety
+   */
+  const shouldRenderVueNodes = computed(
+    () =>
+      isVueNodesEnabled.value &&
+      // Add any other safety conditions here
+      true
+  )
+
+  return {
+    isVueNodesEnabled,
+    isVueWidgetsEnabled,
+    isDevModeEnabled,
+    shouldRenderVueNodes
+  }
+}

src/constants/coreSettings.ts

@@ -866,5 +866,26 @@ export const CORE_SETTINGS: SettingParams[] = [
     name: 'Release seen timestamp',
     type: 'hidden',
     defaultValue: 0
+  },
+
+  // Vue Node System Settings
+  {
+    id: 'Comfy.VueNodes.Enabled' as any,
+    category: ['Comfy', 'Vue Nodes'],
+    experimental: true,
+    name: 'Enable Vue node rendering',
+    tooltip:
+      'Render nodes as Vue components instead of canvas elements. Experimental feature.',
+    type: 'boolean',
+    defaultValue: false
+  },
+  {
+    id: 'Comfy.VueNodes.Widgets' as any,
+    category: ['Comfy', 'Vue Nodes', 'Widgets'],
+    experimental: true,
+    name: 'Enable Vue widgets',
+    tooltip: 'Render widgets as Vue components within Vue nodes.',
+    type: 'boolean',
+    defaultValue: true
   }
 ]

src/constants/slotColors.ts

@@ -0,0 +1,30 @@
+/**
+ * Default colors for node slot types
+ * Mirrors LiteGraph's slot_default_color_by_type
+ */
+export const SLOT_TYPE_COLORS: Record<string, string> = {
+  number: '#AAD',
+  string: '#DCA',
+  boolean: '#DAA',
+  vec2: '#ADA',
+  vec3: '#ADA',
+  vec4: '#ADA',
+  color: '#DDA',
+  image: '#353',
+  latent: '#858',
+  conditioning: '#FFA',
+  control_net: '#F8F',
+  clip: '#FFD',
+  vae: '#F82',
+  model: '#B98',
+  '*': '#AAA' // Default color
+}
+
+/**
+ * Get the color for a slot type
+ */
+export function getSlotColor(type?: string | number | null): string {
+  if (!type) return SLOT_TYPE_COLORS['*']
+  const typeStr = String(type).toLowerCase()
+  return SLOT_TYPE_COLORS[typeStr] || SLOT_TYPE_COLORS['*']
+}

src/types/simplifiedWidget.ts

@@ -0,0 +1,41 @@
+/**
+ * Simplified widget interface for Vue-based node rendering
+ * Removes all DOM manipulation and positioning concerns
+ */
+
+/** Valid types for widget values */
+export type WidgetValue =
+  | string
+  | number
+  | boolean
+  | object
+  | undefined
+  | null
+  | void
+  | File[]
+
+export interface SimplifiedWidget<
+  T extends WidgetValue = WidgetValue,
+  O = Record<string, any>
+> {
+  /** Display name of the widget */
+  name: string
+
+  /** Widget type identifier (e.g., 'STRING', 'INT', 'COMBO') */
+  type: string
+
+  /** Current value of the widget */
+  value: T
+
+  /** Widget options including filtered PrimeVue props */
+  options?: O
+
+  /** Callback fired when value changes */
+  callback?: (value: T) => void
+
+  /** Optional serialization method for custom value handling */
+  serializeValue?: () => any
+
+  /** Optional method to compute widget size requirements */
+  computeSize?: () => { minHeight: number; maxHeight?: number }
+}

src/types/spatialIndex.ts

@@ -0,0 +1,23 @@
+/**
+ * Type definitions for spatial indexing system
+ */
+import type { Bounds } from '@/utils/spatial/QuadTree'
+
+/**
+ * Debug information for a single QuadTree node
+ */
+export interface QuadNodeDebugInfo {
+  bounds: Bounds
+  depth: number
+  itemCount: number
+  divided: boolean
+  children?: QuadNodeDebugInfo[]
+}
+
+/**
+ * Debug information for the entire spatial index
+ */
+export interface SpatialIndexDebugInfo {
+  size: number
+  tree: QuadNodeDebugInfo
+}

src/utils/spatial/QuadTree.ts

@@ -0,0 +1,302 @@
+/**
+ * QuadTree implementation for spatial indexing of nodes
+ * Optimized for viewport culling in large node graphs
+ */
+import type {
+  QuadNodeDebugInfo,
+  SpatialIndexDebugInfo
+} from '@/types/spatialIndex'
+
+export interface Bounds {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface QuadTreeItem<T> {
+  id: string
+  bounds: Bounds
+  data: T
+}
+
+interface QuadTreeOptions {
+  maxDepth?: number
+  maxItemsPerNode?: number
+  minNodeSize?: number
+}
+
+class QuadNode<T> {
+  private bounds: Bounds
+  private depth: number
+  private maxDepth: number
+  private maxItems: number
+  private items: QuadTreeItem<T>[] = []
+  private children: QuadNode<T>[] | null = null
+  private divided = false
+
+  constructor(
+    bounds: Bounds,
+    depth: number = 0,
+    maxDepth: number = 5,
+    maxItems: number = 4
+  ) {
+    this.bounds = bounds
+    this.depth = depth
+    this.maxDepth = maxDepth
+    this.maxItems = maxItems
+  }
+
+  insert(item: QuadTreeItem<T>): boolean {
+    // Check if item is within bounds
+    if (!this.contains(item.bounds)) {
+      return false
+    }
+
+    // If we have space and haven't divided, add to this node
+    if (this.items.length < this.maxItems && !this.divided) {
+      this.items.push(item)
+      return true
+    }
+
+    // If we haven't reached max depth, subdivide
+    if (!this.divided && this.depth < this.maxDepth) {
+      this.subdivide()
+    }
+
+    // If divided, insert into children
+    if (this.divided && this.children) {
+      for (const child of this.children) {
+        if (child.insert(item)) {
+          return true
+        }
+      }
+    }
+
+    // If we can't subdivide further, add to this node anyway
+    this.items.push(item)
+    return true
+  }
+
+  remove(item: QuadTreeItem<T>): boolean {
+    const index = this.items.findIndex((i) => i.id === item.id)
+    if (index !== -1) {
+      this.items.splice(index, 1)
+      return true
+    }
+
+    if (this.divided && this.children) {
+      for (const child of this.children) {
+        if (child.remove(item)) {
+          return true
+        }
+      }
+    }
+
+    return false
+  }
+
+  query(
+    searchBounds: Bounds,
+    found: QuadTreeItem<T>[] = []
+  ): QuadTreeItem<T>[] {
+    // Check if search area intersects with this node
+    if (!this.intersects(searchBounds)) {
+      return found
+    }
+
+    // Add items in this node that intersect with search bounds
+    for (const item of this.items) {
+      if (this.boundsIntersect(item.bounds, searchBounds)) {
+        found.push(item)
+      }
+    }
+
+    // Recursively search children
+    if (this.divided && this.children) {
+      for (const child of this.children) {
+        child.query(searchBounds, found)
+      }
+    }
+
+    return found
+  }
+
+  private subdivide() {
+    const { x, y, width, height } = this.bounds
+    const halfWidth = width / 2
+    const halfHeight = height / 2
+
+    this.children = [
+      // Top-left
+      new QuadNode<T>(
+        { x, y, width: halfWidth, height: halfHeight },
+        this.depth + 1,
+        this.maxDepth,
+        this.maxItems
+      ),
+      // Top-right
+      new QuadNode<T>(
+        { x: x + halfWidth, y, width: halfWidth, height: halfHeight },
+        this.depth + 1,
+        this.maxDepth,
+        this.maxItems
+      ),
+      // Bottom-left
+      new QuadNode<T>(
+        { x, y: y + halfHeight, width: halfWidth, height: halfHeight },
+        this.depth + 1,
+        this.maxDepth,
+        this.maxItems
+      ),
+      // Bottom-right
+      new QuadNode<T>(
+        {
+          x: x + halfWidth,
+          y: y + halfHeight,
+          width: halfWidth,
+          height: halfHeight
+        },
+        this.depth + 1,
+        this.maxDepth,
+        this.maxItems
+      )
+    ]
+
+    this.divided = true
+
+    // Redistribute existing items to children
+    const itemsToRedistribute = [...this.items]
+    this.items = []
+
+    for (const item of itemsToRedistribute) {
+      let inserted = false
+      for (const child of this.children) {
+        if (child.insert(item)) {
+          inserted = true
+          break
+        }
+      }
+      // Keep in parent if it doesn't fit in any child
+      if (!inserted) {
+        this.items.push(item)
+      }
+    }
+  }
+
+  private contains(itemBounds: Bounds): boolean {
+    return (
+      itemBounds.x >= this.bounds.x &&
+      itemBounds.y >= this.bounds.y &&
+      itemBounds.x + itemBounds.width <= this.bounds.x + this.bounds.width &&
+      itemBounds.y + itemBounds.height <= this.bounds.y + this.bounds.height
+    )
+  }
+
+  private intersects(searchBounds: Bounds): boolean {
+    return this.boundsIntersect(this.bounds, searchBounds)
+  }
+
+  private boundsIntersect(a: Bounds, b: Bounds): boolean {
+    return !(
+      a.x + a.width < b.x ||
+      b.x + b.width < a.x ||
+      a.y + a.height < b.y ||
+      b.y + b.height < a.y
+    )
+  }
+
+  // Debug helper to get tree structure
+  getDebugInfo(): QuadNodeDebugInfo {
+    return {
+      bounds: this.bounds,
+      depth: this.depth,
+      itemCount: this.items.length,
+      divided: this.divided,
+      children: this.children?.map((child) => child.getDebugInfo())
+    }
+  }
+}
+
+export class QuadTree<T> {
+  private root: QuadNode<T>
+  private itemMap: Map<string, QuadTreeItem<T>> = new Map()
+  private options: Required<QuadTreeOptions>
+
+  constructor(bounds: Bounds, options: QuadTreeOptions = {}) {
+    this.options = {
+      maxDepth: options.maxDepth ?? 5,
+      maxItemsPerNode: options.maxItemsPerNode ?? 4,
+      minNodeSize: options.minNodeSize ?? 50
+    }
+
+    this.root = new QuadNode<T>(
+      bounds,
+      0,
+      this.options.maxDepth,
+      this.options.maxItemsPerNode
+    )
+  }
+
+  insert(id: string, bounds: Bounds, data: T): boolean {
+    const item: QuadTreeItem<T> = { id, bounds, data }
+
+    // Remove old item if it exists
+    if (this.itemMap.has(id)) {
+      this.remove(id)
+    }
+
+    const success = this.root.insert(item)
+    if (success) {
+      this.itemMap.set(id, item)
+    }
+    return success
+  }
+
+  remove(id: string): boolean {
+    const item = this.itemMap.get(id)
+    if (!item) return false
+
+    const success = this.root.remove(item)
+    if (success) {
+      this.itemMap.delete(id)
+    }
+    return success
+  }
+
+  update(id: string, newBounds: Bounds): boolean {
+    const item = this.itemMap.get(id)
+    if (!item) return false
+
+    // Remove and re-insert with new bounds
+    const data = item.data
+    this.remove(id)
+    return this.insert(id, newBounds, data)
+  }
+
+  query(searchBounds: Bounds): T[] {
+    const items = this.root.query(searchBounds)
+    return items.map((item) => item.data)
+  }
+
+  clear() {
+    this.root = new QuadNode<T>(
+      this.root['bounds'],
+      0,
+      this.options.maxDepth,
+      this.options.maxItemsPerNode
+    )
+    this.itemMap.clear()
+  }
+
+  get size(): number {
+    return this.itemMap.size
+  }
+
+  getDebugInfo(): SpatialIndexDebugInfo {
+    return {
+      size: this.size,
+      tree: this.root.getDebugInfo()
+    }
+  }
+}

src/utils/typeGuardUtil.ts

@@ -27,3 +27,33 @@ export const isSubgraph = (
  */
 export const isNonNullish = <T>(item: T | undefined | null): item is T =>
   item != null
+
+/**
+ * Type guard for slot objects (inputs/outputs)
+ */
+export const isSlotObject = (
+  obj: unknown
+): obj is { name?: string; type?: string } => {
+  return obj !== null && typeof obj === 'object'
+}
+
+/**
+ * Type guard for safe number conversion
+ */
+export const isValidNumber = (value: unknown): value is number => {
+  return typeof value === 'number' && !isNaN(value) && isFinite(value)
+}
+
+/**
+ * Type guard for safe string conversion
+ */
+export const isValidString = (value: unknown): value is string => {
+  return typeof value === 'string'
+}
+
+/**
+ * Type guard for arrays with safe bounds checking
+ */
+export const isNonEmptyArray = <T>(value: unknown): value is T[] => {
+  return Array.isArray(value) && value.length > 0
+}

src/utils/widgetPropFilter.ts

@@ -0,0 +1,76 @@
+/**
+ * Widget prop filtering utilities
+ * Filters out style-related and customization props from PrimeVue components
+ * to maintain consistent widget appearance across the application
+ */
+
+// Props to exclude based on the widget interface specifications
+export const STANDARD_EXCLUDED_PROPS = [
+  'style',
+  'class',
+  'dt',
+  'pt',
+  'ptOptions',
+  'unstyled'
+] as const
+
+export const INPUT_EXCLUDED_PROPS = [
+  ...STANDARD_EXCLUDED_PROPS,
+  'inputClass',
+  'inputStyle'
+] as const
+
+export const PANEL_EXCLUDED_PROPS = [
+  ...STANDARD_EXCLUDED_PROPS,
+  'panelClass',
+  'panelStyle',
+  'overlayClass'
+] as const
+
+export const IMAGE_EXCLUDED_PROPS = [
+  ...STANDARD_EXCLUDED_PROPS,
+  'imageClass',
+  'imageStyle'
+] as const
+
+export const GALLERIA_EXCLUDED_PROPS = [
+  ...STANDARD_EXCLUDED_PROPS,
+  'thumbnailsPosition',
+  'verticalThumbnailViewPortHeight',
+  'indicatorsPosition',
+  'maskClass',
+  'containerStyle',
+  'containerClass',
+  'galleriaClass'
+] as const
+
+export const BADGE_EXCLUDED_PROPS = [
+  ...STANDARD_EXCLUDED_PROPS,
+  'badgeClass'
+] as const
+
+export const LABEL_EXCLUDED_PROPS = [
+  ...PANEL_EXCLUDED_PROPS,
+  'labelStyle'
+] as const
+
+/**
+ * Filters widget props by excluding specified properties
+ * @param props - The props object to filter
+ * @param excludeList - List of property names to exclude
+ * @returns Filtered props object
+ */
+export function filterWidgetProps<T extends Record<string, any>>(
+  props: T | undefined,
+  excludeList: readonly string[]
+): Partial<T> {
+  if (!props) return {}
+
+  const filtered: Record<string, any> = {}
+  for (const [key, value] of Object.entries(props)) {
+    if (!excludeList.includes(key)) {
+      filtered[key] = value
+    }
+  }
+  return filtered as Partial<T>
+}

tests-ui/tests/composables/element/useTransformState.test.ts

@@ -0,0 +1,329 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { useTransformState } from '@/composables/element/useTransformState'
+
+import { createMockCanvasContext } from '../../helpers/nodeTestHelpers'
+
+describe('useTransformState', () => {
+  let transformState: ReturnType<typeof useTransformState>
+
+  beforeEach(() => {
+    transformState = useTransformState()
+  })
+
+  describe('initial state', () => {
+    it('should initialize with default camera values', () => {
+      const { camera } = transformState
+      expect(camera.x).toBe(0)
+      expect(camera.y).toBe(0)
+      expect(camera.z).toBe(1)
+    })
+
+    it('should generate correct initial transform style', () => {
+      const { transformStyle } = transformState
+      expect(transformStyle.value).toEqual({
+        transform: 'scale(1) translate(0px, 0px)',
+        transformOrigin: '0 0'
+      })
+    })
+  })
+
+  describe('syncWithCanvas', () => {
+    it('should sync camera state with canvas transform', () => {
+      const { syncWithCanvas, camera } = transformState
+      const mockCanvas = createMockCanvasContext()
+
+      // Set mock canvas transform
+      mockCanvas.ds.offset = [100, 50]
+      mockCanvas.ds.scale = 2
+
+      syncWithCanvas(mockCanvas as any)
+
+      expect(camera.x).toBe(100)
+      expect(camera.y).toBe(50)
+      expect(camera.z).toBe(2)
+    })
+
+    it('should handle null canvas gracefully', () => {
+      const { syncWithCanvas, camera } = transformState
+
+      syncWithCanvas(null as any)
+
+      // Should remain at initial values
+      expect(camera.x).toBe(0)
+      expect(camera.y).toBe(0)
+      expect(camera.z).toBe(1)
+    })
+
+    it('should handle canvas without ds property', () => {
+      const { syncWithCanvas, camera } = transformState
+      const canvasWithoutDs = { canvas: {} }
+
+      syncWithCanvas(canvasWithoutDs as any)
+
+      // Should remain at initial values
+      expect(camera.x).toBe(0)
+      expect(camera.y).toBe(0)
+      expect(camera.z).toBe(1)
+    })
+
+    it('should update transform style after sync', () => {
+      const { syncWithCanvas, transformStyle } = transformState
+      const mockCanvas = createMockCanvasContext()
+
+      mockCanvas.ds.offset = [150, 75]
+      mockCanvas.ds.scale = 0.5
+
+      syncWithCanvas(mockCanvas as any)
+
+      expect(transformStyle.value).toEqual({
+        transform: 'scale(0.5) translate(150px, 75px)',
+        transformOrigin: '0 0'
+      })
+    })
+  })
+
+  describe('coordinate conversions', () => {
+    beforeEach(() => {
+      // Set up a known transform state
+      const mockCanvas = createMockCanvasContext()
+      mockCanvas.ds.offset = [100, 50]
+      mockCanvas.ds.scale = 2
+      transformState.syncWithCanvas(mockCanvas as any)
+    })
+
+    describe('canvasToScreen', () => {
+      it('should convert canvas coordinates to screen coordinates', () => {
+        const { canvasToScreen } = transformState
+
+        const canvasPoint = { x: 10, y: 20 }
+        const screenPoint = canvasToScreen(canvasPoint)
+
+        // screen = canvas * scale + offset
+        // x: 10 * 2 + 100 = 120
+        // y: 20 * 2 + 50 = 90
+        expect(screenPoint).toEqual({ x: 120, y: 90 })
+      })
+
+      it('should handle zero coordinates', () => {
+        const { canvasToScreen } = transformState
+
+        const screenPoint = canvasToScreen({ x: 0, y: 0 })
+        expect(screenPoint).toEqual({ x: 100, y: 50 })
+      })
+
+      it('should handle negative coordinates', () => {
+        const { canvasToScreen } = transformState
+
+        const screenPoint = canvasToScreen({ x: -10, y: -20 })
+        expect(screenPoint).toEqual({ x: 80, y: 10 })
+      })
+    })
+
+    describe('screenToCanvas', () => {
+      it('should convert screen coordinates to canvas coordinates', () => {
+        const { screenToCanvas } = transformState
+
+        const screenPoint = { x: 120, y: 90 }
+        const canvasPoint = screenToCanvas(screenPoint)
+
+        // canvas = (screen - offset) / scale
+        // x: (120 - 100) / 2 = 10
+        // y: (90 - 50) / 2 = 20
+        expect(canvasPoint).toEqual({ x: 10, y: 20 })
+      })
+
+      it('should be inverse of canvasToScreen', () => {
+        const { canvasToScreen, screenToCanvas } = transformState
+
+        const originalPoint = { x: 25, y: 35 }
+        const screenPoint = canvasToScreen(originalPoint)
+        const backToCanvas = screenToCanvas(screenPoint)
+
+        expect(backToCanvas.x).toBeCloseTo(originalPoint.x)
+        expect(backToCanvas.y).toBeCloseTo(originalPoint.y)
+      })
+    })
+  })
+
+  describe('getNodeScreenBounds', () => {
+    beforeEach(() => {
+      const mockCanvas = createMockCanvasContext()
+      mockCanvas.ds.offset = [100, 50]
+      mockCanvas.ds.scale = 2
+      transformState.syncWithCanvas(mockCanvas as any)
+    })
+
+    it('should calculate correct screen bounds for a node', () => {
+      const { getNodeScreenBounds } = transformState
+
+      const nodePos = [10, 20]
+      const nodeSize = [200, 100]
+      const bounds = getNodeScreenBounds(nodePos, nodeSize)
+
+      // Top-left: canvasToScreen(10, 20) = (120, 90)
+      // Width: 200 * 2 = 400
+      // Height: 100 * 2 = 200
+      expect(bounds.x).toBe(120)
+      expect(bounds.y).toBe(90)
+      expect(bounds.width).toBe(400)
+      expect(bounds.height).toBe(200)
+    })
+  })
+
+  describe('isNodeInViewport', () => {
+    beforeEach(() => {
+      const mockCanvas = createMockCanvasContext()
+      mockCanvas.ds.offset = [0, 0]
+      mockCanvas.ds.scale = 1
+      transformState.syncWithCanvas(mockCanvas as any)
+    })
+
+    const viewport = { width: 1000, height: 600 }
+
+    it('should return true for nodes inside viewport', () => {
+      const { isNodeInViewport } = transformState
+
+      const nodePos = [100, 100]
+      const nodeSize = [200, 100]
+
+      expect(isNodeInViewport(nodePos, nodeSize, viewport)).toBe(true)
+    })
+
+    it('should return false for nodes completely outside viewport', () => {
+      const { isNodeInViewport } = transformState
+
+      // Node far to the right
+      expect(isNodeInViewport([2000, 100], [200, 100], viewport)).toBe(false)
+
+      // Node far to the left
+      expect(isNodeInViewport([-500, 100], [200, 100], viewport)).toBe(false)
+
+      // Node far below
+      expect(isNodeInViewport([100, 1000], [200, 100], viewport)).toBe(false)
+
+      // Node far above
+      expect(isNodeInViewport([100, -500], [200, 100], viewport)).toBe(false)
+    })
+
+    it('should return true for nodes partially in viewport with margin', () => {
+      const { isNodeInViewport } = transformState
+
+      // Node slightly outside but within margin
+      const nodePos = [-50, -50]
+      const nodeSize = [100, 100]
+
+      expect(isNodeInViewport(nodePos, nodeSize, viewport, 0.2)).toBe(true)
+    })
+
+    it('should return false for tiny nodes (size culling)', () => {
+      const { isNodeInViewport } = transformState
+
+      // Node is in viewport but too small
+      const nodePos = [100, 100]
+      const nodeSize = [3, 3] // Less than 4 pixels
+
+      expect(isNodeInViewport(nodePos, nodeSize, viewport)).toBe(false)
+    })
+
+    it('should adjust margin based on zoom level', () => {
+      const { isNodeInViewport, syncWithCanvas } = transformState
+      const mockCanvas = createMockCanvasContext()
+
+      // Test with very low zoom
+      mockCanvas.ds.scale = 0.05
+      syncWithCanvas(mockCanvas as any)
+
+      // Node at edge should still be visible due to increased margin
+      expect(isNodeInViewport([1100, 100], [200, 100], viewport)).toBe(true)
+
+      // Test with high zoom
+      mockCanvas.ds.scale = 4
+      syncWithCanvas(mockCanvas as any)
+
+      // Margin should be tighter
+      expect(isNodeInViewport([1100, 100], [200, 100], viewport)).toBe(false)
+    })
+  })
+
+  describe('getViewportBounds', () => {
+    beforeEach(() => {
+      const mockCanvas = createMockCanvasContext()
+      mockCanvas.ds.offset = [100, 50]
+      mockCanvas.ds.scale = 2
+      transformState.syncWithCanvas(mockCanvas as any)
+    })
+
+    it('should calculate viewport bounds in canvas coordinates', () => {
+      const { getViewportBounds } = transformState
+      const viewport = { width: 1000, height: 600 }
+
+      const bounds = getViewportBounds(viewport, 0.2)
+
+      // With 20% margin:
+      // marginX = 1000 * 0.2 = 200
+      // marginY = 600 * 0.2 = 120
+      // topLeft in screen: (-200, -120)
+      // bottomRight in screen: (1200, 720)
+
+      // Convert to canvas coordinates:
+      // topLeft: ((-200 - 100) / 2, (-120 - 50) / 2) = (-150, -85)
+      // bottomRight: ((1200 - 100) / 2, (720 - 50) / 2) = (550, 335)
+
+      expect(bounds.x).toBe(-150)
+      expect(bounds.y).toBe(-85)
+      expect(bounds.width).toBe(700) // 550 - (-150)
+      expect(bounds.height).toBe(420) // 335 - (-85)
+    })
+
+    it('should handle zero margin', () => {
+      const { getViewportBounds } = transformState
+      const viewport = { width: 1000, height: 600 }
+
+      const bounds = getViewportBounds(viewport, 0)
+
+      // No margin, so viewport bounds are exact
+      expect(bounds.x).toBe(-50) // (0 - 100) / 2
+      expect(bounds.y).toBe(-25) // (0 - 50) / 2
+      expect(bounds.width).toBe(500) // 1000 / 2
+      expect(bounds.height).toBe(300) // 600 / 2
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle extreme zoom levels', () => {
+      const { syncWithCanvas, canvasToScreen } = transformState
+      const mockCanvas = createMockCanvasContext()
+
+      // Very small zoom
+      mockCanvas.ds.scale = 0.001
+      syncWithCanvas(mockCanvas as any)
+
+      const point1 = canvasToScreen({ x: 1000, y: 1000 })
+      expect(point1.x).toBeCloseTo(1)
+      expect(point1.y).toBeCloseTo(1)
+
+      // Very large zoom
+      mockCanvas.ds.scale = 100
+      syncWithCanvas(mockCanvas as any)
+
+      const point2 = canvasToScreen({ x: 1, y: 1 })
+      expect(point2.x).toBe(100)
+      expect(point2.y).toBe(100)
+    })
+
+    it('should handle zero scale in screenToCanvas', () => {
+      const { syncWithCanvas, screenToCanvas } = transformState
+      const mockCanvas = createMockCanvasContext()
+
+      // Scale of 0 gets converted to 1 by || operator
+      mockCanvas.ds.scale = 0
+      syncWithCanvas(mockCanvas as any)
+
+      // Should use scale of 1 due to camera.z || 1 in implementation
+      const result = screenToCanvas({ x: 100, y: 100 })
+      expect(result.x).toBe(100) // (100 - 0) / 1
+      expect(result.y).toBe(100) // (100 - 0) / 1
+    })
+  })
+})

tests-ui/tests/composables/graph/useCanvasTransformSync.test.ts

@@ -0,0 +1,239 @@
+import type { LGraphCanvas } from '@comfyorg/litegraph'
+import { mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
+
+import { useCanvasTransformSync } from '@/composables/graph/useCanvasTransformSync'
+
+// Mock LiteGraph canvas
+const createMockCanvas = (): Partial<LGraphCanvas> => ({
+  canvas: document.createElement('canvas'),
+  ds: {
+    offset: [0, 0],
+    scale: 1
+  } as any // Mock the DragAndScale type
+})
+
+describe('useCanvasTransformSync', () => {
+  let mockCanvas: LGraphCanvas
+  let syncFn: ReturnType<typeof vi.fn>
+  let callbacks: {
+    onStart: ReturnType<typeof vi.fn>
+    onUpdate: ReturnType<typeof vi.fn>
+    onStop: ReturnType<typeof vi.fn>
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    mockCanvas = createMockCanvas() as LGraphCanvas
+    syncFn = vi.fn()
+    callbacks = {
+      onStart: vi.fn(),
+      onUpdate: vi.fn(),
+      onStop: vi.fn()
+    }
+
+    // Mock requestAnimationFrame
+    global.requestAnimationFrame = vi.fn((cb) => {
+      setTimeout(cb, 16) // Simulate 60fps
+      return 1
+    })
+    global.cancelAnimationFrame = vi.fn()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('should auto-start sync when canvas is provided', async () => {
+    const { isActive } = useCanvasTransformSync(mockCanvas, syncFn, callbacks)
+
+    await nextTick()
+
+    expect(isActive.value).toBe(true)
+    expect(callbacks.onStart).toHaveBeenCalledOnce()
+    expect(syncFn).toHaveBeenCalledWith(mockCanvas)
+  })
+
+  it('should not auto-start when autoStart is false', async () => {
+    const { isActive } = useCanvasTransformSync(mockCanvas, syncFn, callbacks, {
+      autoStart: false
+    })
+
+    await nextTick()
+
+    expect(isActive.value).toBe(false)
+    expect(callbacks.onStart).not.toHaveBeenCalled()
+    expect(syncFn).not.toHaveBeenCalled()
+  })
+
+  it('should not start when canvas is null', async () => {
+    const { isActive } = useCanvasTransformSync(null, syncFn, callbacks)
+
+    await nextTick()
+
+    expect(isActive.value).toBe(false)
+    expect(callbacks.onStart).not.toHaveBeenCalled()
+  })
+
+  it('should manually start and stop sync', async () => {
+    const { isActive, startSync, stopSync } = useCanvasTransformSync(
+      mockCanvas,
+      syncFn,
+      callbacks,
+      { autoStart: false }
+    )
+
+    // Start manually
+    startSync()
+    await nextTick()
+
+    expect(isActive.value).toBe(true)
+    expect(callbacks.onStart).toHaveBeenCalledOnce()
+
+    // Stop manually
+    stopSync()
+    await nextTick()
+
+    expect(isActive.value).toBe(false)
+    expect(callbacks.onStop).toHaveBeenCalledOnce()
+  })
+
+  it('should call sync function on each frame', async () => {
+    useCanvasTransformSync(mockCanvas, syncFn, callbacks)
+
+    await nextTick()
+
+    // Advance timers to trigger additional frames (initial call + 3 more = 4 total)
+    vi.advanceTimersByTime(48) // 3 additional frames at 16ms each
+    await nextTick()
+
+    expect(syncFn).toHaveBeenCalledTimes(4) // Initial call + 3 timed calls
+    expect(syncFn).toHaveBeenCalledWith(mockCanvas)
+  })
+
+  it('should provide timing information in onUpdate callback', async () => {
+    // Mock performance.now to return predictable values
+    const mockNow = vi.spyOn(performance, 'now')
+    mockNow.mockReturnValueOnce(0).mockReturnValueOnce(5) // 5ms duration
+
+    useCanvasTransformSync(mockCanvas, syncFn, callbacks)
+
+    await nextTick()
+
+    expect(callbacks.onUpdate).toHaveBeenCalledWith(5)
+  })
+
+  it('should handle sync function that throws errors', async () => {
+    const errorSyncFn = vi.fn().mockImplementation(() => {
+      throw new Error('Sync failed')
+    })
+
+    // Creating the composable should not throw
+    expect(() => {
+      useCanvasTransformSync(mockCanvas, errorSyncFn, callbacks)
+    }).not.toThrow()
+
+    await nextTick()
+
+    // Even though sync function throws, the composable should handle it gracefully
+    expect(errorSyncFn).toHaveBeenCalled()
+    expect(callbacks.onStart).toHaveBeenCalled()
+  })
+
+  it('should not start if already active', async () => {
+    const { startSync } = useCanvasTransformSync(mockCanvas, syncFn, callbacks)
+
+    await nextTick()
+
+    // Try to start again
+    startSync()
+    await nextTick()
+
+    // Should only be called once from auto-start
+    expect(callbacks.onStart).toHaveBeenCalledOnce()
+  })
+
+  it('should not stop if already inactive', async () => {
+    const { stopSync } = useCanvasTransformSync(mockCanvas, syncFn, callbacks, {
+      autoStart: false
+    })
+
+    // Try to stop when not started
+    stopSync()
+    await nextTick()
+
+    expect(callbacks.onStop).not.toHaveBeenCalled()
+  })
+
+  it('should clean up on component unmount', async () => {
+    const TestComponent = {
+      setup() {
+        const { isActive } = useCanvasTransformSync(
+          mockCanvas,
+          syncFn,
+          callbacks
+        )
+        return { isActive }
+      },
+      template: '<div>{{ isActive }}</div>'
+    }
+
+    const wrapper = mount(TestComponent)
+    await nextTick()
+
+    expect(callbacks.onStart).toHaveBeenCalled()
+
+    // Unmount component
+    wrapper.unmount()
+    await nextTick()
+
+    expect(callbacks.onStop).toHaveBeenCalled()
+    expect(global.cancelAnimationFrame).toHaveBeenCalled()
+  })
+
+  it('should work without callbacks', async () => {
+    const { isActive } = useCanvasTransformSync(mockCanvas, syncFn)
+
+    await nextTick()
+
+    expect(isActive.value).toBe(true)
+    expect(syncFn).toHaveBeenCalledWith(mockCanvas)
+  })
+
+  it('should stop sync when canvas becomes null during sync', async () => {
+    let currentCanvas: any = mockCanvas
+    const dynamicSyncFn = vi.fn(() => {
+      // Simulate canvas becoming null during sync
+      currentCanvas = null
+    })
+
+    const { isActive } = useCanvasTransformSync(
+      currentCanvas,
+      dynamicSyncFn,
+      callbacks
+    )
+
+    await nextTick()
+
+    expect(isActive.value).toBe(true)
+
+    // Advance time to trigger sync
+    vi.advanceTimersByTime(16)
+    await nextTick()
+
+    // Should handle null canvas gracefully
+    expect(dynamicSyncFn).toHaveBeenCalled()
+  })
+
+  it('should use cancelAnimationFrame when stopping', async () => {
+    const { stopSync } = useCanvasTransformSync(mockCanvas, syncFn, callbacks)
+
+    await nextTick()
+
+    stopSync()
+
+    expect(global.cancelAnimationFrame).toHaveBeenCalledWith(1)
+  })
+})

tests-ui/tests/composables/graph/useLOD.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest'
+import { ref } from 'vue'
+
+import {
+  LODLevel,
+  LOD_THRESHOLDS,
+  supportsFeatureAtZoom,
+  useLOD
+} from '@/composables/graph/useLOD'
+
+describe('useLOD', () => {
+  describe('LOD level detection', () => {
+    it('should return MINIMAL for zoom <= 0.4', () => {
+      const zoomRef = ref(0.4)
+      const { lodLevel } = useLOD(zoomRef)
+      expect(lodLevel.value).toBe(LODLevel.MINIMAL)
+
+      zoomRef.value = 0.2
+      expect(lodLevel.value).toBe(LODLevel.MINIMAL)
+
+      zoomRef.value = 0.1
+      expect(lodLevel.value).toBe(LODLevel.MINIMAL)
+    })
+
+    it('should return REDUCED for 0.4 < zoom <= 0.8', () => {
+      const zoomRef = ref(0.5)
+      const { lodLevel } = useLOD(zoomRef)
+      expect(lodLevel.value).toBe(LODLevel.REDUCED)
+
+      zoomRef.value = 0.6
+      expect(lodLevel.value).toBe(LODLevel.REDUCED)
+
+      zoomRef.value = 0.8
+      expect(lodLevel.value).toBe(LODLevel.REDUCED)
+    })
+
+    it('should return FULL for zoom > 0.8', () => {
+      const zoomRef = ref(0.9)
+      const { lodLevel } = useLOD(zoomRef)
+      expect(lodLevel.value).toBe(LODLevel.FULL)
+
+      zoomRef.value = 1.0
+      expect(lodLevel.value).toBe(LODLevel.FULL)
+
+      zoomRef.value = 2.5
+      expect(lodLevel.value).toBe(LODLevel.FULL)
+    })
+
+    it('should be reactive to zoom changes', () => {
+      const zoomRef = ref(0.2)
+      const { lodLevel } = useLOD(zoomRef)
+
+      expect(lodLevel.value).toBe(LODLevel.MINIMAL)
+
+      zoomRef.value = 0.6
+      expect(lodLevel.value).toBe(LODLevel.REDUCED)
+
+      zoomRef.value = 1.0
+      expect(lodLevel.value).toBe(LODLevel.FULL)
+    })
+  })
+
+  describe('rendering decisions', () => {
+    it('should disable all rendering for MINIMAL LOD', () => {
+      const zoomRef = ref(0.2)
+      const {
+        shouldRenderWidgets,
+        shouldRenderSlots,
+        shouldRenderContent,
+        shouldRenderSlotLabels,
+        shouldRenderWidgetLabels
+      } = useLOD(zoomRef)
+
+      expect(shouldRenderWidgets.value).toBe(false)
+      expect(shouldRenderSlots.value).toBe(false)
+      expect(shouldRenderContent.value).toBe(false)
+      expect(shouldRenderSlotLabels.value).toBe(false)
+      expect(shouldRenderWidgetLabels.value).toBe(false)
+    })
+
+    it('should enable widgets/slots but disable labels for REDUCED LOD', () => {
+      const zoomRef = ref(0.6)
+      const {
+        shouldRenderWidgets,
+        shouldRenderSlots,
+        shouldRenderContent,
+        shouldRenderSlotLabels,
+        shouldRenderWidgetLabels
+      } = useLOD(zoomRef)
+
+      expect(shouldRenderWidgets.value).toBe(true)
+      expect(shouldRenderSlots.value).toBe(true)
+      expect(shouldRenderContent.value).toBe(false)
+      expect(shouldRenderSlotLabels.value).toBe(false)
+      expect(shouldRenderWidgetLabels.value).toBe(false)
+    })
+
+    it('should enable all rendering for FULL LOD', () => {
+      const zoomRef = ref(1.0)
+      const {
+        shouldRenderWidgets,
+        shouldRenderSlots,
+        shouldRenderContent,
+        shouldRenderSlotLabels,
+        shouldRenderWidgetLabels
+      } = useLOD(zoomRef)
+
+      expect(shouldRenderWidgets.value).toBe(true)
+      expect(shouldRenderSlots.value).toBe(true)
+      expect(shouldRenderContent.value).toBe(true)
+      expect(shouldRenderSlotLabels.value).toBe(true)
+      expect(shouldRenderWidgetLabels.value).toBe(true)
+    })
+  })
+
+  describe('CSS classes', () => {
+    it('should return correct CSS class for each LOD level', () => {
+      const zoomRef = ref(0.2)
+      const { lodCssClass } = useLOD(zoomRef)
+
+      expect(lodCssClass.value).toBe('lg-node--lod-minimal')
+
+      zoomRef.value = 0.6
+      expect(lodCssClass.value).toBe('lg-node--lod-reduced')
+
+      zoomRef.value = 1.0
+      expect(lodCssClass.value).toBe('lg-node--lod-full')
+    })
+  })
+
+  describe('essential widgets filtering', () => {
+    it('should return all widgets for FULL LOD', () => {
+      const zoomRef = ref(1.0)
+      const { getEssentialWidgets } = useLOD(zoomRef)
+
+      const widgets = [
+        { type: 'combo' },
+        { type: 'text' },
+        { type: 'button' },
+        { type: 'slider' }
+      ]
+
+      expect(getEssentialWidgets(widgets)).toEqual(widgets)
+    })
+
+    it('should return empty array for MINIMAL LOD', () => {
+      const zoomRef = ref(0.2)
+      const { getEssentialWidgets } = useLOD(zoomRef)
+
+      const widgets = [{ type: 'combo' }, { type: 'text' }, { type: 'button' }]
+
+      expect(getEssentialWidgets(widgets)).toEqual([])
+    })
+
+    it('should filter to essential types for REDUCED LOD', () => {
+      const zoomRef = ref(0.6)
+      const { getEssentialWidgets } = useLOD(zoomRef)
+
+      const widgets = [
+        { type: 'combo' },
+        { type: 'text' },
+        { type: 'button' },
+        { type: 'slider' },
+        { type: 'toggle' },
+        { type: 'number' }
+      ]
+
+      const essential = getEssentialWidgets(widgets)
+      expect(essential).toHaveLength(4)
+      expect(essential.map((w: any) => w.type)).toEqual([
+        'combo',
+        'slider',
+        'toggle',
+        'number'
+      ])
+    })
+
+    it('should handle case-insensitive widget types', () => {
+      const zoomRef = ref(0.6)
+      const { getEssentialWidgets } = useLOD(zoomRef)
+
+      const widgets = [
+        { type: 'COMBO' },
+        { type: 'Select' },
+        { type: 'TOGGLE' }
+      ]
+
+      const essential = getEssentialWidgets(widgets)
+      expect(essential).toHaveLength(3)
+    })
+
+    it('should handle widgets with undefined or missing type', () => {
+      const zoomRef = ref(0.6)
+      const { getEssentialWidgets } = useLOD(zoomRef)
+
+      const widgets = [
+        { type: 'combo' },
+        { type: undefined },
+        {},
+        { type: 'slider' }
+      ]
+
+      const essential = getEssentialWidgets(widgets)
+      expect(essential).toHaveLength(2)
+      expect(essential.map((w: any) => w.type)).toEqual(['combo', 'slider'])
+    })
+  })
+
+  describe('performance metrics', () => {
+    it('should provide debug metrics', () => {
+      const zoomRef = ref(0.6)
+      const { lodMetrics } = useLOD(zoomRef)
+
+      expect(lodMetrics.value).toEqual({
+        level: LODLevel.REDUCED,
+        zoom: 0.6,
+        widgetCount: 'full',
+        slotCount: 'full'
+      })
+    })
+
+    it('should update metrics when zoom changes', () => {
+      const zoomRef = ref(0.2)
+      const { lodMetrics } = useLOD(zoomRef)
+
+      expect(lodMetrics.value.level).toBe(LODLevel.MINIMAL)
+      expect(lodMetrics.value.widgetCount).toBe('none')
+      expect(lodMetrics.value.slotCount).toBe('none')
+
+      zoomRef.value = 1.0
+      expect(lodMetrics.value.level).toBe(LODLevel.FULL)
+      expect(lodMetrics.value.widgetCount).toBe('full')
+      expect(lodMetrics.value.slotCount).toBe('full')
+    })
+  })
+})
+
+describe('LOD_THRESHOLDS', () => {
+  it('should export correct threshold values', () => {
+    expect(LOD_THRESHOLDS.FULL_THRESHOLD).toBe(0.8)
+    expect(LOD_THRESHOLDS.REDUCED_THRESHOLD).toBe(0.4)
+    expect(LOD_THRESHOLDS.MINIMAL_THRESHOLD).toBe(0.0)
+  })
+})
+
+describe('supportsFeatureAtZoom', () => {
+  it('should return correct feature support for different zoom levels', () => {
+    expect(supportsFeatureAtZoom(1.0, 'renderWidgets')).toBe(true)
+    expect(supportsFeatureAtZoom(1.0, 'renderSlots')).toBe(true)
+    expect(supportsFeatureAtZoom(1.0, 'renderContent')).toBe(true)
+
+    expect(supportsFeatureAtZoom(0.6, 'renderWidgets')).toBe(true)
+    expect(supportsFeatureAtZoom(0.6, 'renderSlots')).toBe(true)
+    expect(supportsFeatureAtZoom(0.6, 'renderContent')).toBe(false)
+
+    expect(supportsFeatureAtZoom(0.2, 'renderWidgets')).toBe(false)
+    expect(supportsFeatureAtZoom(0.2, 'renderSlots')).toBe(false)
+    expect(supportsFeatureAtZoom(0.2, 'renderContent')).toBe(false)
+  })
+
+  it('should handle threshold boundary values correctly', () => {
+    expect(supportsFeatureAtZoom(0.8, 'renderWidgets')).toBe(true)
+    expect(supportsFeatureAtZoom(0.8, 'renderContent')).toBe(false)
+
+    expect(supportsFeatureAtZoom(0.81, 'renderContent')).toBe(true)
+
+    expect(supportsFeatureAtZoom(0.4, 'renderWidgets')).toBe(false)
+    expect(supportsFeatureAtZoom(0.41, 'renderWidgets')).toBe(true)
+  })
+})

tests-ui/tests/composables/graph/useSpatialIndex.test.ts

@@ -0,0 +1,483 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { useSpatialIndex } from '@/composables/graph/useSpatialIndex'
+
+import { createBounds } from '../../helpers/nodeTestHelpers'
+
+// Mock @vueuse/core
+vi.mock('@vueuse/core', () => ({
+  useDebounceFn: (fn: (...args: any[]) => any) => fn // Return function directly for testing
+}))
+
+describe('useSpatialIndex', () => {
+  let spatialIndex: ReturnType<typeof useSpatialIndex>
+
+  beforeEach(() => {
+    spatialIndex = useSpatialIndex()
+  })
+
+  describe('initialization', () => {
+    it('should start with null quadTree', () => {
+      expect(spatialIndex.quadTree.value).toBeNull()
+    })
+
+    it('should initialize with default bounds when first node is added', () => {
+      const { updateNode, quadTree, metrics } = spatialIndex
+
+      updateNode('node1', { x: 100, y: 100 }, { width: 200, height: 100 })
+
+      expect(quadTree.value).not.toBeNull()
+      expect(metrics.value.totalNodes).toBe(1)
+    })
+
+    it('should initialize with custom bounds', () => {
+      const { initialize, quadTree } = spatialIndex
+      const customBounds = createBounds(0, 0, 5000, 3000)
+
+      initialize(customBounds)
+
+      expect(quadTree.value).not.toBeNull()
+    })
+
+    it('should increment rebuild count on initialization', () => {
+      const { initialize, metrics } = spatialIndex
+
+      expect(metrics.value.rebuildCount).toBe(0)
+      initialize()
+      expect(metrics.value.rebuildCount).toBe(1)
+    })
+
+    it('should accept custom options', () => {
+      const customIndex = useSpatialIndex({
+        maxDepth: 8,
+        maxItemsPerNode: 6,
+        updateDebounceMs: 32
+      })
+
+      customIndex.initialize()
+
+      expect(customIndex.quadTree.value).not.toBeNull()
+    })
+  })
+
+  describe('updateNode', () => {
+    it('should add a new node to the index', () => {
+      const { updateNode, metrics } = spatialIndex
+
+      updateNode('node1', { x: 100, y: 100 }, { width: 200, height: 100 })
+
+      expect(metrics.value.totalNodes).toBe(1)
+    })
+
+    it('should update existing node position', () => {
+      const { updateNode, queryViewport } = spatialIndex
+
+      // Add node
+      updateNode('node1', { x: 100, y: 100 }, { width: 200, height: 100 })
+
+      // Move node
+      updateNode('node1', { x: 500, y: 500 }, { width: 200, height: 100 })
+
+      // Query old position - should not find node
+      const oldResults = queryViewport(createBounds(50, 50, 300, 200))
+      expect(oldResults).not.toContain('node1')
+
+      // Query new position - should find node
+      const newResults = queryViewport(createBounds(450, 450, 300, 200))
+      expect(newResults).toContain('node1')
+    })
+
+    it('should auto-initialize if quadTree is null', () => {
+      const { updateNode, quadTree } = spatialIndex
+
+      expect(quadTree.value).toBeNull()
+      updateNode('node1', { x: 0, y: 0 }, { width: 100, height: 100 })
+      expect(quadTree.value).not.toBeNull()
+    })
+  })
+
+  describe('batchUpdate', () => {
+    it('should update multiple nodes at once', () => {
+      const { batchUpdate, metrics } = spatialIndex
+
+      const updates = [
+        {
+          id: 'node1',
+          position: { x: 100, y: 100 },
+          size: { width: 200, height: 100 }
+        },
+        {
+          id: 'node2',
+          position: { x: 300, y: 300 },
+          size: { width: 150, height: 150 }
+        },
+        {
+          id: 'node3',
+          position: { x: 500, y: 200 },
+          size: { width: 100, height: 200 }
+        }
+      ]
+
+      batchUpdate(updates)
+
+      expect(metrics.value.totalNodes).toBe(3)
+    })
+
+    it('should handle empty batch', () => {
+      const { batchUpdate, metrics } = spatialIndex
+
+      batchUpdate([])
+
+      expect(metrics.value.totalNodes).toBe(0)
+    })
+
+    it('should auto-initialize if needed', () => {
+      const { batchUpdate, quadTree } = spatialIndex
+
+      expect(quadTree.value).toBeNull()
+      batchUpdate([
+        {
+          id: 'node1',
+          position: { x: 0, y: 0 },
+          size: { width: 100, height: 100 }
+        }
+      ])
+      expect(quadTree.value).not.toBeNull()
+    })
+  })
+
+  describe('removeNode', () => {
+    beforeEach(() => {
+      spatialIndex.updateNode(
+        'node1',
+        { x: 100, y: 100 },
+        { width: 200, height: 100 }
+      )
+      spatialIndex.updateNode(
+        'node2',
+        { x: 300, y: 300 },
+        { width: 200, height: 100 }
+      )
+    })
+
+    it('should remove node from index', () => {
+      const { removeNode, metrics } = spatialIndex
+
+      expect(metrics.value.totalNodes).toBe(2)
+      removeNode('node1')
+      expect(metrics.value.totalNodes).toBe(1)
+    })
+
+    it('should handle removing non-existent node', () => {
+      const { removeNode, metrics } = spatialIndex
+
+      expect(metrics.value.totalNodes).toBe(2)
+      removeNode('node999')
+      expect(metrics.value.totalNodes).toBe(2)
+    })
+
+    it('should handle removeNode when quadTree is null', () => {
+      const freshIndex = useSpatialIndex()
+
+      // Should not throw
+      expect(() => freshIndex.removeNode('node1')).not.toThrow()
+    })
+  })
+
+  describe('queryViewport', () => {
+    beforeEach(() => {
+      // Set up a grid of nodes
+      spatialIndex.updateNode(
+        'node1',
+        { x: 0, y: 0 },
+        { width: 100, height: 100 }
+      )
+      spatialIndex.updateNode(
+        'node2',
+        { x: 200, y: 0 },
+        { width: 100, height: 100 }
+      )
+      spatialIndex.updateNode(
+        'node3',
+        { x: 0, y: 200 },
+        { width: 100, height: 100 }
+      )
+      spatialIndex.updateNode(
+        'node4',
+        { x: 200, y: 200 },
+        { width: 100, height: 100 }
+      )
+    })
+
+    it('should find nodes within viewport bounds', () => {
+      const { queryViewport } = spatialIndex
+
+      // Query top-left quadrant
+      const results = queryViewport(createBounds(-50, -50, 200, 200))
+      expect(results).toContain('node1')
+      expect(results).not.toContain('node2')
+      expect(results).not.toContain('node3')
+      expect(results).not.toContain('node4')
+    })
+
+    it('should find multiple nodes in larger viewport', () => {
+      const { queryViewport } = spatialIndex
+
+      // Query entire area
+      const results = queryViewport(createBounds(-50, -50, 400, 400))
+      expect(results).toHaveLength(4)
+      expect(results).toContain('node1')
+      expect(results).toContain('node2')
+      expect(results).toContain('node3')
+      expect(results).toContain('node4')
+    })
+
+    it('should return empty array for empty region', () => {
+      const { queryViewport } = spatialIndex
+
+      const results = queryViewport(createBounds(1000, 1000, 100, 100))
+      expect(results).toEqual([])
+    })
+
+    it('should update metrics after query', () => {
+      const { queryViewport, metrics } = spatialIndex
+
+      queryViewport(createBounds(0, 0, 300, 300))
+
+      expect(metrics.value.queryTime).toBeGreaterThan(0)
+      expect(metrics.value.visibleNodes).toBe(4)
+    })
+
+    it('should handle query when quadTree is null', () => {
+      const freshIndex = useSpatialIndex()
+
+      const results = freshIndex.queryViewport(createBounds(0, 0, 100, 100))
+      expect(results).toEqual([])
+    })
+  })
+
+  describe('queryRadius', () => {
+    beforeEach(() => {
+      // Set up nodes at different distances
+      spatialIndex.updateNode(
+        'center',
+        { x: 475, y: 475 },
+        { width: 50, height: 50 }
+      )
+      spatialIndex.updateNode(
+        'near1',
+        { x: 525, y: 475 },
+        { width: 50, height: 50 }
+      )
+      spatialIndex.updateNode(
+        'near2',
+        { x: 425, y: 475 },
+        { width: 50, height: 50 }
+      )
+      spatialIndex.updateNode(
+        'far',
+        { x: 775, y: 775 },
+        { width: 50, height: 50 }
+      )
+    })
+
+    it('should find nodes within radius', () => {
+      const { queryRadius } = spatialIndex
+
+      const results = queryRadius({ x: 500, y: 500 }, 100)
+
+      expect(results).toContain('center')
+      expect(results).toContain('near1')
+      expect(results).toContain('near2')
+      expect(results).not.toContain('far')
+    })
+
+    it('should handle zero radius', () => {
+      const { queryRadius } = spatialIndex
+
+      const results = queryRadius({ x: 500, y: 500 }, 0)
+
+      // Zero radius creates a point query at (500,500)
+      // The 'center' node spans 475-525 on both axes, so it contains this point
+      expect(results).toContain('center')
+    })
+
+    it('should handle large radius', () => {
+      const { queryRadius } = spatialIndex
+
+      const results = queryRadius({ x: 500, y: 500 }, 1000)
+
+      expect(results).toHaveLength(4) // Should find all nodes
+    })
+  })
+
+  describe('clear', () => {
+    beforeEach(() => {
+      spatialIndex.updateNode(
+        'node1',
+        { x: 100, y: 100 },
+        { width: 200, height: 100 }
+      )
+      spatialIndex.updateNode(
+        'node2',
+        { x: 300, y: 300 },
+        { width: 200, height: 100 }
+      )
+    })
+
+    it('should remove all nodes', () => {
+      const { clear, metrics } = spatialIndex
+
+      expect(metrics.value.totalNodes).toBe(2)
+      clear()
+      expect(metrics.value.totalNodes).toBe(0)
+    })
+
+    it('should reset metrics', () => {
+      const { clear, queryViewport, metrics } = spatialIndex
+
+      // Do a query to set visible nodes
+      queryViewport(createBounds(0, 0, 500, 500))
+      expect(metrics.value.visibleNodes).toBe(2)
+
+      clear()
+      expect(metrics.value.visibleNodes).toBe(0)
+    })
+
+    it('should handle clear when quadTree is null', () => {
+      const freshIndex = useSpatialIndex()
+
+      expect(() => freshIndex.clear()).not.toThrow()
+    })
+  })
+
+  describe('rebuild', () => {
+    it('should rebuild index with new nodes', () => {
+      const { rebuild, metrics, queryViewport } = spatialIndex
+
+      // Add initial nodes
+      spatialIndex.updateNode(
+        'old1',
+        { x: 0, y: 0 },
+        { width: 100, height: 100 }
+      )
+      expect(metrics.value.rebuildCount).toBe(1)
+
+      // Rebuild with new set
+      const newNodes = new Map([
+        [
+          'new1',
+          { position: { x: 100, y: 100 }, size: { width: 50, height: 50 } }
+        ],
+        [
+          'new2',
+          { position: { x: 200, y: 200 }, size: { width: 50, height: 50 } }
+        ]
+      ])
+
+      rebuild(newNodes)
+
+      expect(metrics.value.totalNodes).toBe(2)
+      expect(metrics.value.rebuildCount).toBe(2)
+
+      // Old nodes should be gone
+      const oldResults = queryViewport(createBounds(-50, -50, 100, 100))
+      expect(oldResults).not.toContain('old1')
+
+      // New nodes should be findable
+      const newResults = queryViewport(createBounds(50, 50, 200, 200))
+      expect(newResults).toContain('new1')
+      expect(newResults).toContain('new2')
+    })
+
+    it('should handle empty rebuild', () => {
+      const { rebuild, metrics } = spatialIndex
+
+      rebuild(new Map())
+
+      expect(metrics.value.totalNodes).toBe(0)
+    })
+  })
+
+  describe('getDebugVisualization', () => {
+    it('should return null when debug is disabled', () => {
+      const { getDebugVisualization } = spatialIndex
+
+      expect(getDebugVisualization()).toBeNull()
+    })
+
+    it('should return debug info when enabled', () => {
+      const debugIndex = useSpatialIndex({ enableDebugVisualization: true })
+      debugIndex.initialize()
+
+      const debug = debugIndex.getDebugVisualization()
+      expect(debug).not.toBeNull()
+      expect(debug).toHaveProperty('size')
+      expect(debug).toHaveProperty('tree')
+    })
+  })
+
+  describe('metrics', () => {
+    it('should track performance metrics', () => {
+      const { metrics, updateNode, queryViewport } = spatialIndex
+
+      // Initial state
+      expect(metrics.value).toEqual({
+        queryTime: 0,
+        totalNodes: 0,
+        visibleNodes: 0,
+        treeDepth: 0,
+        rebuildCount: 0
+      })
+
+      // Add nodes
+      updateNode('node1', { x: 0, y: 0 }, { width: 100, height: 100 })
+      expect(metrics.value.totalNodes).toBe(1)
+
+      // Query
+      queryViewport(createBounds(-50, -50, 200, 200))
+      expect(metrics.value.queryTime).toBeGreaterThan(0)
+      expect(metrics.value.visibleNodes).toBe(1)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle nodes with zero size', () => {
+      const { updateNode, queryViewport } = spatialIndex
+
+      updateNode('point', { x: 100, y: 100 }, { width: 0, height: 0 })
+
+      // Should still be findable
+      const results = queryViewport(createBounds(50, 50, 100, 100))
+      expect(results).toContain('point')
+    })
+
+    it('should handle negative positions', () => {
+      const { updateNode, queryViewport } = spatialIndex
+
+      updateNode('negative', { x: -500, y: -500 }, { width: 100, height: 100 })
+
+      const results = queryViewport(createBounds(-600, -600, 200, 200))
+      expect(results).toContain('negative')
+    })
+
+    it('should handle very large nodes', () => {
+      const { updateNode, queryViewport } = spatialIndex
+
+      updateNode('huge', { x: 0, y: 0 }, { width: 5000, height: 5000 })
+
+      // Should be found even when querying small area within it
+      const results = queryViewport(createBounds(100, 100, 10, 10))
+      expect(results).toContain('huge')
+    })
+  })
+
+  describe('debouncedUpdateNode', () => {
+    it('should be available', () => {
+      const { debouncedUpdateNode } = spatialIndex
+
+      expect(debouncedUpdateNode).toBeDefined()
+      expect(typeof debouncedUpdateNode).toBe('function')
+    })
+  })
+})

tests-ui/tests/composables/graph/useTransformSettling.test.ts

@@ -0,0 +1,277 @@
+import { mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+
+import { useTransformSettling } from '@/composables/graph/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)
+
+    // 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 (default 200ms)
+    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 track pan events when trackPan is enabled', async () => {
+    const { isTransforming } = useTransformSettling(element, {
+      trackPan: true,
+      settleDelay: 200
+    })
+
+    // Pointer down should start transform
+    element.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+    await nextTick()
+    expect(isTransforming.value).toBe(true)
+
+    // Pointer move should keep it active
+    vi.advanceTimersByTime(100)
+    element.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }))
+    await nextTick()
+
+    // Should still be transforming
+    expect(isTransforming.value).toBe(true)
+
+    // Pointer up
+    element.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }))
+    await nextTick()
+
+    // Should still be transforming until settle delay
+    expect(isTransforming.value).toBe(true)
+
+    // Advance past settle delay
+    vi.advanceTimersByTime(200)
+    expect(isTransforming.value).toBe(false)
+  })
+
+  it('should not track pan events when trackPan is disabled', async () => {
+    const { isTransforming } = useTransformSettling(element, {
+      trackPan: false
+    })
+
+    // 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 handle pointer cancel events', async () => {
+    const { isTransforming } = useTransformSettling(element, {
+      trackPan: true,
+      settleDelay: 200
+    })
+
+    // Start panning
+    element.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+    await nextTick()
+    expect(isTransforming.value).toBe(true)
+
+    // Cancel instead of up
+    element.dispatchEvent(new PointerEvent('pointercancel', { bubbles: true }))
+    await nextTick()
+
+    // Should still settle normally
+    vi.advanceTimersByTime(200)
+    expect(isTransforming.value).toBe(false)
+  })
+
+  it('should work with ref target', async () => {
+    const targetRef = ref<HTMLElement | null>(null)
+    const { isTransforming } = useTransformSettling(targetRef)
+
+    // 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 throttle pointer move events', async () => {
+    const { isTransforming } = useTransformSettling(element, {
+      trackPan: true,
+      pointerMoveThrottle: 50,
+      settleDelay: 100
+    })
+
+    // Start panning
+    element.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+    await nextTick()
+
+    // Fire many pointer move events rapidly
+    for (let i = 0; i < 10; i++) {
+      element.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }))
+      vi.advanceTimersByTime(5) // 5ms between events
+    }
+    await nextTick()
+
+    // Should still be transforming
+    expect(isTransforming.value).toBe(true)
+
+    // End panning
+    element.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }))
+
+    // Advance past settle delay
+    vi.advanceTimersByTime(100)
+    expect(isTransforming.value).toBe(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, {
+          trackPan: true
+        })
+        return { isTransforming }
+      },
+      template: '<div>{{ isTransforming }}</div>'
+    }
+
+    const wrapper = mount(TestComponent)
+    await nextTick()
+
+    // Unmount component
+    wrapper.unmount()
+
+    // Should have removed all event listeners
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      'wheel',
+      expect.any(Function),
+      expect.objectContaining({ capture: true })
+    )
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      'pointerdown',
+      expect.any(Function),
+      expect.objectContaining({ capture: true })
+    )
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      'pointermove',
+      expect.any(Function),
+      expect.objectContaining({ capture: true })
+    )
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      'pointerup',
+      expect.any(Function),
+      expect.objectContaining({ capture: true })
+    )
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      'pointercancel',
+      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,
+      trackPan: true
+    })
+
+    // Check that passive option was used for appropriate events
+    expect(addEventListenerSpy).toHaveBeenCalledWith(
+      'wheel',
+      expect.any(Function),
+      expect.objectContaining({ passive: true, capture: true })
+    )
+    expect(addEventListenerSpy).toHaveBeenCalledWith(
+      'pointermove',
+      expect.any(Function),
+      expect.objectContaining({ passive: true, capture: true })
+    )
+  })
+})

tests-ui/tests/composables/graph/useWidgetRenderer.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest'
+
+import { WidgetType } from '@/components/graph/vueWidgets/widgetRegistry'
+import { useWidgetRenderer } from '@/composables/graph/useWidgetRenderer'
+
+describe('useWidgetRenderer', () => {
+  const { getWidgetComponent, shouldRenderAsVue } = useWidgetRenderer()
+
+  describe('getWidgetComponent', () => {
+    // Test number type mappings
+    describe('number types', () => {
+      it('should map number type to NUMBER widget', () => {
+        expect(getWidgetComponent('number')).toBe(WidgetType.NUMBER)
+      })
+
+      it('should map slider type to SLIDER widget', () => {
+        expect(getWidgetComponent('slider')).toBe(WidgetType.SLIDER)
+      })
+
+      it('should map INT type to INT widget', () => {
+        expect(getWidgetComponent('INT')).toBe(WidgetType.INT)
+      })
+
+      it('should map FLOAT type to FLOAT widget', () => {
+        expect(getWidgetComponent('FLOAT')).toBe(WidgetType.FLOAT)
+      })
+    })
+
+    // Test text type mappings
+    describe('text types', () => {
+      it('should map text variations to STRING widget', () => {
+        expect(getWidgetComponent('text')).toBe(WidgetType.STRING)
+        expect(getWidgetComponent('string')).toBe(WidgetType.STRING)
+        expect(getWidgetComponent('STRING')).toBe(WidgetType.STRING)
+      })
+
+      it('should map multiline text types to TEXTAREA widget', () => {
+        expect(getWidgetComponent('multiline')).toBe(WidgetType.TEXTAREA)
+        expect(getWidgetComponent('textarea')).toBe(WidgetType.TEXTAREA)
+        expect(getWidgetComponent('MARKDOWN')).toBe(WidgetType.TEXTAREA)
+        expect(getWidgetComponent('customtext')).toBe(WidgetType.TEXTAREA)
+      })
+    })
+
+    // Test selection type mappings
+    describe('selection types', () => {
+      it('should map combo types to COMBO widget', () => {
+        expect(getWidgetComponent('combo')).toBe(WidgetType.COMBO)
+        expect(getWidgetComponent('COMBO')).toBe(WidgetType.COMBO)
+      })
+    })
+
+    // Test boolean type mappings
+    describe('boolean types', () => {
+      it('should map boolean types to appropriate widgets', () => {
+        expect(getWidgetComponent('toggle')).toBe(WidgetType.TOGGLESWITCH)
+        expect(getWidgetComponent('boolean')).toBe(WidgetType.BOOLEAN)
+        expect(getWidgetComponent('BOOLEAN')).toBe(WidgetType.BOOLEAN)
+      })
+    })
+
+    // Test advanced widget mappings
+    describe('advanced widgets', () => {
+      it('should map color types to COLOR widget', () => {
+        expect(getWidgetComponent('color')).toBe(WidgetType.COLOR)
+        expect(getWidgetComponent('COLOR')).toBe(WidgetType.COLOR)
+      })
+
+      it('should map image types to IMAGE widget', () => {
+        expect(getWidgetComponent('image')).toBe(WidgetType.IMAGE)
+        expect(getWidgetComponent('IMAGE')).toBe(WidgetType.IMAGE)
+      })
+
+      it('should map file types to FILEUPLOAD widget', () => {
+        expect(getWidgetComponent('file')).toBe(WidgetType.FILEUPLOAD)
+        expect(getWidgetComponent('FILEUPLOAD')).toBe(WidgetType.FILEUPLOAD)
+      })
+
+      it('should map button types to BUTTON widget', () => {
+        expect(getWidgetComponent('button')).toBe(WidgetType.BUTTON)
+        expect(getWidgetComponent('BUTTON')).toBe(WidgetType.BUTTON)
+      })
+    })
+
+    // Test fallback behavior
+    describe('fallback behavior', () => {
+      it('should return STRING widget for unknown types', () => {
+        expect(getWidgetComponent('unknown')).toBe(WidgetType.STRING)
+        expect(getWidgetComponent('custom_widget')).toBe(WidgetType.STRING)
+        expect(getWidgetComponent('')).toBe(WidgetType.STRING)
+      })
+
+      it('should return STRING widget for unmapped but valid types', () => {
+        expect(getWidgetComponent('datetime')).toBe(WidgetType.STRING)
+        expect(getWidgetComponent('json')).toBe(WidgetType.STRING)
+      })
+    })
+  })
+
+  describe('shouldRenderAsVue', () => {
+    it('should return false for widgets marked as canvas-only', () => {
+      const widget = { type: 'text', options: { canvasOnly: true } }
+      expect(shouldRenderAsVue(widget)).toBe(false)
+    })
+
+    it('should return false for widgets without a type', () => {
+      const widget = { options: {} }
+      expect(shouldRenderAsVue(widget)).toBe(false)
+    })
+
+    it('should return true for widgets with mapped types', () => {
+      expect(shouldRenderAsVue({ type: 'text' })).toBe(true)
+      expect(shouldRenderAsVue({ type: 'number' })).toBe(true)
+      expect(shouldRenderAsVue({ type: 'combo' })).toBe(true)
+    })
+
+    it('should return true even for unknown types (fallback to STRING)', () => {
+      expect(shouldRenderAsVue({ type: 'unknown_type' })).toBe(true)
+    })
+
+    it('should respect options while checking type', () => {
+      const widget = { type: 'text', options: { someOption: 'value' } }
+      expect(shouldRenderAsVue(widget)).toBe(true)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle widgets with empty options', () => {
+      const widget = { type: 'text', options: {} }
+      expect(shouldRenderAsVue(widget)).toBe(true)
+    })
+
+    it('should handle case sensitivity correctly', () => {
+      // Test that both lowercase and uppercase work
+      expect(getWidgetComponent('string')).toBe(WidgetType.STRING)
+      expect(getWidgetComponent('STRING')).toBe(WidgetType.STRING)
+      expect(getWidgetComponent('combo')).toBe(WidgetType.COMBO)
+      expect(getWidgetComponent('COMBO')).toBe(WidgetType.COMBO)
+    })
+  })
+})

tests-ui/tests/composables/graph/useWidgetValue.test.ts

@@ -0,0 +1,502 @@
+import {
+  type MockedFunction,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi
+} from 'vitest'
+import { ref } from 'vue'
+
+import {
+  useBooleanWidgetValue,
+  useNumberWidgetValue,
+  useStringWidgetValue,
+  useWidgetValue
+} from '@/composables/graph/useWidgetValue'
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
+
+describe('useWidgetValue', () => {
+  let mockWidget: SimplifiedWidget<string>
+  let mockEmit: MockedFunction<(event: 'update:modelValue', value: any) => void>
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    mockWidget = {
+      name: 'testWidget',
+      type: 'string',
+      value: 'initial',
+      callback: vi.fn()
+    }
+    mockEmit = vi.fn()
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    consoleWarnSpy.mockRestore()
+  })
+
+  describe('basic functionality', () => {
+    it('should initialize with modelValue', () => {
+      const { localValue } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'test value',
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      expect(localValue.value).toBe('test value')
+    })
+
+    it('should use defaultValue when modelValue is null', () => {
+      const { localValue } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: null as any,
+        defaultValue: 'default',
+        emit: mockEmit
+      })
+
+      expect(localValue.value).toBe('default')
+    })
+
+    it('should use defaultValue when modelValue is undefined', () => {
+      const { localValue } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: undefined as any,
+        defaultValue: 'default',
+        emit: mockEmit
+      })
+
+      expect(localValue.value).toBe('default')
+    })
+  })
+
+  describe('onChange handler', () => {
+    it('should update localValue immediately', () => {
+      const { localValue, onChange } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'initial',
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      onChange('new value')
+      expect(localValue.value).toBe('new value')
+    })
+
+    it('should emit update:modelValue event', () => {
+      const { onChange } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'initial',
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      onChange('new value')
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 'new value')
+    })
+
+    it('should call widget callback if it exists', () => {
+      const { onChange } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'initial',
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      onChange('new value')
+      expect(mockWidget.callback).toHaveBeenCalledWith('new value')
+    })
+
+    it('should not error if widget callback is undefined', () => {
+      const widgetWithoutCallback = { ...mockWidget, callback: undefined }
+      const { onChange } = useWidgetValue({
+        widget: widgetWithoutCallback,
+        modelValue: 'initial',
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      expect(() => onChange('new value')).not.toThrow()
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 'new value')
+    })
+
+    it('should handle null values', () => {
+      const { localValue, onChange } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'initial',
+        defaultValue: 'default',
+        emit: mockEmit
+      })
+
+      onChange(null as any)
+      expect(localValue.value).toBe('default')
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 'default')
+    })
+
+    it('should handle undefined values', () => {
+      const { localValue, onChange } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'initial',
+        defaultValue: 'default',
+        emit: mockEmit
+      })
+
+      onChange(undefined as any)
+      expect(localValue.value).toBe('default')
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 'default')
+    })
+  })
+
+  describe('type safety', () => {
+    it('should handle type mismatches with warning', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'numberWidget',
+        type: 'number',
+        value: 42,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useWidgetValue({
+        widget: numberWidget,
+        modelValue: 10,
+        defaultValue: 0,
+        emit: mockEmit
+      })
+
+      // Pass string to number widget
+      onChange('not a number' as any)
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'useWidgetValue: Type mismatch for widget numberWidget. Expected number, got string'
+      )
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 0) // Uses defaultValue
+    })
+
+    it('should accept values of matching type', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'numberWidget',
+        type: 'number',
+        value: 42,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useWidgetValue({
+        widget: numberWidget,
+        modelValue: 10,
+        defaultValue: 0,
+        emit: mockEmit
+      })
+
+      onChange(25)
+      expect(consoleWarnSpy).not.toHaveBeenCalled()
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 25)
+    })
+  })
+
+  describe('transform function', () => {
+    it('should apply transform function to new values', () => {
+      const transform = vi.fn((value: string) => value.toUpperCase())
+      const { onChange } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'initial',
+        defaultValue: '',
+        emit: mockEmit,
+        transform
+      })
+
+      onChange('hello')
+      expect(transform).toHaveBeenCalledWith('hello')
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 'HELLO')
+    })
+
+    it('should skip type checking when transform is provided', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'numberWidget',
+        type: 'number',
+        value: 42,
+        callback: vi.fn()
+      }
+
+      const transform = (value: string) => parseInt(value, 10) || 0
+      const { onChange } = useWidgetValue({
+        widget: numberWidget,
+        modelValue: 10,
+        defaultValue: 0,
+        emit: mockEmit,
+        transform
+      })
+
+      onChange('123')
+      expect(consoleWarnSpy).not.toHaveBeenCalled()
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 123)
+    })
+  })
+
+  describe('external updates', () => {
+    it('should update localValue when modelValue changes', async () => {
+      const modelValue = ref('initial')
+      const { localValue } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: modelValue.value,
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      expect(localValue.value).toBe('initial')
+
+      // Simulate parent updating modelValue
+      modelValue.value = 'updated externally'
+
+      // Re-create the composable with new value (simulating prop change)
+      const { localValue: newLocalValue } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: modelValue.value,
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      expect(newLocalValue.value).toBe('updated externally')
+    })
+
+    it('should handle external null values', async () => {
+      const modelValue = ref<string | null>('initial')
+      const { localValue } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: modelValue.value!,
+        defaultValue: 'default',
+        emit: mockEmit
+      })
+
+      expect(localValue.value).toBe('initial')
+
+      // Simulate external update to null
+      modelValue.value = null
+      const { localValue: newLocalValue } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: modelValue.value as any,
+        defaultValue: 'default',
+        emit: mockEmit
+      })
+
+      expect(newLocalValue.value).toBe('default')
+    })
+  })
+
+  describe('useStringWidgetValue helper', () => {
+    it('should handle string values correctly', () => {
+      const stringWidget: SimplifiedWidget<string> = {
+        name: 'textWidget',
+        type: 'string',
+        value: 'hello',
+        callback: vi.fn()
+      }
+
+      const { localValue, onChange } = useStringWidgetValue(
+        stringWidget,
+        'initial',
+        mockEmit
+      )
+
+      expect(localValue.value).toBe('initial')
+
+      onChange('new string')
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 'new string')
+    })
+
+    it('should transform undefined to empty string', () => {
+      const stringWidget: SimplifiedWidget<string> = {
+        name: 'textWidget',
+        type: 'string',
+        value: '',
+        callback: vi.fn()
+      }
+
+      const { onChange } = useStringWidgetValue(stringWidget, '', mockEmit)
+
+      onChange(undefined as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', '')
+    })
+
+    it('should convert non-string values to string', () => {
+      const stringWidget: SimplifiedWidget<string> = {
+        name: 'textWidget',
+        type: 'string',
+        value: '',
+        callback: vi.fn()
+      }
+
+      const { onChange } = useStringWidgetValue(stringWidget, '', mockEmit)
+
+      onChange(123 as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', '123')
+    })
+  })
+
+  describe('useNumberWidgetValue helper', () => {
+    it('should handle number values correctly', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'sliderWidget',
+        type: 'number',
+        value: 50,
+        callback: vi.fn()
+      }
+
+      const { localValue, onChange } = useNumberWidgetValue(
+        numberWidget,
+        25,
+        mockEmit
+      )
+
+      expect(localValue.value).toBe(25)
+
+      onChange(75)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 75)
+    })
+
+    it('should handle array values from PrimeVue Slider', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'sliderWidget',
+        type: 'number',
+        value: 50,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useNumberWidgetValue(numberWidget, 25, mockEmit)
+
+      // PrimeVue Slider can emit number[]
+      onChange([42, 100] as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 42)
+    })
+
+    it('should handle empty array', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'sliderWidget',
+        type: 'number',
+        value: 50,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useNumberWidgetValue(numberWidget, 25, mockEmit)
+
+      onChange([] as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 0)
+    })
+
+    it('should convert string numbers', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'numberWidget',
+        type: 'number',
+        value: 0,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useNumberWidgetValue(numberWidget, 0, mockEmit)
+
+      onChange('42' as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 42)
+    })
+
+    it('should handle invalid number conversions', () => {
+      const numberWidget: SimplifiedWidget<number> = {
+        name: 'numberWidget',
+        type: 'number',
+        value: 0,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useNumberWidgetValue(numberWidget, 0, mockEmit)
+
+      onChange('not-a-number' as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', 0)
+    })
+  })
+
+  describe('useBooleanWidgetValue helper', () => {
+    it('should handle boolean values correctly', () => {
+      const boolWidget: SimplifiedWidget<boolean> = {
+        name: 'toggleWidget',
+        type: 'boolean',
+        value: false,
+        callback: vi.fn()
+      }
+
+      const { localValue, onChange } = useBooleanWidgetValue(
+        boolWidget,
+        true,
+        mockEmit
+      )
+
+      expect(localValue.value).toBe(true)
+
+      onChange(false)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', false)
+    })
+
+    it('should convert truthy values to true', () => {
+      const boolWidget: SimplifiedWidget<boolean> = {
+        name: 'toggleWidget',
+        type: 'boolean',
+        value: false,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useBooleanWidgetValue(boolWidget, false, mockEmit)
+
+      onChange('truthy' as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', true)
+    })
+
+    it('should convert falsy values to false', () => {
+      const boolWidget: SimplifiedWidget<boolean> = {
+        name: 'toggleWidget',
+        type: 'boolean',
+        value: false,
+        callback: vi.fn()
+      }
+
+      const { onChange } = useBooleanWidgetValue(boolWidget, true, mockEmit)
+
+      onChange(0 as any)
+      expect(mockEmit).toHaveBeenCalledWith('update:modelValue', false)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle rapid onChange calls', () => {
+      const { onChange } = useWidgetValue({
+        widget: mockWidget,
+        modelValue: 'initial',
+        defaultValue: '',
+        emit: mockEmit
+      })
+
+      onChange('value1')
+      onChange('value2')
+      onChange('value3')
+
+      expect(mockEmit).toHaveBeenCalledTimes(3)
+      expect(mockEmit).toHaveBeenNthCalledWith(1, 'update:modelValue', 'value1')
+      expect(mockEmit).toHaveBeenNthCalledWith(2, 'update:modelValue', 'value2')
+      expect(mockEmit).toHaveBeenNthCalledWith(3, 'update:modelValue', 'value3')
+    })
+
+    it('should handle widget with all properties undefined', () => {
+      const minimalWidget = {
+        name: 'minimal',
+        type: 'unknown'
+      } as SimplifiedWidget<any>
+
+      const { localValue, onChange } = useWidgetValue({
+        widget: minimalWidget,
+        modelValue: 'test',
+        defaultValue: 'default',
+        emit: mockEmit
+      })
+
+      expect(localValue.value).toBe('test')
+      expect(() => onChange('new')).not.toThrow()
+    })
+  })
+})

tests-ui/tests/helpers/nodeTestHelpers.ts

@@ -0,0 +1,76 @@
+// Simple mock objects for testing Vue node components
+export function createMockWidget(overrides: any = {}) {
+  return {
+    name: 'test_widget',
+    type: 'number',
+    value: 0,
+    options: {},
+    callback: null,
+    ...overrides
+  }
+}
+
+// Create mock VueNodeData for testing
+export function createMockVueNodeData(overrides: any = {}) {
+  return {
+    id: 'node-1',
+    type: 'TestNode',
+    title: 'Test Node',
+    mode: 0,
+    selected: false,
+    executing: false,
+    widgets: [],
+    inputs: [],
+    outputs: [],
+    ...overrides
+  }
+}
+
+// Create a mock canvas context for transform testing
+export function createMockCanvasContext() {
+  return {
+    canvas: {
+      width: 1280,
+      height: 720,
+      getBoundingClientRect: () => ({
+        left: 0,
+        top: 0,
+        width: 1280,
+        height: 720,
+        right: 1280,
+        bottom: 720,
+        x: 0,
+        y: 0
+      })
+    },
+    ds: {
+      offset: [0, 0],
+      scale: 1
+    }
+  }
+}
+
+// Helper to create bounds for spatial testing
+export function createBounds(
+  x: number,
+  y: number,
+  width: number,
+  height: number
+) {
+  return {
+    x,
+    y,
+    width,
+    height
+  }
+}
+
+// Helper to create a position
+export function createPosition(x: number, y: number) {
+  return { x, y }
+}
+
+// Helper to create a size
+export function createSize(width: number, height: number) {
+  return { width, height }
+}

tests-ui/tests/performance/QuadTreeBenchmark.ts

@@ -0,0 +1,225 @@
+/**
+ * Performance benchmark for QuadTree vs linear culling
+ * Measures query performance at different node counts and zoom levels
+ */
+import { type Bounds, QuadTree } from '../../../src/utils/spatial/QuadTree'
+
+export interface BenchmarkResult {
+  nodeCount: number
+  queryCount: number
+  linearTime: number
+  quadTreeTime: number
+  speedup: number
+  culledPercentage: number
+}
+
+export interface NodeData {
+  id: string
+  bounds: Bounds
+}
+
+export class QuadTreeBenchmark {
+  private worldBounds: Bounds = {
+    x: -5000,
+    y: -5000,
+    width: 10000,
+    height: 10000
+  }
+
+  // Generate random nodes with realistic clustering
+  generateNodes(count: number): NodeData[] {
+    const nodes: NodeData[] = []
+
+    for (let i = 0; i < count; i++) {
+      // 70% clustered, 30% scattered
+      const isClustered = Math.random() < 0.7
+
+      let x: number, y: number
+
+      if (isClustered) {
+        // Pick a cluster center
+        const clusterX = (Math.random() - 0.5) * 8000
+        const clusterY = (Math.random() - 0.5) * 8000
+
+        // Add node near cluster with gaussian distribution
+        x = clusterX + (Math.random() - 0.5) * 500
+        y = clusterY + (Math.random() - 0.5) * 500
+      } else {
+        // Scattered randomly
+        x = (Math.random() - 0.5) * 9000
+        y = (Math.random() - 0.5) * 9000
+      }
+
+      nodes.push({
+        id: `node_${i}`,
+        bounds: {
+          x,
+          y,
+          width: 200 + Math.random() * 100,
+          height: 100 + Math.random() * 50
+        }
+      })
+    }
+
+    return nodes
+  }
+
+  // Linear viewport culling (baseline)
+  linearCulling(nodes: NodeData[], viewport: Bounds): string[] {
+    const visible: string[] = []
+
+    for (const node of nodes) {
+      if (this.boundsIntersect(node.bounds, viewport)) {
+        visible.push(node.id)
+      }
+    }
+
+    return visible
+  }
+
+  // QuadTree viewport culling
+  quadTreeCulling(quadTree: QuadTree<string>, viewport: Bounds): string[] {
+    return quadTree.query(viewport)
+  }
+
+  // Check if two bounds intersect
+  private boundsIntersect(a: Bounds, b: Bounds): boolean {
+    return !(
+      a.x + a.width < b.x ||
+      b.x + b.width < a.x ||
+      a.y + a.height < b.y ||
+      b.y + b.height < a.y
+    )
+  }
+
+  // Run benchmark for specific configuration
+  runBenchmark(
+    nodeCount: number,
+    viewportSize: { width: number; height: number },
+    queryCount: number = 100
+  ): BenchmarkResult {
+    // Generate nodes
+    const nodes = this.generateNodes(nodeCount)
+
+    // Build QuadTree
+    const quadTree = new QuadTree<string>(this.worldBounds, {
+      maxDepth: Math.ceil(Math.log2(nodeCount / 4)),
+      maxItemsPerNode: 4
+    })
+
+    for (const node of nodes) {
+      quadTree.insert(node.id, node.bounds, node.id)
+    }
+
+    // Generate random viewports for testing
+    const viewports: Bounds[] = []
+    for (let i = 0; i < queryCount; i++) {
+      const x =
+        (Math.random() - 0.5) * (this.worldBounds.width - viewportSize.width)
+      const y =
+        (Math.random() - 0.5) * (this.worldBounds.height - viewportSize.height)
+      viewports.push({
+        x,
+        y,
+        width: viewportSize.width,
+        height: viewportSize.height
+      })
+    }
+
+    // Benchmark linear culling
+    const linearStart = performance.now()
+    let linearVisibleTotal = 0
+    for (const viewport of viewports) {
+      const visible = this.linearCulling(nodes, viewport)
+      linearVisibleTotal += visible.length
+    }
+    const linearTime = performance.now() - linearStart
+
+    // Benchmark QuadTree culling
+    const quadTreeStart = performance.now()
+    let quadTreeVisibleTotal = 0
+    for (const viewport of viewports) {
+      const visible = this.quadTreeCulling(quadTree, viewport)
+      quadTreeVisibleTotal += visible.length
+    }
+    const quadTreeTime = performance.now() - quadTreeStart
+
+    // Calculate metrics
+    const avgVisible = linearVisibleTotal / queryCount
+    const culledPercentage = ((nodeCount - avgVisible) / nodeCount) * 100
+
+    return {
+      nodeCount,
+      queryCount,
+      linearTime,
+      quadTreeTime,
+      speedup: linearTime / quadTreeTime,
+      culledPercentage
+    }
+  }
+
+  // Run comprehensive benchmark suite
+  runBenchmarkSuite(): BenchmarkResult[] {
+    const nodeCounts = [50, 100, 200, 500, 1000, 2000, 5000]
+    const viewportSizes = [
+      { width: 1920, height: 1080 }, // Full HD
+      { width: 800, height: 600 }, // Zoomed in
+      { width: 4000, height: 3000 } // Zoomed out
+    ]
+
+    const results: BenchmarkResult[] = []
+
+    for (const nodeCount of nodeCounts) {
+      for (const viewportSize of viewportSizes) {
+        const result = this.runBenchmark(nodeCount, viewportSize)
+        results.push(result)
+
+        console.log(
+          `Nodes: ${nodeCount}, ` +
+            `Viewport: ${viewportSize.width}x${viewportSize.height}, ` +
+            `Linear: ${result.linearTime.toFixed(2)}ms, ` +
+            `QuadTree: ${result.quadTreeTime.toFixed(2)}ms, ` +
+            `Speedup: ${result.speedup.toFixed(2)}x, ` +
+            `Culled: ${result.culledPercentage.toFixed(1)}%`
+        )
+      }
+    }
+
+    return results
+  }
+
+  // Find optimal maxDepth for given node count
+  findOptimalDepth(nodeCount: number): number {
+    const nodes = this.generateNodes(nodeCount)
+    const viewport = { x: 0, y: 0, width: 1920, height: 1080 }
+
+    let bestDepth = 1
+    let bestTime = Infinity
+
+    for (let depth = 1; depth <= 10; depth++) {
+      const quadTree = new QuadTree<string>(this.worldBounds, {
+        maxDepth: depth,
+        maxItemsPerNode: 4
+      })
+
+      // Build tree
+      for (const node of nodes) {
+        quadTree.insert(node.id, node.bounds, node.id)
+      }
+
+      // Measure query time
+      const start = performance.now()
+      for (let i = 0; i < 100; i++) {
+        quadTree.query(viewport)
+      }
+      const time = performance.now() - start
+
+      if (time < bestTime) {
+        bestTime = time
+        bestDepth = depth
+      }
+    }
+
+    return bestDepth
+  }
+}

tests-ui/tests/performance/spatialIndexPerformance.test.ts

@@ -0,0 +1,402 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { useSpatialIndex } from '@/composables/graph/useSpatialIndex'
+import type { Bounds } from '@/utils/spatial/QuadTree'
+
+describe('Spatial Index Performance', () => {
+  let spatialIndex: ReturnType<typeof useSpatialIndex>
+
+  beforeEach(() => {
+    spatialIndex = useSpatialIndex({
+      maxDepth: 6,
+      maxItemsPerNode: 4,
+      updateDebounceMs: 0 // Disable debouncing for tests
+    })
+  })
+
+  describe('large scale operations', () => {
+    it('should handle 1000 node insertions efficiently', () => {
+      const startTime = performance.now()
+
+      // Generate 1000 nodes in a realistic distribution
+      const nodes = Array.from({ length: 1000 }, (_, i) => ({
+        id: `node${i}`,
+        position: {
+          x: (Math.random() - 0.5) * 10000,
+          y: (Math.random() - 0.5) * 10000
+        },
+        size: {
+          width: 150 + Math.random() * 100,
+          height: 100 + Math.random() * 50
+        }
+      }))
+
+      spatialIndex.batchUpdate(nodes)
+
+      const insertTime = performance.now() - startTime
+
+      // Should insert 1000 nodes in under 100ms
+      expect(insertTime).toBeLessThan(100)
+      expect(spatialIndex.metrics.value.totalNodes).toBe(1000)
+    })
+
+    it('should maintain fast viewport queries under load', () => {
+      // First populate with many nodes
+      const nodes = Array.from({ length: 1000 }, (_, i) => ({
+        id: `node${i}`,
+        position: {
+          x: (Math.random() - 0.5) * 10000,
+          y: (Math.random() - 0.5) * 10000
+        },
+        size: { width: 200, height: 100 }
+      }))
+      spatialIndex.batchUpdate(nodes)
+
+      // Now benchmark viewport queries
+      const queryCount = 100
+      const viewportBounds: Bounds = {
+        x: -960,
+        y: -540,
+        width: 1920,
+        height: 1080
+      }
+
+      const startTime = performance.now()
+
+      for (let i = 0; i < queryCount; i++) {
+        // Vary viewport position to test different tree regions
+        const offsetX = (i % 10) * 500
+        const offsetY = Math.floor(i / 10) * 300
+        spatialIndex.queryViewport({
+          x: viewportBounds.x + offsetX,
+          y: viewportBounds.y + offsetY,
+          width: viewportBounds.width,
+          height: viewportBounds.height
+        })
+      }
+
+      const totalQueryTime = performance.now() - startTime
+      const avgQueryTime = totalQueryTime / queryCount
+
+      // Each query should take less than 2ms on average
+      expect(avgQueryTime).toBeLessThan(2)
+      expect(totalQueryTime).toBeLessThan(100) // 100 queries in under 100ms
+    })
+
+    it('should demonstrate performance advantage over linear search', () => {
+      // Create test data
+      const nodeCount = 500
+      const nodes = Array.from({ length: nodeCount }, (_, i) => ({
+        id: `node${i}`,
+        position: {
+          x: (Math.random() - 0.5) * 8000,
+          y: (Math.random() - 0.5) * 8000
+        },
+        size: { width: 200, height: 100 }
+      }))
+
+      // Populate spatial index
+      spatialIndex.batchUpdate(nodes)
+
+      const viewport: Bounds = { x: -500, y: -300, width: 1000, height: 600 }
+      const queryCount = 50
+
+      // Benchmark spatial index queries
+      const spatialStartTime = performance.now()
+      for (let i = 0; i < queryCount; i++) {
+        spatialIndex.queryViewport(viewport)
+      }
+      const spatialTime = performance.now() - spatialStartTime
+
+      // Benchmark linear search equivalent
+      const linearStartTime = performance.now()
+      for (let i = 0; i < queryCount; i++) {
+        nodes.filter((node) => {
+          const nodeRight = node.position.x + node.size.width
+          const nodeBottom = node.position.y + node.size.height
+          const viewportRight = viewport.x + viewport.width
+          const viewportBottom = viewport.y + viewport.height
+
+          return !(
+            nodeRight < viewport.x ||
+            node.position.x > viewportRight ||
+            nodeBottom < viewport.y ||
+            node.position.y > viewportBottom
+          )
+        })
+      }
+      const linearTime = performance.now() - linearStartTime
+
+      // Spatial index should be faster than linear search
+      const speedup = linearTime / spatialTime
+      // In some environments, speedup may be less due to small dataset
+      // Just ensure spatial is not significantly slower (at least 10% of linear speed)
+      expect(speedup).toBeGreaterThan(0.1)
+
+      // Both should find roughly the same number of nodes
+      const spatialResults = spatialIndex.queryViewport(viewport)
+      const linearResults = nodes.filter((node) => {
+        const nodeRight = node.position.x + node.size.width
+        const nodeBottom = node.position.y + node.size.height
+        const viewportRight = viewport.x + viewport.width
+        const viewportBottom = viewport.y + viewport.height
+
+        return !(
+          nodeRight < viewport.x ||
+          node.position.x > viewportRight ||
+          nodeBottom < viewport.y ||
+          node.position.y > viewportBottom
+        )
+      })
+
+      // Results should be similar (within 10% due to QuadTree boundary effects)
+      const resultsDiff = Math.abs(spatialResults.length - linearResults.length)
+      const maxDiff =
+        Math.max(spatialResults.length, linearResults.length) * 0.1
+      expect(resultsDiff).toBeLessThan(maxDiff)
+    })
+  })
+
+  describe('update performance', () => {
+    it('should handle frequent position updates efficiently', () => {
+      // Add initial nodes
+      const nodeCount = 200
+      const initialNodes = Array.from({ length: nodeCount }, (_, i) => ({
+        id: `node${i}`,
+        position: { x: i * 100, y: i * 50 },
+        size: { width: 200, height: 100 }
+      }))
+      spatialIndex.batchUpdate(initialNodes)
+
+      // Benchmark frequent updates (simulating animation/dragging)
+      const updateCount = 100
+      const startTime = performance.now()
+
+      for (let frame = 0; frame < updateCount; frame++) {
+        // Update a subset of nodes each frame
+        for (let i = 0; i < 20; i++) {
+          const nodeId = `node${i}`
+          spatialIndex.updateNode(
+            nodeId,
+            {
+              x: i * 100 + Math.sin(frame * 0.1) * 50,
+              y: i * 50 + Math.cos(frame * 0.1) * 30
+            },
+            { width: 200, height: 100 }
+          )
+        }
+      }
+
+      const updateTime = performance.now() - startTime
+      const avgFrameTime = updateTime / updateCount
+
+      // Should maintain 60fps (16.67ms per frame) with 20 node updates per frame
+      expect(avgFrameTime).toBeLessThan(8) // Conservative target: 8ms per frame
+    })
+
+    it('should handle node additions and removals efficiently', () => {
+      const startTime = performance.now()
+
+      // Add nodes
+      for (let i = 0; i < 100; i++) {
+        spatialIndex.updateNode(
+          `node${i}`,
+          { x: Math.random() * 1000, y: Math.random() * 1000 },
+          { width: 200, height: 100 }
+        )
+      }
+
+      // Remove half of them
+      for (let i = 0; i < 50; i++) {
+        spatialIndex.removeNode(`node${i}`)
+      }
+
+      // Add new ones
+      for (let i = 100; i < 150; i++) {
+        spatialIndex.updateNode(
+          `node${i}`,
+          { x: Math.random() * 1000, y: Math.random() * 1000 },
+          { width: 200, height: 100 }
+        )
+      }
+
+      const totalTime = performance.now() - startTime
+
+      // All operations should complete quickly
+      expect(totalTime).toBeLessThan(50)
+      expect(spatialIndex.metrics.value.totalNodes).toBe(100) // 50 remaining + 50 new
+    })
+  })
+
+  describe('memory and scaling', () => {
+    it('should scale efficiently with increasing node counts', () => {
+      const nodeCounts = [100, 200, 500, 1000]
+      const queryTimes: number[] = []
+
+      for (const nodeCount of nodeCounts) {
+        // Create fresh spatial index for each test
+        const testIndex = useSpatialIndex({ updateDebounceMs: 0 })
+
+        // Populate with nodes
+        const nodes = Array.from({ length: nodeCount }, (_, i) => ({
+          id: `node${i}`,
+          position: {
+            x: (Math.random() - 0.5) * 10000,
+            y: (Math.random() - 0.5) * 10000
+          },
+          size: { width: 200, height: 100 }
+        }))
+        testIndex.batchUpdate(nodes)
+
+        // Benchmark query time
+        const viewport: Bounds = { x: -500, y: -300, width: 1000, height: 600 }
+        const startTime = performance.now()
+
+        for (let i = 0; i < 10; i++) {
+          testIndex.queryViewport(viewport)
+        }
+
+        const avgTime = (performance.now() - startTime) / 10
+        queryTimes.push(avgTime)
+      }
+
+      // Query time should scale logarithmically, not linearly
+      // The ratio between 1000 nodes and 100 nodes should be less than 5x
+      const ratio100to1000 = queryTimes[3] / queryTimes[0]
+      expect(ratio100to1000).toBeLessThan(5)
+
+      // All query times should be reasonable
+      queryTimes.forEach((time) => {
+        expect(time).toBeLessThan(5) // Each query under 5ms
+      })
+    })
+
+    it('should handle edge cases without performance degradation', () => {
+      // Test with very large nodes
+      spatialIndex.updateNode(
+        'huge-node',
+        { x: -1000, y: -1000 },
+        { width: 5000, height: 3000 }
+      )
+
+      // Test with many tiny nodes
+      for (let i = 0; i < 100; i++) {
+        spatialIndex.updateNode(
+          `tiny-${i}`,
+          { x: Math.random() * 100, y: Math.random() * 100 },
+          { width: 1, height: 1 }
+        )
+      }
+
+      // Test with nodes at extreme coordinates
+      spatialIndex.updateNode(
+        'extreme-pos',
+        { x: 50000, y: -50000 },
+        { width: 200, height: 100 }
+      )
+
+      spatialIndex.updateNode(
+        'extreme-neg',
+        { x: -50000, y: 50000 },
+        { width: 200, height: 100 }
+      )
+
+      // Queries should still be fast
+      const startTime = performance.now()
+      for (let i = 0; i < 20; i++) {
+        spatialIndex.queryViewport({
+          x: Math.random() * 1000 - 500,
+          y: Math.random() * 1000 - 500,
+          width: 1000,
+          height: 600
+        })
+      }
+      const queryTime = performance.now() - startTime
+
+      expect(queryTime).toBeLessThan(20) // 20 queries in under 20ms
+    })
+  })
+
+  describe('realistic workflow scenarios', () => {
+    it('should handle typical ComfyUI workflow performance', () => {
+      // Simulate a large ComfyUI workflow with clustered nodes
+      const clusters = [
+        { center: { x: 0, y: 0 }, nodeCount: 50 },
+        { center: { x: 2000, y: 0 }, nodeCount: 30 },
+        { center: { x: 4000, y: 1000 }, nodeCount: 40 },
+        { center: { x: 0, y: 2000 }, nodeCount: 35 }
+      ]
+
+      let nodeId = 0
+      const allNodes: Array<{
+        id: string
+        position: { x: number; y: number }
+        size: { width: number; height: number }
+      }> = []
+
+      // Create clustered nodes (realistic for ComfyUI workflows)
+      clusters.forEach((cluster) => {
+        for (let i = 0; i < cluster.nodeCount; i++) {
+          allNodes.push({
+            id: `node${nodeId++}`,
+            position: {
+              x: cluster.center.x + (Math.random() - 0.5) * 800,
+              y: cluster.center.y + (Math.random() - 0.5) * 600
+            },
+            size: {
+              width: 150 + Math.random() * 100,
+              height: 100 + Math.random() * 50
+            }
+          })
+        }
+      })
+
+      // Add the nodes
+      const setupTime = performance.now()
+      spatialIndex.batchUpdate(allNodes)
+      const setupDuration = performance.now() - setupTime
+
+      // Simulate user panning around the workflow
+      const viewportSize = { width: 1920, height: 1080 }
+      const panPositions = [
+        { x: -960, y: -540 }, // Center on first cluster
+        { x: 1040, y: -540 }, // Pan to second cluster
+        { x: 3040, y: 460 }, // Pan to third cluster
+        { x: -960, y: 1460 }, // Pan to fourth cluster
+        { x: 1000, y: 500 } // Overview position
+      ]
+
+      const panStartTime = performance.now()
+      const queryResults: number[] = []
+
+      panPositions.forEach((pos) => {
+        // Simulate multiple viewport queries during smooth panning
+        for (let step = 0; step < 10; step++) {
+          const results = spatialIndex.queryViewport({
+            x: pos.x + step * 20,
+            y: pos.y + step * 10,
+            width: viewportSize.width,
+            height: viewportSize.height
+          })
+          queryResults.push(results.length)
+        }
+      })
+
+      const panDuration = performance.now() - panStartTime
+      const avgQueryTime = panDuration / (panPositions.length * 10)
+
+      // Performance expectations for realistic workflows
+      expect(setupDuration).toBeLessThan(30) // Setup 155 nodes in under 30ms
+      expect(avgQueryTime).toBeLessThan(1.5) // Average query under 1.5ms
+      expect(panDuration).toBeLessThan(50) // All panning queries under 50ms
+
+      // Should have reasonable culling efficiency
+      const totalNodes = allNodes.length
+      const avgVisibleNodes =
+        queryResults.reduce((a, b) => a + b, 0) / queryResults.length
+      const cullRatio = (totalNodes - avgVisibleNodes) / totalNodes
+
+      expect(cullRatio).toBeGreaterThan(0.3) // At least 30% culling efficiency
+    })
+  })
+})

tests-ui/tests/performance/transformPerformance.test.ts

@@ -0,0 +1,479 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { useTransformState } from '@/composables/element/useTransformState'
+
+// Mock canvas context for testing
+const createMockCanvasContext = () => ({
+  ds: {
+    offset: [0, 0] as [number, number],
+    scale: 1
+  }
+})
+
+describe('Transform Performance', () => {
+  let transformState: ReturnType<typeof useTransformState>
+  let mockCanvas: any
+
+  beforeEach(() => {
+    transformState = useTransformState()
+    mockCanvas = createMockCanvasContext()
+  })
+
+  describe('coordinate conversion performance', () => {
+    it('should handle large batches of coordinate conversions efficiently', () => {
+      // Set up a realistic transform state
+      mockCanvas.ds.offset = [500, 300]
+      mockCanvas.ds.scale = 1.5
+      transformState.syncWithCanvas(mockCanvas)
+
+      const conversionCount = 10000
+      const points = Array.from({ length: conversionCount }, () => ({
+        x: Math.random() * 5000,
+        y: Math.random() * 3000
+      }))
+
+      // Benchmark canvas to screen conversions
+      const canvasToScreenStart = performance.now()
+      const screenPoints = points.map((point) =>
+        transformState.canvasToScreen(point)
+      )
+      const canvasToScreenTime = performance.now() - canvasToScreenStart
+
+      // Benchmark screen to canvas conversions
+      const screenToCanvasStart = performance.now()
+      const backToCanvas = screenPoints.map((point) =>
+        transformState.screenToCanvas(point)
+      )
+      const screenToCanvasTime = performance.now() - screenToCanvasStart
+
+      // Performance expectations
+      expect(canvasToScreenTime).toBeLessThan(20) // 10k conversions in under 20ms
+      expect(screenToCanvasTime).toBeLessThan(20) // 10k conversions in under 20ms
+
+      // Verify accuracy of round-trip conversion
+      const maxError = points.reduce((max, original, i) => {
+        const converted = backToCanvas[i]
+        const errorX = Math.abs(original.x - converted.x)
+        const errorY = Math.abs(original.y - converted.y)
+        return Math.max(max, errorX, errorY)
+      }, 0)
+
+      expect(maxError).toBeLessThan(0.001) // Sub-pixel accuracy
+    })
+
+    it('should maintain performance across different zoom levels', () => {
+      const zoomLevels = [0.1, 0.5, 1.0, 2.0, 5.0, 10.0]
+      const conversionCount = 1000
+      const testPoints = Array.from({ length: conversionCount }, () => ({
+        x: Math.random() * 2000,
+        y: Math.random() * 1500
+      }))
+
+      const performanceResults: number[] = []
+
+      zoomLevels.forEach((scale) => {
+        mockCanvas.ds.scale = scale
+        transformState.syncWithCanvas(mockCanvas)
+
+        const startTime = performance.now()
+        testPoints.forEach((point) => {
+          const screen = transformState.canvasToScreen(point)
+          transformState.screenToCanvas(screen)
+        })
+        const duration = performance.now() - startTime
+
+        performanceResults.push(duration)
+      })
+
+      // Performance should be consistent across zoom levels
+      const maxTime = Math.max(...performanceResults)
+      const minTime = Math.min(...performanceResults)
+      const variance = (maxTime - minTime) / minTime
+
+      expect(maxTime).toBeLessThan(20) // All zoom levels under 20ms
+      expect(variance).toBeLessThan(3.0) // Less than 300% variance between zoom levels
+    })
+
+    it('should handle extreme coordinate values efficiently', () => {
+      // Test with very large coordinate values
+      const extremePoints = [
+        { x: -100000, y: -100000 },
+        { x: 100000, y: 100000 },
+        { x: 0, y: 0 },
+        { x: -50000, y: 50000 },
+        { x: 1e6, y: -1e6 }
+      ]
+
+      // Test at extreme zoom levels
+      const extremeScales = [0.001, 1000]
+
+      extremeScales.forEach((scale) => {
+        mockCanvas.ds.scale = scale
+        mockCanvas.ds.offset = [1000, 500]
+        transformState.syncWithCanvas(mockCanvas)
+
+        const startTime = performance.now()
+
+        // Convert each point 100 times
+        extremePoints.forEach((point) => {
+          for (let i = 0; i < 100; i++) {
+            const screen = transformState.canvasToScreen(point)
+            transformState.screenToCanvas(screen)
+          }
+        })
+
+        const duration = performance.now() - startTime
+
+        expect(duration).toBeLessThan(5) // Should handle extremes efficiently
+        expect(
+          Number.isFinite(transformState.canvasToScreen(extremePoints[0]).x)
+        ).toBe(true)
+        expect(
+          Number.isFinite(transformState.canvasToScreen(extremePoints[0]).y)
+        ).toBe(true)
+      })
+    })
+  })
+
+  describe('viewport culling performance', () => {
+    it('should efficiently determine node visibility for large numbers of nodes', () => {
+      // Set up realistic viewport
+      const viewport = { width: 1920, height: 1080 }
+
+      // Generate many node positions
+      const nodeCount = 1000
+      const nodes = Array.from({ length: nodeCount }, () => ({
+        pos: [Math.random() * 10000, Math.random() * 6000] as ArrayLike<number>,
+        size: [
+          150 + Math.random() * 100,
+          100 + Math.random() * 50
+        ] as ArrayLike<number>
+      }))
+
+      // Test at different zoom levels and positions
+      const testConfigs = [
+        { scale: 0.5, offset: [0, 0] },
+        { scale: 1.0, offset: [2000, 1000] },
+        { scale: 2.0, offset: [-1000, -500] }
+      ]
+
+      testConfigs.forEach((config) => {
+        mockCanvas.ds.scale = config.scale
+        mockCanvas.ds.offset = config.offset
+        transformState.syncWithCanvas(mockCanvas)
+
+        const startTime = performance.now()
+
+        // Test viewport culling for all nodes
+        const visibleNodes = nodes.filter((node) =>
+          transformState.isNodeInViewport(node.pos, node.size, viewport)
+        )
+
+        const cullTime = performance.now() - startTime
+
+        expect(cullTime).toBeLessThan(10) // 1000 nodes culled in under 10ms
+        expect(visibleNodes.length).toBeLessThan(nodeCount) // Some culling should occur
+        expect(visibleNodes.length).toBeGreaterThanOrEqual(0) // Sanity check
+      })
+    })
+
+    it('should optimize culling with adaptive margins', () => {
+      const viewport = { width: 1280, height: 720 }
+      const testNode = {
+        pos: [1300, 100] as ArrayLike<number>, // Just outside viewport
+        size: [200, 100] as ArrayLike<number>
+      }
+
+      // Test margin adaptation at different zoom levels
+      const zoomTests = [
+        { scale: 0.05, expectedVisible: true }, // Low zoom, larger margin
+        { scale: 1.0, expectedVisible: true }, // Normal zoom, standard margin
+        { scale: 4.0, expectedVisible: false } // High zoom, tighter margin
+      ]
+
+      const marginTests: boolean[] = []
+      const timings: number[] = []
+
+      zoomTests.forEach((test) => {
+        mockCanvas.ds.scale = test.scale
+        mockCanvas.ds.offset = [0, 0]
+        transformState.syncWithCanvas(mockCanvas)
+
+        const startTime = performance.now()
+        const isVisible = transformState.isNodeInViewport(
+          testNode.pos,
+          testNode.size,
+          viewport,
+          0.2 // 20% margin
+        )
+        const duration = performance.now() - startTime
+
+        marginTests.push(isVisible)
+        timings.push(duration)
+      })
+
+      // All culling operations should be very fast
+      timings.forEach((time) => {
+        expect(time).toBeLessThan(0.1) // Individual culling under 0.1ms
+      })
+
+      // Verify adaptive behavior (margins should work as expected)
+      expect(marginTests[0]).toBe(zoomTests[0].expectedVisible)
+      expect(marginTests[2]).toBe(zoomTests[2].expectedVisible)
+    })
+
+    it('should handle size-based culling efficiently', () => {
+      // Test nodes of various sizes
+      const nodeSizes = [
+        [1, 1], // Tiny node
+        [5, 5], // Small node
+        [50, 50], // Medium node
+        [200, 100], // Large node
+        [500, 300] // Very large node
+      ]
+
+      const viewport = { width: 1920, height: 1080 }
+
+      // Position all nodes in viewport center
+      const centerPos = [960, 540] as ArrayLike<number>
+
+      nodeSizes.forEach((size) => {
+        // Test at very low zoom where size culling should activate
+        mockCanvas.ds.scale = 0.01 // Very low zoom
+        transformState.syncWithCanvas(mockCanvas)
+
+        const startTime = performance.now()
+        const isVisible = transformState.isNodeInViewport(
+          centerPos,
+          size as ArrayLike<number>,
+          viewport
+        )
+        const cullTime = performance.now() - startTime
+
+        expect(cullTime).toBeLessThan(0.1) // Size culling under 0.1ms
+
+        // At 0.01 zoom, nodes need to be 400+ pixels to show as 4+ screen pixels
+        const screenSize = Math.max(size[0], size[1]) * 0.01
+        if (screenSize < 4) {
+          expect(isVisible).toBe(false)
+        } else {
+          expect(isVisible).toBe(true)
+        }
+      })
+    })
+  })
+
+  describe('transform state synchronization', () => {
+    it('should efficiently sync with canvas state changes', () => {
+      const syncCount = 1000
+      const transformUpdates = Array.from({ length: syncCount }, (_, i) => ({
+        offset: [Math.sin(i * 0.1) * 1000, Math.cos(i * 0.1) * 500],
+        scale: 0.5 + Math.sin(i * 0.05) * 0.4 // Scale between 0.1 and 0.9
+      }))
+
+      const startTime = performance.now()
+
+      transformUpdates.forEach((update) => {
+        mockCanvas.ds.offset = update.offset
+        mockCanvas.ds.scale = update.scale
+        transformState.syncWithCanvas(mockCanvas)
+      })
+
+      const syncTime = performance.now() - startTime
+
+      expect(syncTime).toBeLessThan(15) // 1000 syncs in under 15ms
+
+      // Verify final state is correct
+      const lastUpdate = transformUpdates[transformUpdates.length - 1]
+      expect(transformState.camera.x).toBe(lastUpdate.offset[0])
+      expect(transformState.camera.y).toBe(lastUpdate.offset[1])
+      expect(transformState.camera.z).toBe(lastUpdate.scale)
+    })
+
+    it('should generate CSS transform strings efficiently', () => {
+      const transformCount = 10000
+
+      // Set up varying transform states
+      const transforms = Array.from({ length: transformCount }, (_, i) => {
+        mockCanvas.ds.offset = [i * 10, i * 5]
+        mockCanvas.ds.scale = 0.5 + (i % 100) / 100
+        transformState.syncWithCanvas(mockCanvas)
+        return transformState.transformStyle.value
+      })
+
+      const startTime = performance.now()
+
+      // Access transform styles (triggers computed property)
+      transforms.forEach((style) => {
+        expect(style.transform).toContain('scale(')
+        expect(style.transform).toContain('translate(')
+        expect(style.transformOrigin).toBe('0 0')
+      })
+
+      const accessTime = performance.now() - startTime
+
+      expect(accessTime).toBeLessThan(200) // 10k style accesses in under 200ms
+    })
+  })
+
+  describe('bounds calculation performance', () => {
+    it('should calculate node screen bounds efficiently', () => {
+      // Set up realistic transform
+      mockCanvas.ds.offset = [200, 100]
+      mockCanvas.ds.scale = 1.5
+      transformState.syncWithCanvas(mockCanvas)
+
+      const nodeCount = 1000
+      const nodes = Array.from({ length: nodeCount }, () => ({
+        pos: [Math.random() * 5000, Math.random() * 3000] as ArrayLike<number>,
+        size: [
+          100 + Math.random() * 200,
+          80 + Math.random() * 120
+        ] as ArrayLike<number>
+      }))
+
+      const startTime = performance.now()
+
+      const bounds = nodes.map((node) =>
+        transformState.getNodeScreenBounds(node.pos, node.size)
+      )
+
+      const calcTime = performance.now() - startTime
+
+      expect(calcTime).toBeLessThan(15) // 1000 bounds calculations in under 15ms
+      expect(bounds).toHaveLength(nodeCount)
+
+      // Verify bounds are reasonable
+      bounds.forEach((bound) => {
+        expect(bound.width).toBeGreaterThan(0)
+        expect(bound.height).toBeGreaterThan(0)
+        expect(Number.isFinite(bound.x)).toBe(true)
+        expect(Number.isFinite(bound.y)).toBe(true)
+      })
+    })
+
+    it('should calculate viewport bounds efficiently', () => {
+      const viewportSizes = [
+        { width: 800, height: 600 },
+        { width: 1920, height: 1080 },
+        { width: 3840, height: 2160 },
+        { width: 1280, height: 720 }
+      ]
+
+      const margins = [0, 0.1, 0.2, 0.5]
+
+      const combinations = viewportSizes.flatMap((viewport) =>
+        margins.map((margin) => ({ viewport, margin }))
+      )
+
+      const startTime = performance.now()
+
+      const allBounds = combinations.map(({ viewport, margin }) => {
+        mockCanvas.ds.offset = [Math.random() * 1000, Math.random() * 500]
+        mockCanvas.ds.scale = 0.5 + Math.random() * 2
+        transformState.syncWithCanvas(mockCanvas)
+
+        return transformState.getViewportBounds(viewport, margin)
+      })
+
+      const calcTime = performance.now() - startTime
+
+      expect(calcTime).toBeLessThan(5) // All viewport calculations in under 5ms
+      expect(allBounds).toHaveLength(combinations.length)
+
+      // Verify bounds are reasonable
+      allBounds.forEach((bounds) => {
+        expect(bounds.width).toBeGreaterThan(0)
+        expect(bounds.height).toBeGreaterThan(0)
+        expect(Number.isFinite(bounds.x)).toBe(true)
+        expect(Number.isFinite(bounds.y)).toBe(true)
+      })
+    })
+  })
+
+  describe('real-world performance scenarios', () => {
+    it('should handle smooth panning performance', () => {
+      // Simulate smooth 60fps panning for 2 seconds
+      const frameCount = 120 // 2 seconds at 60fps
+      const panDistance = 2000 // Pan 2000 pixels
+
+      const frames: number[] = []
+
+      for (let frame = 0; frame < frameCount; frame++) {
+        const progress = frame / (frameCount - 1)
+        const x = progress * panDistance
+        const y = Math.sin(progress * Math.PI * 2) * 200 // Slight vertical wave
+
+        mockCanvas.ds.offset = [x, y]
+
+        const frameStart = performance.now()
+
+        // Typical operations during panning
+        transformState.syncWithCanvas(mockCanvas)
+        const style = transformState.transformStyle.value // Access transform style
+        expect(style.transform).toContain('translate') // Verify style is valid
+
+        // Simulate some coordinate conversions (mouse tracking, etc.)
+        for (let i = 0; i < 5; i++) {
+          const screen = transformState.canvasToScreen({
+            x: x + i * 100,
+            y: y + i * 50
+          })
+          transformState.screenToCanvas(screen)
+        }
+
+        const frameTime = performance.now() - frameStart
+        frames.push(frameTime)
+
+        // Each frame should be well under 16.67ms for 60fps
+        expect(frameTime).toBeLessThan(1) // Conservative: under 1ms per frame
+      }
+
+      const totalTime = frames.reduce((sum, time) => sum + time, 0)
+      const avgFrameTime = totalTime / frameCount
+
+      expect(avgFrameTime).toBeLessThan(0.5) // Average frame time under 0.5ms
+      expect(totalTime).toBeLessThan(60) // Total panning overhead under 60ms
+    })
+
+    it('should handle zoom performance with viewport updates', () => {
+      // Simulate smooth zoom from 0.1x to 10x
+      const zoomSteps = 100
+      const viewport = { width: 1920, height: 1080 }
+
+      const zoomTimes: number[] = []
+
+      for (let step = 0; step < zoomSteps; step++) {
+        const zoomLevel = Math.pow(10, (step / (zoomSteps - 1)) * 2 - 1) // 0.1 to 10
+        mockCanvas.ds.scale = zoomLevel
+
+        const stepStart = performance.now()
+
+        // Operations during zoom
+        transformState.syncWithCanvas(mockCanvas)
+
+        // Viewport bounds calculation (for culling)
+        transformState.getViewportBounds(viewport, 0.2)
+
+        // Test a few nodes for visibility
+        for (let i = 0; i < 10; i++) {
+          transformState.isNodeInViewport(
+            [i * 200, i * 150],
+            [200, 100],
+            viewport
+          )
+        }
+
+        const stepTime = performance.now() - stepStart
+        zoomTimes.push(stepTime)
+      }
+
+      const maxZoomTime = Math.max(...zoomTimes)
+      const avgZoomTime =
+        zoomTimes.reduce((sum, time) => sum + time, 0) / zoomSteps
+
+      expect(maxZoomTime).toBeLessThan(2) // No zoom step over 2ms
+      expect(avgZoomTime).toBeLessThan(1) // Average zoom step under 1ms
+    })
+  })
+})

tests-ui/tests/utils/spatial/QuadTree.test.ts

@@ -0,0 +1,269 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { type Bounds, QuadTree } from '@/utils/spatial/QuadTree'
+
+describe('QuadTree', () => {
+  let quadTree: QuadTree<string>
+  const worldBounds: Bounds = { x: 0, y: 0, width: 1000, height: 1000 }
+
+  beforeEach(() => {
+    quadTree = new QuadTree<string>(worldBounds, {
+      maxDepth: 4,
+      maxItemsPerNode: 4
+    })
+  })
+
+  describe('insertion', () => {
+    it('should insert items within bounds', () => {
+      const success = quadTree.insert(
+        'node1',
+        { x: 100, y: 100, width: 50, height: 50 },
+        'node1'
+      )
+      expect(success).toBe(true)
+      expect(quadTree.size).toBe(1)
+    })
+
+    it('should reject items outside bounds', () => {
+      const success = quadTree.insert(
+        'node1',
+        { x: -100, y: -100, width: 50, height: 50 },
+        'node1'
+      )
+      expect(success).toBe(false)
+      expect(quadTree.size).toBe(0)
+    })
+
+    it('should handle duplicate IDs by replacing', () => {
+      quadTree.insert(
+        'node1',
+        { x: 100, y: 100, width: 50, height: 50 },
+        'data1'
+      )
+      quadTree.insert(
+        'node1',
+        { x: 200, y: 200, width: 50, height: 50 },
+        'data2'
+      )
+
+      expect(quadTree.size).toBe(1)
+      const results = quadTree.query({
+        x: 150,
+        y: 150,
+        width: 100,
+        height: 100
+      })
+      expect(results).toContain('data2')
+      expect(results).not.toContain('data1')
+    })
+  })
+
+  describe('querying', () => {
+    beforeEach(() => {
+      // Insert test nodes in a grid pattern
+      for (let x = 0; x < 10; x++) {
+        for (let y = 0; y < 10; y++) {
+          const id = `node_${x}_${y}`
+          quadTree.insert(
+            id,
+            {
+              x: x * 100,
+              y: y * 100,
+              width: 50,
+              height: 50
+            },
+            id
+          )
+        }
+      }
+    })
+
+    it('should find nodes within query bounds', () => {
+      const results = quadTree.query({ x: 0, y: 0, width: 250, height: 250 })
+      expect(results.length).toBe(9) // 3x3 grid
+    })
+
+    it('should return empty array for out-of-bounds query', () => {
+      const results = quadTree.query({
+        x: 2000,
+        y: 2000,
+        width: 100,
+        height: 100
+      })
+      expect(results.length).toBe(0)
+    })
+
+    it('should handle partial overlaps', () => {
+      const results = quadTree.query({ x: 25, y: 25, width: 100, height: 100 })
+      expect(results.length).toBe(4) // 2x2 grid due to overlap
+    })
+
+    it('should handle large query areas efficiently', () => {
+      const startTime = performance.now()
+      const results = quadTree.query({ x: 0, y: 0, width: 1000, height: 1000 })
+      const queryTime = performance.now() - startTime
+
+      expect(results.length).toBe(100) // All nodes
+      expect(queryTime).toBeLessThan(5) // Should be fast
+    })
+  })
+
+  describe('removal', () => {
+    it('should remove existing items', () => {
+      quadTree.insert(
+        'node1',
+        { x: 100, y: 100, width: 50, height: 50 },
+        'node1'
+      )
+      expect(quadTree.size).toBe(1)
+
+      const success = quadTree.remove('node1')
+      expect(success).toBe(true)
+      expect(quadTree.size).toBe(0)
+    })
+
+    it('should handle removal of non-existent items', () => {
+      const success = quadTree.remove('nonexistent')
+      expect(success).toBe(false)
+    })
+  })
+
+  describe('updating', () => {
+    it('should update item position', () => {
+      quadTree.insert(
+        'node1',
+        { x: 100, y: 100, width: 50, height: 50 },
+        'node1'
+      )
+
+      const success = quadTree.update('node1', {
+        x: 200,
+        y: 200,
+        width: 50,
+        height: 50
+      })
+      expect(success).toBe(true)
+
+      // Should not find at old position
+      const oldResults = quadTree.query({
+        x: 75,
+        y: 75,
+        width: 100,
+        height: 100
+      })
+      expect(oldResults).not.toContain('node1')
+
+      // Should find at new position
+      const newResults = quadTree.query({
+        x: 175,
+        y: 175,
+        width: 100,
+        height: 100
+      })
+      expect(newResults).toContain('node1')
+    })
+  })
+
+  describe('subdivision', () => {
+    it('should subdivide when exceeding max items', () => {
+      // Insert 5 items (max is 4) to trigger subdivision
+      for (let i = 0; i < 5; i++) {
+        quadTree.insert(
+          `node${i}`,
+          {
+            x: i * 10,
+            y: i * 10,
+            width: 5,
+            height: 5
+          },
+          `node${i}`
+        )
+      }
+
+      expect(quadTree.size).toBe(5)
+
+      // Verify all items can still be found
+      const allResults = quadTree.query(worldBounds)
+      expect(allResults.length).toBe(5)
+    })
+  })
+
+  describe('performance', () => {
+    it('should handle 1000 nodes efficiently', () => {
+      const insertStart = performance.now()
+
+      // Insert 1000 nodes
+      for (let i = 0; i < 1000; i++) {
+        const x = Math.random() * 900
+        const y = Math.random() * 900
+        quadTree.insert(
+          `node${i}`,
+          {
+            x,
+            y,
+            width: 50,
+            height: 50
+          },
+          `node${i}`
+        )
+      }
+
+      const insertTime = performance.now() - insertStart
+      expect(insertTime).toBeLessThan(50) // Should be fast
+
+      // Query performance
+      const queryStart = performance.now()
+      const results = quadTree.query({
+        x: 400,
+        y: 400,
+        width: 200,
+        height: 200
+      })
+      const queryTime = performance.now() - queryStart
+
+      expect(queryTime).toBeLessThan(2) // Queries should be very fast
+      expect(results.length).toBeGreaterThan(0)
+      expect(results.length).toBeLessThan(1000) // Should cull most nodes
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle zero-sized bounds', () => {
+      const success = quadTree.insert(
+        'point',
+        { x: 100, y: 100, width: 0, height: 0 },
+        'point'
+      )
+      expect(success).toBe(true)
+
+      const results = quadTree.query({ x: 99, y: 99, width: 2, height: 2 })
+      expect(results).toContain('point')
+    })
+
+    it('should handle items spanning multiple quadrants', () => {
+      const success = quadTree.insert(
+        'large',
+        {
+          x: 400,
+          y: 400,
+          width: 200,
+          height: 200
+        },
+        'large'
+      )
+      expect(success).toBe(true)
+
+      // Should be found when querying any overlapping quadrant
+      const topLeft = quadTree.query({ x: 0, y: 0, width: 500, height: 500 })
+      const bottomRight = quadTree.query({
+        x: 500,
+        y: 500,
+        width: 500,
+        height: 500
+      })
+
+      expect(topLeft).toContain('large')
+      expect(bottomRight).toContain('large')
+    })
+  })
+})