[refactor] Refactor rendering-related files to DDD organization (#5388)

* refactor rendering-related files to DDD organization

* add to git ignore ignore revs

src/renderer/core/layout/TransformPane.vue

@@ -0,0 +1,91 @@
+<template>
+  <div
+    class="transform-pane"
+    :class="{ 'transform-pane--interacting': isInteracting }"
+    :style="transformStyle"
+    @pointerdown="handlePointerDown"
+  >
+    <!-- Vue nodes will be rendered here -->
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, provide } from 'vue'
+
+import { useCanvasTransformSync } from '@/composables/graph/useCanvasTransformSync'
+import { useTransformSettling } from '@/composables/graph/useTransformSettling'
+import { LGraphCanvas } from '@/lib/litegraph/src/litegraph'
+import { useTransformState } from '@/renderer/core/layout/useTransformState'
+
+interface TransformPaneProps {
+  canvas?: LGraphCanvas
+}
+
+const props = defineProps<TransformPaneProps>()
+
+const {
+  camera,
+  transformStyle,
+  syncWithCanvas,
+  canvasToScreen,
+  screenToCanvas,
+  isNodeInViewport
+} = useTransformState()
+
+const canvasElement = computed(() => props.canvas?.canvas)
+const { isTransforming: isInteracting } = useTransformSettling(canvasElement, {
+  settleDelay: 200,
+  trackPan: true
+})
+
+provide('transformState', {
+  camera,
+  canvasToScreen,
+  screenToCanvas,
+  isNodeInViewport
+})
+
+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
+  }
+}
+
+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;
+  transform-origin: 0 0;
+  pointer-events: none;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.transform-pane--interacting {
+  will-change: transform;
+}
+
+/* Allow pointer events on nodes */
+.transform-pane :deep([data-node-id]) {
+  pointer-events: auto;
+}
+</style>

src/renderer/core/layout/__tests__/TransformPane.spec.ts

@@ -0,0 +1,350 @@
+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('@/renderer/core/spatial/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('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)
+    })
+  })
+})

src/renderer/core/layout/useTransformState.ts

@@ -0,0 +1,242 @@
+/**
+ * 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 { computed, reactive, readonly } from 'vue'
+
+import type { LGraphCanvas } from '@/lib/litegraph/src/litegraph'
+
+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/renderer/core/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/renderer/core/spatial/SpatialIndex.ts

@@ -9,7 +9,8 @@ import {
   QUADTREE_CONFIG
 } from '@/renderer/core/layout/constants'
 import type { Bounds, NodeId } from '@/renderer/core/layout/types'
-import { QuadTree } from '@/utils/spatial/QuadTree'
+
+import { QuadTree } from './QuadTree'
 
 /**
  * Cache entry for spatial queries

src/renderer/extensions/minimap/MiniMap.vue

@@ -0,0 +1,147 @@
+<template>
+  <div
+    v-if="visible && initialized"
+    ref="minimapRef"
+    class="minimap-main-container flex absolute bottom-[66px] right-2 md:right-11 z-1000"
+  >
+    <MiniMapPanel
+      v-if="showOptionsPanel"
+      :panel-styles="panelStyles"
+      :node-colors="nodeColors"
+      :show-links="showLinks"
+      :show-groups="showGroups"
+      :render-bypass="renderBypass"
+      :render-error="renderError"
+      @update-option="updateOption"
+    />
+
+    <div
+      ref="containerRef"
+      class="litegraph-minimap relative"
+      :style="containerStyles"
+    >
+      <Button
+        class="absolute z-10"
+        size="small"
+        text
+        severity="secondary"
+        @click.stop="toggleOptionsPanel"
+      >
+        <template #icon>
+          <i-lucide:settings-2 />
+        </template>
+      </Button>
+      <Button
+        class="absolute z-10 right-0"
+        size="small"
+        text
+        severity="secondary"
+        data-testid="close-minmap-button"
+        @click.stop="() => commandStore.execute('Comfy.Canvas.ToggleMinimap')"
+      >
+        <template #icon>
+          <i-lucide:x />
+        </template>
+      </Button>
+
+      <hr
+        class="absolute top-5 bg-[#E1DED5] dark-theme:bg-[#262729] h-[1px] border-0"
+        :style="{
+          width: containerStyles.width
+        }"
+      />
+
+      <canvas
+        ref="canvasRef"
+        :width="width"
+        :height="height"
+        class="minimap-canvas"
+      />
+
+      <div class="minimap-viewport" :style="viewportStyles" />
+
+      <div
+        class="absolute inset-0"
+        @pointerdown="handlePointerDown"
+        @pointermove="handlePointerMove"
+        @pointerup="handlePointerUp"
+        @pointerleave="handlePointerUp"
+        @wheel="handleWheel"
+      />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import Button from 'primevue/button'
+import { onMounted, onUnmounted, ref } from 'vue'
+
+import { useMinimap } from '@/renderer/extensions/minimap/composables/useMinimap'
+import { useCommandStore } from '@/stores/commandStore'
+
+import MiniMapPanel from './MiniMapPanel.vue'
+
+const commandStore = useCommandStore()
+
+const minimapRef = ref<HTMLDivElement>()
+
+const {
+  initialized,
+  visible,
+  containerRef,
+  canvasRef,
+  containerStyles,
+  viewportStyles,
+  width,
+  height,
+  panelStyles,
+  nodeColors,
+  showLinks,
+  showGroups,
+  renderBypass,
+  renderError,
+  updateOption,
+  destroy,
+  handlePointerDown,
+  handlePointerMove,
+  handlePointerUp,
+  handleWheel,
+  setMinimapRef
+} = useMinimap()
+
+const showOptionsPanel = ref(false)
+
+const toggleOptionsPanel = () => {
+  showOptionsPanel.value = !showOptionsPanel.value
+}
+
+onMounted(() => {
+  if (minimapRef.value) {
+    setMinimapRef(minimapRef.value)
+  }
+})
+
+onUnmounted(() => {
+  destroy()
+})
+</script>
+
+<style scoped>
+.litegraph-minimap {
+  overflow: hidden;
+}
+
+.minimap-canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}
+
+.minimap-viewport {
+  position: absolute;
+  top: 0;
+  left: 0;
+  pointer-events: none;
+}
+</style>

src/renderer/extensions/minimap/MiniMapPanel.vue

@@ -0,0 +1,97 @@
+<template>
+  <div
+    class="minimap-panel p-3 mr-2 flex flex-col gap-3 text-sm"
+    :style="panelStyles"
+  >
+    <div class="flex items-center gap-2">
+      <Checkbox
+        input-id="node-colors"
+        name="node-colors"
+        :model-value="nodeColors"
+        binary
+        @update:model-value="
+          (value) => $emit('updateOption', 'Comfy.Minimap.NodeColors', value)
+        "
+      />
+      <i-lucide:palette />
+      <label for="node-colors">{{ $t('minimap.nodeColors') }}</label>
+    </div>
+
+    <div class="flex items-center gap-2">
+      <Checkbox
+        input-id="show-links"
+        name="show-links"
+        :model-value="showLinks"
+        binary
+        @update:model-value="
+          (value) => $emit('updateOption', 'Comfy.Minimap.ShowLinks', value)
+        "
+      />
+      <i-lucide:route />
+      <label for="show-links">{{ $t('minimap.showLinks') }}</label>
+    </div>
+
+    <div class="flex items-center gap-2">
+      <Checkbox
+        input-id="show-groups"
+        name="show-groups"
+        :model-value="showGroups"
+        binary
+        @update:model-value="
+          (value) => $emit('updateOption', 'Comfy.Minimap.ShowGroups', value)
+        "
+      />
+      <i-lucide:frame />
+      <label for="show-groups">{{ $t('minimap.showGroups') }}</label>
+    </div>
+
+    <div class="flex items-center gap-2">
+      <Checkbox
+        input-id="render-bypass"
+        name="render-bypass"
+        :model-value="renderBypass"
+        binary
+        @update:model-value="
+          (value) =>
+            $emit('updateOption', 'Comfy.Minimap.RenderBypassState', value)
+        "
+      />
+      <i-lucide:circle-slash-2 />
+      <label for="render-bypass">{{ $t('minimap.renderBypassState') }}</label>
+    </div>
+
+    <div class="flex items-center gap-2">
+      <Checkbox
+        input-id="render-error"
+        name="render-error"
+        :model-value="renderError"
+        binary
+        @update:model-value="
+          (value) =>
+            $emit('updateOption', 'Comfy.Minimap.RenderErrorState', value)
+        "
+      />
+      <i-lucide:message-circle-warning />
+      <label for="render-error">{{ $t('minimap.renderErrorState') }}</label>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import Checkbox from 'primevue/checkbox'
+
+import type { MinimapSettingsKey } from '@/renderer/extensions/minimap/types'
+
+defineProps<{
+  panelStyles: any
+  nodeColors: boolean
+  showLinks: boolean
+  showGroups: boolean
+  renderBypass: boolean
+  renderError: boolean
+}>()
+
+defineEmits<{
+  updateOption: [key: MinimapSettingsKey, value: boolean]
+}>()
+</script>