minimap (#4520)

Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Christian Byrne <cbyrne@comfy.org>

browser_tests/tests/interaction.spec.ts

@@ -768,6 +768,11 @@ test.describe('Viewport settings', () => {
     comfyMouse
   }) => {
     // Screenshot the canvas element
+    await comfyPage.setSetting('Comfy.Graph.CanvasMenu', true)
+    const toggleButton = comfyPage.page.getByTestId('toggle-minimap-button')
+
+    await toggleButton.click()
+
     await comfyPage.menu.topbar.saveWorkflow('Workflow A')
     await comfyPage.nextFrame()
     const screenshotA = (await comfyPage.canvas.screenshot()).toString('base64')

browser_tests/tests/minimap.spec.ts

@@ -0,0 +1,77 @@
+import { expect } from '@playwright/test'
+
+import { comfyPageFixture as test } from '../fixtures/ComfyPage'
+
+test.describe('Minimap', () => {
+  test.beforeEach(async ({ comfyPage }) => {
+    await comfyPage.setSetting('Comfy.UseNewMenu', 'Top')
+    await comfyPage.setSetting('Comfy.Minimap.Visible', true)
+    await comfyPage.setSetting('Comfy.Graph.CanvasMenu', true)
+    await comfyPage.loadWorkflow('default')
+    await comfyPage.page.waitForFunction(
+      () => window['app'] && window['app'].canvas
+    )
+  })
+
+  test('Validate minimap is visible by default', async ({ comfyPage }) => {
+    const minimapContainer = comfyPage.page.locator('.litegraph-minimap')
+
+    await expect(minimapContainer).toBeVisible()
+
+    const minimapCanvas = minimapContainer.locator('.minimap-canvas')
+    await expect(minimapCanvas).toBeVisible()
+
+    const minimapViewport = minimapContainer.locator('.minimap-viewport')
+    await expect(minimapViewport).toBeVisible()
+
+    await expect(minimapContainer).toHaveCSS('position', 'absolute')
+    await expect(minimapContainer).toHaveCSS('z-index', '1000')
+  })
+
+  test('Validate minimap toggle button state', async ({ comfyPage }) => {
+    const toggleButton = comfyPage.page.getByTestId('toggle-minimap-button')
+
+    await expect(toggleButton).toBeVisible()
+
+    await expect(toggleButton).toHaveClass(/minimap-active/)
+
+    const minimapContainer = comfyPage.page.locator('.litegraph-minimap')
+    await expect(minimapContainer).toBeVisible()
+  })
+
+  test('Validate minimap can be toggled off and on', async ({ comfyPage }) => {
+    const minimapContainer = comfyPage.page.locator('.litegraph-minimap')
+    const toggleButton = comfyPage.page.getByTestId('toggle-minimap-button')
+
+    await expect(minimapContainer).toBeVisible()
+    await expect(toggleButton).toHaveClass(/minimap-active/)
+
+    await toggleButton.click()
+    await comfyPage.nextFrame()
+
+    await expect(minimapContainer).not.toBeVisible()
+    await expect(toggleButton).not.toHaveClass(/minimap-active/)
+
+    await toggleButton.click()
+    await comfyPage.nextFrame()
+
+    await expect(minimapContainer).toBeVisible()
+    await expect(toggleButton).toHaveClass(/minimap-active/)
+  })
+
+  test('Validate minimap keyboard shortcut Alt+M', async ({ comfyPage }) => {
+    const minimapContainer = comfyPage.page.locator('.litegraph-minimap')
+
+    await expect(minimapContainer).toBeVisible()
+
+    await comfyPage.page.keyboard.press('Alt+KeyM')
+    await comfyPage.nextFrame()
+
+    await expect(minimapContainer).not.toBeVisible()
+
+    await comfyPage.page.keyboard.press('Alt+KeyM')
+    await comfyPage.nextFrame()
+
+    await expect(minimapContainer).toBeVisible()
+  })
+})

src/components/graph/GraphCanvas.vue

@@ -18,6 +18,12 @@
         />
       </div>
       <GraphCanvasMenu v-if="canvasMenuEnabled" class="pointer-events-auto" />
+
+      <MiniMap
+        v-if="comfyAppReady && minimapEnabled"
+        ref="minimapRef"
+        class="pointer-events-auto"
+      />
     </template>
   </LiteGraphCanvasSplitterOverlay>
   <GraphCanvasMenu v-if="!betaMenuEnabled && canvasMenuEnabled" />
@@ -51,6 +57,7 @@ import LiteGraphCanvasSplitterOverlay from '@/components/LiteGraphCanvasSplitter
 import BottomPanel from '@/components/bottomPanel/BottomPanel.vue'
 import DomWidgets from '@/components/graph/DomWidgets.vue'
 import GraphCanvasMenu from '@/components/graph/GraphCanvasMenu.vue'
+import MiniMap from '@/components/graph/MiniMap.vue'
 import NodeTooltip from '@/components/graph/NodeTooltip.vue'
 import SelectionOverlay from '@/components/graph/SelectionOverlay.vue'
 import SelectionToolbox from '@/components/graph/SelectionToolbox.vue'
@@ -65,6 +72,7 @@ import { useContextMenuTranslation } from '@/composables/useContextMenuTranslati
 import { useCopy } from '@/composables/useCopy'
 import { useGlobalLitegraph } from '@/composables/useGlobalLitegraph'
 import { useLitegraphSettings } from '@/composables/useLitegraphSettings'
+import { useMinimap } from '@/composables/useMinimap'
 import { usePaste } from '@/composables/usePaste'
 import { useWorkflowAutoSave } from '@/composables/useWorkflowAutoSave'
 import { useWorkflowPersistence } from '@/composables/useWorkflowPersistence'
@@ -111,6 +119,10 @@ const selectionToolboxEnabled = computed(() =>
   settingStore.get('Comfy.Canvas.SelectionToolbox')
 )
 
+const minimapRef = ref<InstanceType<typeof MiniMap>>()
+const minimapEnabled = computed(() => settingStore.get('Comfy.Minimap.Visible'))
+const minimap = useMinimap()
+
 watchEffect(() => {
   nodeDefStore.showDeprecated = settingStore.get('Comfy.Node.ShowDeprecated')
 })
@@ -346,6 +358,13 @@ onMounted(async () => {
     }
   )
 
+  whenever(
+    () => minimapRef.value,
+    (ref) => {
+      minimap.setMinimapRef(ref)
+    }
+  )
+
   whenever(
     () => useCanvasStore().canvas,
     (canvas) => {

src/components/graph/GraphCanvasMenu.vue

@@ -56,6 +56,15 @@
       data-testid="toggle-link-visibility-button"
       @click="() => commandStore.execute('Comfy.Canvas.ToggleLinkVisibility')"
     />
+    <Button
+      v-tooltip.left="t('graphCanvasMenu.toggleMinimap') + ' (Alt + m)'"
+      severity="secondary"
+      :icon="'pi pi-map'"
+      :aria-label="$t('graphCanvasMenu.toggleMinimap')"
+      :class="{ 'minimap-active': minimapVisible }"
+      data-testid="toggle-minimap-button"
+      @click="() => commandStore.execute('Comfy.Canvas.ToggleMinimap')"
+    />
   </ButtonGroup>
 </template>
 
@@ -75,6 +84,7 @@ const commandStore = useCommandStore()
 const canvasStore = useCanvasStore()
 const settingStore = useSettingStore()
 
+const minimapVisible = computed(() => settingStore.get('Comfy.Minimap.Visible'))
 const linkHidden = computed(
   () => settingStore.get('Comfy.LinkRenderMode') === LiteGraph.HIDDEN_LINK
 )
@@ -107,4 +117,15 @@ const stopRepeat = () => {
   margin: 0;
   border-radius: 0;
 }
+
+.p-button.minimap-active {
+  background-color: var(--p-button-primary-background);
+  border-color: var(--p-button-primary-border-color);
+  color: var(--p-button-primary-color);
+}
+
+.p-button.minimap-active:hover {
+  background-color: var(--p-button-primary-hover-background);
+  border-color: var(--p-button-primary-hover-border-color);
+}
 </style>

src/components/graph/MiniMap.vue

@@ -0,0 +1,88 @@
+<template>
+  <div
+    v-if="visible && initialized"
+    ref="containerRef"
+    class="litegraph-minimap absolute bottom-[20px] right-[90px] z-[1000]"
+    :style="containerStyles"
+    @mousedown="handleMouseDown"
+    @mousemove="handleMouseMove"
+    @mouseup="handleMouseUp"
+    @mouseleave="handleMouseUp"
+    @wheel="handleWheel"
+  >
+    <canvas
+      ref="canvasRef"
+      :width="width"
+      :height="height"
+      class="minimap-canvas"
+    />
+    <div class="minimap-viewport" :style="viewportStyles" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, onUnmounted, watch } from 'vue'
+
+import { useMinimap } from '@/composables/useMinimap'
+import { useCanvasStore } from '@/stores/graphStore'
+
+const minimap = useMinimap()
+const canvasStore = useCanvasStore()
+
+const {
+  initialized,
+  visible,
+  containerRef,
+  canvasRef,
+  containerStyles,
+  viewportStyles,
+  width,
+  height,
+  init,
+  destroy,
+  handleMouseDown,
+  handleMouseMove,
+  handleMouseUp,
+  handleWheel
+} = minimap
+
+watch(
+  () => canvasStore.canvas,
+  async (canvas) => {
+    if (canvas && !initialized.value) {
+      await init()
+    }
+  },
+  { immediate: true }
+)
+
+onMounted(async () => {
+  if (canvasStore.canvas) {
+    await init()
+  }
+})
+
+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/composables/canvas/useCanvasTransformSync.ts

@@ -0,0 +1,136 @@
+import { LGraphCanvas } from '@comfyorg/litegraph'
+import { onUnmounted, ref } from 'vue'
+
+import { useCanvasStore } from '@/stores/graphStore'
+
+interface CanvasTransformSyncOptions {
+  /**
+   * Whether to automatically start syncing when canvas is available
+   * @default true
+   */
+  autoStart?: boolean
+  /**
+   * Called when sync starts
+   */
+  onStart?: () => void
+  /**
+   * Called when sync stops
+   */
+  onStop?: () => void
+}
+
+interface CanvasTransform {
+  scale: number
+  offsetX: number
+  offsetY: number
+}
+
+/**
+ * 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, and ensures proper cleanup.
+ *
+ * The sync function typically reads canvas.ds properties like offset and scale to keep
+ * Vue components aligned with the canvas coordinate system.
+ *
+ * @example
+ * ```ts
+ * const syncWithCanvas = (canvas: LGraphCanvas) => {
+ *   canvas.ds.scale
+ *   canvas.ds.offset
+ * }
+ *
+ * const { isActive, startSync, stopSync } = useCanvasTransformSync(
+ *   syncWithCanvas,
+ *   {
+ *     autoStart: false,
+ *     onStart: () => emit('rafStatusChange', true),
+ *     onStop: () => emit('rafStatusChange', false)
+ *   }
+ * )
+ * ```
+ */
+export function useCanvasTransformSync(
+  syncFn: (canvas: LGraphCanvas) => void,
+  options: CanvasTransformSyncOptions = {}
+) {
+  const { onStart, onStop, autoStart = true } = options
+  const { getCanvas } = useCanvasStore()
+
+  const isActive = ref(false)
+  let rafId: number | null = null
+  let lastTransform: CanvasTransform = {
+    scale: 0,
+    offsetX: 0,
+    offsetY: 0
+  }
+
+  const hasTransformChanged = (canvas: LGraphCanvas): boolean => {
+    const ds = canvas.ds
+    return (
+      ds.scale !== lastTransform.scale ||
+      ds.offset[0] !== lastTransform.offsetX ||
+      ds.offset[1] !== lastTransform.offsetY
+    )
+  }
+
+  const sync = () => {
+    if (!isActive.value) return
+
+    const canvas = getCanvas()
+    if (!canvas) return
+
+    try {
+      // Only run sync if transform actually changed
+      if (hasTransformChanged(canvas)) {
+        lastTransform = {
+          scale: canvas.ds.scale,
+          offsetX: canvas.ds.offset[0],
+          offsetY: canvas.ds.offset[1]
+        }
+
+        syncFn(canvas)
+      }
+    } catch (error) {
+      console.error('Canvas transform sync error:', error)
+    }
+
+    rafId = requestAnimationFrame(sync)
+  }
+
+  const startSync = () => {
+    if (isActive.value) return
+
+    isActive.value = true
+    onStart?.()
+
+    // Reset last transform to force initial sync
+    lastTransform = { scale: 0, offsetX: 0, offsetY: 0 }
+
+    sync()
+  }
+
+  const stopSync = () => {
+    isActive.value = false
+
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
+
+    onStop?.()
+  }
+
+  onUnmounted(stopSync)
+
+  if (autoStart) {
+    startSync()
+  }
+
+  return {
+    isActive,
+    startSync,
+    stopSync
+  }
+}

src/composables/useCoreCommands.ts

@@ -317,6 +317,19 @@ export function useCoreCommands(): ComfyCommand[] {
         }
       })()
     },
+    {
+      id: 'Comfy.Canvas.ToggleMinimap',
+      icon: 'pi pi-map',
+      label: 'Canvas Toggle Minimap',
+      versionAdded: '1.24.1',
+      function: async () => {
+        const settingStore = useSettingStore()
+        await settingStore.set(
+          'Comfy.Minimap.Visible',
+          !settingStore.get('Comfy.Minimap.Visible')
+        )
+      }
+    },
     {
       id: 'Comfy.QueuePrompt',
       icon: 'pi pi-play',

src/composables/useMinimap.ts

@@ -0,0 +1,685 @@
+import type { LGraphNode } from '@comfyorg/litegraph'
+import { useRafFn, useThrottleFn } from '@vueuse/core'
+import { computed, nextTick, ref, watch } from 'vue'
+
+import { useCanvasTransformSync } from '@/composables/canvas/useCanvasTransformSync'
+import type { NodeId } from '@/schemas/comfyWorkflowSchema'
+import { api } from '@/scripts/api'
+import { useCanvasStore } from '@/stores/graphStore'
+import { useSettingStore } from '@/stores/settingStore'
+
+interface GraphCallbacks {
+  onNodeAdded?: (node: LGraphNode) => void
+  onNodeRemoved?: (node: LGraphNode) => void
+  onConnectionChange?: (node: LGraphNode) => void
+}
+
+export function useMinimap() {
+  const settingStore = useSettingStore()
+  const canvasStore = useCanvasStore()
+
+  const containerRef = ref<HTMLDivElement>()
+  const canvasRef = ref<HTMLCanvasElement>()
+  const minimapRef = ref<any>(null)
+
+  const visible = ref(true)
+
+  const initialized = ref(false)
+  const bounds = ref({
+    minX: 0,
+    minY: 0,
+    maxX: 0,
+    maxY: 0,
+    width: 0,
+    height: 0
+  })
+  const scale = ref(1)
+  const isDragging = ref(false)
+  const viewportTransform = ref({ x: 0, y: 0, width: 0, height: 0 })
+
+  const needsFullRedraw = ref(true)
+  const needsBoundsUpdate = ref(true)
+  const lastNodeCount = ref(0)
+  const nodeStatesCache = new Map<NodeId, string>()
+  const linksCache = ref<string>('')
+
+  const updateFlags = ref({
+    bounds: false,
+    nodes: false,
+    connections: false,
+    viewport: false
+  })
+
+  const width = 250
+  const height = 200
+  const nodeColor = '#0B8CE999'
+  const linkColor = '#F99614'
+  const slotColor = '#F99614'
+  const viewportColor = '#FFF'
+  const backgroundColor = '#15161C'
+  const borderColor = '#333'
+
+  const containerRect = ref({
+    left: 0,
+    top: 0,
+    width: width,
+    height: height
+  })
+
+  const canvasDimensions = ref({
+    width: 0,
+    height: 0
+  })
+
+  const updateContainerRect = () => {
+    if (!containerRef.value) return
+
+    const rect = containerRef.value.getBoundingClientRect()
+    containerRect.value = {
+      left: rect.left,
+      top: rect.top,
+      width: rect.width,
+      height: rect.height
+    }
+  }
+
+  const updateCanvasDimensions = () => {
+    const c = canvas.value
+    if (!c) return
+
+    const canvasEl = c.canvas
+    const dpr = window.devicePixelRatio || 1
+
+    canvasDimensions.value = {
+      width: canvasEl.clientWidth || canvasEl.width / dpr,
+      height: canvasEl.clientHeight || canvasEl.height / dpr
+    }
+  }
+
+  const canvas = computed(() => canvasStore.canvas)
+  const graph = computed(() => canvas.value?.graph)
+
+  const containerStyles = computed(() => ({
+    width: `${width}px`,
+    height: `${height}px`,
+    backgroundColor: backgroundColor,
+    border: `1px solid ${borderColor}`,
+    borderRadius: '8px'
+  }))
+
+  const viewportStyles = computed(() => ({
+    transform: `translate(${viewportTransform.value.x}px, ${viewportTransform.value.y}px)`,
+    width: `${viewportTransform.value.width}px`,
+    height: `${viewportTransform.value.height}px`,
+    border: `2px solid ${viewportColor}`,
+    backgroundColor: `${viewportColor}33`,
+    willChange: 'transform',
+    backfaceVisibility: 'hidden' as const,
+    perspective: '1000px',
+    pointerEvents: 'none' as const
+  }))
+
+  const calculateGraphBounds = () => {
+    const g = graph.value
+    if (!g?._nodes || g._nodes.length === 0) {
+      return { minX: 0, minY: 0, maxX: 100, maxY: 100, width: 100, height: 100 }
+    }
+
+    let minX = Infinity
+    let minY = Infinity
+    let maxX = -Infinity
+    let maxY = -Infinity
+
+    for (const node of g._nodes) {
+      minX = Math.min(minX, node.pos[0])
+      minY = Math.min(minY, node.pos[1])
+      maxX = Math.max(maxX, node.pos[0] + node.size[0])
+      maxY = Math.max(maxY, node.pos[1] + node.size[1])
+    }
+
+    let currentWidth = maxX - minX
+    let currentHeight = maxY - minY
+
+    // Enforce minimum viewport dimensions for better visualization
+    const minViewportWidth = 2500
+    const minViewportHeight = 2000
+
+    if (currentWidth < minViewportWidth) {
+      const padding = (minViewportWidth - currentWidth) / 2
+      minX -= padding
+      maxX += padding
+      currentWidth = minViewportWidth
+    }
+
+    if (currentHeight < minViewportHeight) {
+      const padding = (minViewportHeight - currentHeight) / 2
+      minY -= padding
+      maxY += padding
+      currentHeight = minViewportHeight
+    }
+
+    return {
+      minX,
+      minY,
+      maxX,
+      maxY,
+      width: currentWidth,
+      height: currentHeight
+    }
+  }
+
+  const calculateScale = () => {
+    if (bounds.value.width === 0 || bounds.value.height === 0) {
+      return 1
+    }
+
+    const scaleX = width / bounds.value.width
+    const scaleY = height / bounds.value.height
+
+    // Apply 0.9 factor to provide padding/gap between nodes and minimap borders
+    return Math.min(scaleX, scaleY) * 0.9
+  }
+
+  const renderNodes = (
+    ctx: CanvasRenderingContext2D,
+    offsetX: number,
+    offsetY: number
+  ) => {
+    const g = graph.value
+    if (!g || !g._nodes || g._nodes.length === 0) return
+
+    for (const node of g._nodes) {
+      const x = (node.pos[0] - bounds.value.minX) * scale.value + offsetX
+      const y = (node.pos[1] - bounds.value.minY) * scale.value + offsetY
+      const w = node.size[0] * scale.value
+      const h = node.size[1] * scale.value
+
+      // Render solid node blocks
+      ctx.fillStyle = nodeColor
+      ctx.fillRect(x, y, w, h)
+    }
+  }
+
+  const renderConnections = (
+    ctx: CanvasRenderingContext2D,
+    offsetX: number,
+    offsetY: number
+  ) => {
+    const g = graph.value
+    if (!g) return
+
+    ctx.strokeStyle = linkColor
+    ctx.lineWidth = 1.4
+
+    const slotRadius = 3.7 * Math.max(scale.value, 0.5) // Larger slots that scale
+    const connections: Array<{
+      x1: number
+      y1: number
+      x2: number
+      y2: number
+    }> = []
+
+    for (const node of g._nodes) {
+      if (!node.outputs) continue
+
+      const x1 = (node.pos[0] - bounds.value.minX) * scale.value + offsetX
+      const y1 = (node.pos[1] - bounds.value.minY) * scale.value + offsetY
+
+      for (const output of node.outputs) {
+        if (!output.links) continue
+
+        for (const linkId of output.links) {
+          const link = g.links[linkId]
+          if (!link) continue
+
+          const targetNode = g.getNodeById(link.target_id)
+          if (!targetNode) continue
+
+          const x2 =
+            (targetNode.pos[0] - bounds.value.minX) * scale.value + offsetX
+          const y2 =
+            (targetNode.pos[1] - bounds.value.minY) * scale.value + offsetY
+
+          const outputX = x1 + node.size[0] * scale.value
+          const outputY = y1 + node.size[1] * scale.value * 0.2
+          const inputX = x2
+          const inputY = y2 + targetNode.size[1] * scale.value * 0.2
+
+          // Draw connection line
+          ctx.beginPath()
+          ctx.moveTo(outputX, outputY)
+          ctx.lineTo(inputX, inputY)
+          ctx.stroke()
+
+          connections.push({ x1: outputX, y1: outputY, x2: inputX, y2: inputY })
+        }
+      }
+    }
+
+    // Render connection slots on top
+    ctx.fillStyle = slotColor
+    for (const conn of connections) {
+      // Output slot
+      ctx.beginPath()
+      ctx.arc(conn.x1, conn.y1, slotRadius, 0, Math.PI * 2)
+      ctx.fill()
+
+      // Input slot
+      ctx.beginPath()
+      ctx.arc(conn.x2, conn.y2, slotRadius, 0, Math.PI * 2)
+      ctx.fill()
+    }
+  }
+
+  const renderMinimap = () => {
+    if (!canvasRef.value || !graph.value) return
+
+    const ctx = canvasRef.value.getContext('2d')
+    if (!ctx) return
+
+    // Fast path for 0 nodes - just show background
+    if (!graph.value._nodes || graph.value._nodes.length === 0) {
+      ctx.clearRect(0, 0, width, height)
+      return
+    }
+
+    const needsRedraw =
+      needsFullRedraw.value ||
+      updateFlags.value.nodes ||
+      updateFlags.value.connections
+
+    if (needsRedraw) {
+      ctx.clearRect(0, 0, width, height)
+
+      const offsetX = (width - bounds.value.width * scale.value) / 2
+      const offsetY = (height - bounds.value.height * scale.value) / 2
+
+      renderNodes(ctx, offsetX, offsetY)
+      renderConnections(ctx, offsetX, offsetY)
+
+      needsFullRedraw.value = false
+      updateFlags.value.nodes = false
+      updateFlags.value.connections = false
+    }
+  }
+
+  const updateViewport = () => {
+    const c = canvas.value
+    if (!c) return
+
+    if (
+      canvasDimensions.value.width === 0 ||
+      canvasDimensions.value.height === 0
+    ) {
+      updateCanvasDimensions()
+    }
+
+    const ds = c.ds
+
+    const viewportWidth = canvasDimensions.value.width / ds.scale
+    const viewportHeight = canvasDimensions.value.height / ds.scale
+
+    const worldX = -ds.offset[0]
+    const worldY = -ds.offset[1]
+
+    const centerOffsetX = (width - bounds.value.width * scale.value) / 2
+    const centerOffsetY = (height - bounds.value.height * scale.value) / 2
+
+    viewportTransform.value = {
+      x: (worldX - bounds.value.minX) * scale.value + centerOffsetX,
+      y: (worldY - bounds.value.minY) * scale.value + centerOffsetY,
+      width: viewportWidth * scale.value,
+      height: viewportHeight * scale.value
+    }
+
+    updateFlags.value.viewport = false
+  }
+
+  const updateMinimap = () => {
+    if (needsBoundsUpdate.value || updateFlags.value.bounds) {
+      bounds.value = calculateGraphBounds()
+      scale.value = calculateScale()
+      needsBoundsUpdate.value = false
+      updateFlags.value.bounds = false
+      needsFullRedraw.value = true
+    }
+
+    if (
+      needsFullRedraw.value ||
+      updateFlags.value.nodes ||
+      updateFlags.value.connections
+    ) {
+      renderMinimap()
+    }
+  }
+
+  const checkForChanges = useThrottleFn(() => {
+    const g = graph.value
+    if (!g) return
+
+    let structureChanged = false
+    let positionChanged = false
+    let connectionChanged = false
+
+    if (g._nodes.length !== lastNodeCount.value) {
+      structureChanged = true
+      lastNodeCount.value = g._nodes.length
+    }
+
+    for (const node of g._nodes) {
+      const key = node.id
+      const currentState = `${node.pos[0]},${node.pos[1]},${node.size[0]},${node.size[1]}`
+
+      if (nodeStatesCache.get(key) !== currentState) {
+        positionChanged = true
+        nodeStatesCache.set(key, currentState)
+      }
+    }
+
+    const currentLinks = JSON.stringify(g.links || {})
+    if (currentLinks !== linksCache.value) {
+      connectionChanged = true
+      linksCache.value = currentLinks
+    }
+
+    const currentNodeIds = new Set(g._nodes.map((n) => n.id))
+    for (const [nodeId] of nodeStatesCache) {
+      if (!currentNodeIds.has(nodeId)) {
+        nodeStatesCache.delete(nodeId)
+        structureChanged = true
+      }
+    }
+
+    if (structureChanged || positionChanged) {
+      updateFlags.value.bounds = true
+      updateFlags.value.nodes = true
+    }
+
+    if (connectionChanged) {
+      updateFlags.value.connections = true
+    }
+
+    if (structureChanged || positionChanged || connectionChanged) {
+      updateMinimap()
+    }
+  }, 500)
+
+  const { pause: pauseChangeDetection, resume: resumeChangeDetection } =
+    useRafFn(
+      async () => {
+        if (visible.value) {
+          await checkForChanges()
+        }
+      },
+      { immediate: false }
+    )
+
+  const { startSync: startViewportSync, stopSync: stopViewportSync } =
+    useCanvasTransformSync(updateViewport, { autoStart: false })
+
+  const handleMouseDown = (e: MouseEvent) => {
+    isDragging.value = true
+    updateContainerRect()
+    handleMouseMove(e)
+  }
+
+  const handleMouseMove = (e: MouseEvent) => {
+    if (!isDragging.value || !canvasRef.value || !canvas.value) return
+
+    const x = e.clientX - containerRect.value.left
+    const y = e.clientY - containerRect.value.top
+
+    const offsetX = (width - bounds.value.width * scale.value) / 2
+    const offsetY = (height - bounds.value.height * scale.value) / 2
+
+    const worldX = (x - offsetX) / scale.value + bounds.value.minX
+    const worldY = (y - offsetY) / scale.value + bounds.value.minY
+
+    centerViewOn(worldX, worldY)
+  }
+
+  const handleMouseUp = () => {
+    isDragging.value = false
+  }
+
+  const handleWheel = (e: WheelEvent) => {
+    e.preventDefault()
+
+    const c = canvas.value
+    if (!c) return
+
+    if (
+      containerRect.value.left === 0 &&
+      containerRect.value.top === 0 &&
+      containerRef.value
+    ) {
+      updateContainerRect()
+    }
+
+    const ds = c.ds
+    const delta = e.deltaY > 0 ? 0.9 : 1.1
+
+    const newScale = ds.scale * delta
+
+    const MIN_SCALE = 0.1
+    const MAX_SCALE = 10
+
+    if (newScale < MIN_SCALE || newScale > MAX_SCALE) return
+
+    const x = e.clientX - containerRect.value.left
+    const y = e.clientY - containerRect.value.top
+
+    const offsetX = (width - bounds.value.width * scale.value) / 2
+    const offsetY = (height - bounds.value.height * scale.value) / 2
+
+    const worldX = (x - offsetX) / scale.value + bounds.value.minX
+    const worldY = (y - offsetY) / scale.value + bounds.value.minY
+
+    ds.scale = newScale
+
+    centerViewOn(worldX, worldY)
+  }
+
+  const centerViewOn = (worldX: number, worldY: number) => {
+    const c = canvas.value
+    if (!c) return
+
+    if (
+      canvasDimensions.value.width === 0 ||
+      canvasDimensions.value.height === 0
+    ) {
+      updateCanvasDimensions()
+    }
+
+    const ds = c.ds
+
+    const viewportWidth = canvasDimensions.value.width / ds.scale
+    const viewportHeight = canvasDimensions.value.height / ds.scale
+
+    ds.offset[0] = -(worldX - viewportWidth / 2)
+    ds.offset[1] = -(worldY - viewportHeight / 2)
+
+    updateFlags.value.viewport = true
+
+    c.setDirty(true, true)
+  }
+
+  let originalCallbacks: GraphCallbacks = {}
+
+  const handleGraphChanged = useThrottleFn(() => {
+    needsFullRedraw.value = true
+    updateFlags.value.bounds = true
+    updateFlags.value.nodes = true
+    updateFlags.value.connections = true
+    updateMinimap()
+  }, 500)
+
+  const setupEventListeners = () => {
+    const g = graph.value
+    if (!g) return
+
+    originalCallbacks = {
+      onNodeAdded: g.onNodeAdded,
+      onNodeRemoved: g.onNodeRemoved,
+      onConnectionChange: g.onConnectionChange
+    }
+
+    g.onNodeAdded = function (node) {
+      originalCallbacks.onNodeAdded?.call(this, node)
+
+      void handleGraphChanged()
+    }
+
+    g.onNodeRemoved = function (node) {
+      originalCallbacks.onNodeRemoved?.call(this, node)
+      nodeStatesCache.delete(node.id)
+      void handleGraphChanged()
+    }
+
+    g.onConnectionChange = function (node) {
+      originalCallbacks.onConnectionChange?.call(this, node)
+
+      void handleGraphChanged()
+    }
+  }
+
+  const cleanupEventListeners = () => {
+    const g = graph.value
+    if (!g) return
+
+    if (originalCallbacks.onNodeAdded !== undefined) {
+      g.onNodeAdded = originalCallbacks.onNodeAdded
+    }
+    if (originalCallbacks.onNodeRemoved !== undefined) {
+      g.onNodeRemoved = originalCallbacks.onNodeRemoved
+    }
+    if (originalCallbacks.onConnectionChange !== undefined) {
+      g.onConnectionChange = originalCallbacks.onConnectionChange
+    }
+  }
+
+  const init = async () => {
+    if (initialized.value) return
+
+    visible.value = settingStore.get('Comfy.Minimap.Visible')
+
+    if (canvas.value && graph.value) {
+      setupEventListeners()
+
+      api.addEventListener('graphChanged', handleGraphChanged)
+
+      if (containerRef.value) {
+        updateContainerRect()
+      }
+      updateCanvasDimensions()
+
+      window.addEventListener('resize', updateContainerRect)
+      window.addEventListener('scroll', updateContainerRect)
+      window.addEventListener('resize', updateCanvasDimensions)
+
+      needsFullRedraw.value = true
+      updateFlags.value.bounds = true
+      updateFlags.value.nodes = true
+      updateFlags.value.connections = true
+      updateFlags.value.viewport = true
+
+      updateMinimap()
+      updateViewport()
+
+      if (visible.value) {
+        resumeChangeDetection()
+        startViewportSync()
+      }
+      initialized.value = true
+    }
+  }
+
+  const destroy = () => {
+    pauseChangeDetection()
+    stopViewportSync()
+    cleanupEventListeners()
+
+    api.removeEventListener('graphChanged', handleGraphChanged)
+
+    window.removeEventListener('resize', updateContainerRect)
+    window.removeEventListener('scroll', updateContainerRect)
+    window.removeEventListener('resize', updateCanvasDimensions)
+
+    nodeStatesCache.clear()
+    initialized.value = false
+  }
+
+  watch(
+    canvas,
+    async (newCanvas, oldCanvas) => {
+      if (oldCanvas) {
+        cleanupEventListeners()
+        pauseChangeDetection()
+        stopViewportSync()
+        api.removeEventListener('graphChanged', handleGraphChanged)
+        window.removeEventListener('resize', updateContainerRect)
+        window.removeEventListener('scroll', updateContainerRect)
+        window.removeEventListener('resize', updateCanvasDimensions)
+      }
+      if (newCanvas && !initialized.value) {
+        await init()
+      }
+    },
+    { immediate: true }
+  )
+
+  watch(visible, async (isVisible) => {
+    if (isVisible) {
+      if (containerRef.value) {
+        updateContainerRect()
+      }
+      updateCanvasDimensions()
+
+      needsFullRedraw.value = true
+      updateFlags.value.bounds = true
+      updateFlags.value.nodes = true
+      updateFlags.value.connections = true
+      updateFlags.value.viewport = true
+
+      await nextTick()
+
+      updateMinimap()
+      updateViewport()
+      resumeChangeDetection()
+      startViewportSync()
+    } else {
+      pauseChangeDetection()
+      stopViewportSync()
+    }
+  })
+
+  const toggle = async () => {
+    visible.value = !visible.value
+    await settingStore.set('Comfy.Minimap.Visible', visible.value)
+  }
+
+  const setMinimapRef = (ref: any) => {
+    minimapRef.value = ref
+  }
+
+  return {
+    visible: computed(() => visible.value),
+    initialized: computed(() => initialized.value),
+
+    containerRef,
+    canvasRef,
+    containerStyles,
+    viewportStyles,
+    width,
+    height,
+
+    init,
+    destroy,
+    toggle,
+    handleMouseDown,
+    handleMouseMove,
+    handleMouseUp,
+    handleWheel,
+    setMinimapRef
+  }
+}

src/constants/coreKeybindings.ts

@@ -181,5 +181,12 @@ export const CORE_KEYBINDINGS: Keybinding[] = [
       shift: true
     },
     commandId: 'Comfy.Graph.ConvertToSubgraph'
+  },
+  {
+    combo: {
+      key: 'm',
+      alt: true
+    },
+    commandId: 'Comfy.Canvas.ToggleMinimap'
   }
 ]

src/constants/coreSettings.ts

@@ -824,6 +824,13 @@ export const CORE_SETTINGS: SettingParams[] = [
     defaultValue: false,
     versionAdded: '1.15.12'
   },
+  {
+    id: 'Comfy.Minimap.Visible',
+    name: 'Display minimap on canvas',
+    type: 'hidden',
+    defaultValue: true,
+    versionAdded: '1.25.0'
+  },
   {
     id: 'Comfy.Workflow.AutoSaveDelay',
     name: 'Auto Save Delay (ms)',

src/locales/en/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "Canvas Toggle Lock"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "Canvas Toggle Minimap"
+  },
   "Comfy_Canvas_ToggleSelected_Pin": {
     "label": "Pin/Unpin Selected Items"
   },

src/locales/en/main.json

@@ -872,7 +872,8 @@
     "fitView": "Fit View",
     "selectMode": "Select Mode",
     "panMode": "Pan Mode",
-    "toggleLinkVisibility": "Toggle Link Visibility"
+    "toggleLinkVisibility": "Toggle Link Visibility",
+    "toggleMinimap": "Toggle Minimap"
   },
   "groupNode": {
     "create": "Create group node",
@@ -948,6 +949,7 @@
     "Resize Selected Nodes": "Resize Selected Nodes",
     "Canvas Toggle Link Visibility": "Canvas Toggle Link Visibility",
     "Canvas Toggle Lock": "Canvas Toggle Lock",
+    "Canvas Toggle Minimap": "Canvas Toggle Minimap",
     "Pin/Unpin Selected Items": "Pin/Unpin Selected Items",
     "Bypass/Unbypass Selected Nodes": "Bypass/Unbypass Selected Nodes",
     "Collapse/Expand Selected Nodes": "Collapse/Expand Selected Nodes",

src/locales/es/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "Alternar bloqueo en lienzo"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "Lienzo Alternar Minimapa"
+  },
   "Comfy_Canvas_ToggleSelectedNodes_Bypass": {
     "label": "Omitir/No omitir nodos seleccionados"
   },

src/locales/es/main.json

@@ -403,6 +403,7 @@
     "resetView": "Restablecer vista",
     "selectMode": "Modo de selección",
     "toggleLinkVisibility": "Alternar visibilidad de enlace",
+    "toggleMinimap": "Alternar minimapa",
     "zoomIn": "Acercar",
     "zoomOut": "Alejar"
   },
@@ -738,6 +739,7 @@
     "Bypass/Unbypass Selected Nodes": "Evitar/No evitar nodos seleccionados",
     "Canvas Toggle Link Visibility": "Alternar visibilidad de enlace en lienzo",
     "Canvas Toggle Lock": "Alternar bloqueo en lienzo",
+    "Canvas Toggle Minimap": "Lienzo: Alternar minimapa",
     "Check for Updates": "Buscar actualizaciones",
     "Clear Pending Tasks": "Borrar tareas pendientes",
     "Clear Workflow": "Borrar flujo de trabajo",

src/locales/fr/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "Basculer le verrouillage du canevas"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "Basculer la mini-carte du canevas"
+  },
   "Comfy_Canvas_ToggleSelectedNodes_Bypass": {
     "label": "Contourner/Ne pas contourner les nœuds sélectionnés"
   },

src/locales/fr/main.json

@@ -403,6 +403,7 @@
     "resetView": "Réinitialiser la vue",
     "selectMode": "Mode sélection",
     "toggleLinkVisibility": "Basculer la visibilité des liens",
+    "toggleMinimap": "Afficher/Masquer la mini-carte",
     "zoomIn": "Zoom avant",
     "zoomOut": "Zoom arrière"
   },
@@ -738,6 +739,7 @@
     "Bypass/Unbypass Selected Nodes": "Contourner/Ne pas contourner les nœuds sélectionnés",
     "Canvas Toggle Link Visibility": "Basculer la visibilité du lien de la toile",
     "Canvas Toggle Lock": "Basculer le verrouillage de la toile",
+    "Canvas Toggle Minimap": "Basculer la mini-carte du canevas",
     "Check for Updates": "Vérifier les mises à jour",
     "Clear Pending Tasks": "Effacer les tâches en attente",
     "Clear Workflow": "Effacer le flux de travail",

src/locales/ja/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "キャンバスのロックを切り替える"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "キャンバス ミニマップ切り替え"
+  },
   "Comfy_Canvas_ToggleSelectedNodes_Bypass": {
     "label": "選択したノードのバイパス/バイパス解除"
   },

src/locales/ja/main.json

@@ -403,6 +403,7 @@
     "resetView": "ビューをリセット",
     "selectMode": "選択モード",
     "toggleLinkVisibility": "リンクの表示切り替え",
+    "toggleMinimap": "ミニマップの切り替え",
     "zoomIn": "拡大",
     "zoomOut": "縮小"
   },
@@ -738,6 +739,7 @@
     "Bypass/Unbypass Selected Nodes": "選択したノードのバイパス/バイパス解除",
     "Canvas Toggle Link Visibility": "キャンバスのリンク表示を切り替え",
     "Canvas Toggle Lock": "キャンバスのロックを切り替え",
+    "Canvas Toggle Minimap": "キャンバス ミニマップの切り替え",
     "Check for Updates": "更新を確認する",
     "Clear Pending Tasks": "保留中のタスクをクリア",
     "Clear Workflow": "ワークフローをクリア",

src/locales/ko/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "캔버스 잠금 토글"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "캔버스 미니맵 전환"
+  },
   "Comfy_Canvas_ToggleSelectedNodes_Bypass": {
     "label": "선택한 노드 우회/우회 해제"
   },

src/locales/ko/main.json

@@ -403,6 +403,7 @@
     "resetView": "보기 재설정",
     "selectMode": "선택 모드",
     "toggleLinkVisibility": "링크 가시성 전환",
+    "toggleMinimap": "미니맵 전환",
     "zoomIn": "확대",
     "zoomOut": "축소"
   },
@@ -738,6 +739,7 @@
     "Bypass/Unbypass Selected Nodes": "선택한 노드 우회/우회 해제",
     "Canvas Toggle Link Visibility": "캔버스 토글 링크 가시성",
     "Canvas Toggle Lock": "캔버스 토글 잠금",
+    "Canvas Toggle Minimap": "캔버스 미니맵 전환",
     "Check for Updates": "업데이트 확인",
     "Clear Pending Tasks": "보류 중인 작업 제거하기",
     "Clear Workflow": "워크플로 지우기",

src/locales/ru/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "Переключить блокировку холста"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "Полотно: переключить миникарту"
+  },
   "Comfy_Canvas_ToggleSelectedNodes_Bypass": {
     "label": "Обход/Необход выбранных нод"
   },

src/locales/ru/main.json

@@ -403,6 +403,7 @@
     "resetView": "Сбросить вид",
     "selectMode": "Выбрать режим",
     "toggleLinkVisibility": "Переключить видимость ссылок",
+    "toggleMinimap": "Показать/скрыть миникарту",
     "zoomIn": "Увеличить",
     "zoomOut": "Уменьшить"
   },
@@ -738,6 +739,7 @@
     "Bypass/Unbypass Selected Nodes": "Обойти/восстановить выбранные ноды",
     "Canvas Toggle Link Visibility": "Переключение видимости ссылки на холст",
     "Canvas Toggle Lock": "Переключение блокировки холста",
+    "Canvas Toggle Minimap": "Показать/скрыть миникарту на холсте",
     "Check for Updates": "Проверить наличие обновлений",
     "Clear Pending Tasks": "Очистить ожидающие задачи",
     "Clear Workflow": "Очистить рабочий процесс",

src/locales/zh-TW/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "畫布切換鎖定"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "畫布切換小地圖"
+  },
   "Comfy_Canvas_ToggleSelectedNodes_Bypass": {
     "label": "略過/取消略過選取的節點"
   },

src/locales/zh-TW/main.json

@@ -403,6 +403,7 @@
     "resetView": "重設視圖",
     "selectMode": "選取模式",
     "toggleLinkVisibility": "切換連結顯示",
+    "toggleMinimap": "切換小地圖",
     "zoomIn": "放大",
     "zoomOut": "縮小"
   },
@@ -738,6 +739,7 @@
     "Bypass/Unbypass Selected Nodes": "繞過/取消繞過選取節點",
     "Canvas Toggle Link Visibility": "切換連結可見性",
     "Canvas Toggle Lock": "切換畫布鎖定",
+    "Canvas Toggle Minimap": "畫布切換小地圖",
     "Check for Updates": "檢查更新",
     "Clear Pending Tasks": "清除待處理任務",
     "Clear Workflow": "清除工作流程",

src/locales/zh/commands.json

@@ -71,6 +71,9 @@
   "Comfy_Canvas_ToggleLock": {
     "label": "锁定视图"
   },
+  "Comfy_Canvas_ToggleMinimap": {
+    "label": "畫布切換小地圖"
+  },
   "Comfy_Canvas_ToggleSelectedNodes_Bypass": {
     "label": "忽略/取消忽略选中节点"
   },

src/locales/zh/main.json

@@ -403,6 +403,7 @@
     "resetView": "重置视图",
     "selectMode": "选择模式",
     "toggleLinkVisibility": "切换连线可见性",
+    "toggleMinimap": "切換小地圖",
     "zoomIn": "放大",
     "zoomOut": "缩小"
   },
@@ -738,6 +739,7 @@
     "Bypass/Unbypass Selected Nodes": "忽略/取消忽略选定节点",
     "Canvas Toggle Link Visibility": "切换连线可见性",
     "Canvas Toggle Lock": "切换视图锁定",
+    "Canvas Toggle Minimap": "畫布切換小地圖",
     "Check for Updates": "检查更新",
     "Clear Pending Tasks": "清除待处理任务",
     "Clear Workflow": "清除工作流",

src/schemas/apiSchema.ts

@@ -475,6 +475,7 @@ const zSettings = z.object({
   'Comfy.TutorialCompleted': z.boolean(),
   'Comfy.InstalledVersion': z.string().nullable(),
   'Comfy.Node.AllowImageSizeDraw': z.boolean(),
+  'Comfy.Minimap.Visible': z.boolean(),
   'Comfy.Canvas.NavigationMode': z.string(),
   'Comfy-Desktop.AutoUpdate': z.boolean(),
   'Comfy-Desktop.SendStatistics': z.boolean(),

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

@@ -0,0 +1,129 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
+
+import { useCanvasTransformSync } from '@/composables/canvas/useCanvasTransformSync'
+
+// Mock canvas store
+let mockGetCanvas = vi.fn()
+vi.mock('@/stores/graphStore', () => ({
+  useCanvasStore: vi.fn(() => ({
+    getCanvas: mockGetCanvas
+  }))
+}))
+
+describe('useCanvasTransformSync', () => {
+  let mockCanvas: { ds: { scale: number; offset: [number, number] } }
+  let syncFn: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    mockCanvas = {
+      ds: {
+        scale: 1,
+        offset: [0, 0]
+      }
+    }
+    syncFn = vi.fn()
+    mockGetCanvas = vi.fn(() => mockCanvas)
+    vi.clearAllMocks()
+  })
+
+  it('should not call syncFn when transform has not changed', async () => {
+    const { startSync } = useCanvasTransformSync(syncFn, { autoStart: false })
+
+    startSync()
+    await nextTick()
+
+    // Should call once initially
+    expect(syncFn).toHaveBeenCalledTimes(1)
+
+    // Wait for next RAF cycle
+    await new Promise((resolve) => requestAnimationFrame(resolve))
+
+    // Should not call again since transform didn't change
+    expect(syncFn).toHaveBeenCalledTimes(1)
+  })
+
+  it('should call syncFn when scale changes', async () => {
+    const { startSync } = useCanvasTransformSync(syncFn, { autoStart: false })
+
+    startSync()
+    await nextTick()
+
+    expect(syncFn).toHaveBeenCalledTimes(1)
+
+    // Change scale
+    mockCanvas.ds.scale = 2
+
+    // Wait for next RAF cycle
+    await new Promise((resolve) => requestAnimationFrame(resolve))
+
+    expect(syncFn).toHaveBeenCalledTimes(2)
+  })
+
+  it('should call syncFn when offset changes', async () => {
+    const { startSync } = useCanvasTransformSync(syncFn, { autoStart: false })
+
+    startSync()
+    await nextTick()
+
+    expect(syncFn).toHaveBeenCalledTimes(1)
+
+    // Change offset
+    mockCanvas.ds.offset = [10, 20]
+
+    // Wait for next RAF cycles
+    await new Promise((resolve) => requestAnimationFrame(resolve))
+
+    expect(syncFn).toHaveBeenCalledTimes(2)
+  })
+
+  it('should stop calling syncFn after stopSync is called', async () => {
+    const { startSync, stopSync } = useCanvasTransformSync(syncFn, {
+      autoStart: false
+    })
+
+    startSync()
+    await nextTick()
+
+    expect(syncFn).toHaveBeenCalledTimes(1)
+
+    stopSync()
+
+    // Change transform after stopping
+    mockCanvas.ds.scale = 2
+
+    // Wait for RAF cycle
+    await new Promise((resolve) => requestAnimationFrame(resolve))
+
+    // Should not call again
+    expect(syncFn).toHaveBeenCalledTimes(1)
+  })
+
+  it('should handle null canvas gracefully', async () => {
+    mockGetCanvas.mockReturnValue(null)
+    const { startSync } = useCanvasTransformSync(syncFn, { autoStart: false })
+
+    startSync()
+    await nextTick()
+
+    // Should not call syncFn with null canvas
+    expect(syncFn).not.toHaveBeenCalled()
+  })
+
+  it('should call onStart and onStop callbacks', () => {
+    const onStart = vi.fn()
+    const onStop = vi.fn()
+
+    const { startSync, stopSync } = useCanvasTransformSync(syncFn, {
+      autoStart: false,
+      onStart,
+      onStop
+    })
+
+    startSync()
+    expect(onStart).toHaveBeenCalledTimes(1)
+
+    stopSync()
+    expect(onStop).toHaveBeenCalledTimes(1)
+  })
+})

tests-ui/tests/composables/useMinimap.test.ts

@@ -0,0 +1,815 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
+
+const flushPromises = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+const mockPause = vi.fn()
+const mockResume = vi.fn()
+
+vi.mock('@vueuse/core', () => {
+  const callbacks: Record<string, () => void> = {}
+  let callbackId = 0
+
+  return {
+    useRafFn: vi.fn((callback, options) => {
+      const id = callbackId++
+      callbacks[id] = callback
+
+      if (options?.immediate !== false) {
+        void Promise.resolve().then(() => callback())
+      }
+
+      return {
+        pause: mockPause,
+        resume: vi.fn(() => {
+          mockResume()
+          void Promise.resolve().then(() => callbacks[id]?.())
+        })
+      }
+    }),
+    useThrottleFn: vi.fn((callback) => {
+      return (...args: any[]) => {
+        return callback(...args)
+      }
+    })
+  }
+})
+
+let mockCanvas: any
+let mockGraph: any
+
+const setupMocks = () => {
+  const mockNodes = [
+    {
+      id: 'node1',
+      pos: [0, 0],
+      size: [100, 50],
+      color: '#ff0000',
+      constructor: { color: '#666' },
+      outputs: [
+        {
+          links: ['link1']
+        }
+      ]
+    },
+    {
+      id: 'node2',
+      pos: [200, 100],
+      size: [150, 75],
+      constructor: { color: '#666' },
+      outputs: []
+    }
+  ]
+
+  mockGraph = {
+    _nodes: mockNodes,
+    links: {
+      link1: {
+        id: 'link1',
+        target_id: 'node2'
+      }
+    },
+    getNodeById: vi.fn((id) => mockNodes.find((n) => n.id === id)),
+    setDirtyCanvas: vi.fn(),
+    onNodeAdded: null,
+    onNodeRemoved: null,
+    onConnectionChange: null
+  }
+
+  mockCanvas = {
+    graph: mockGraph,
+    canvas: {
+      width: 1000,
+      height: 800,
+      clientWidth: 1000,
+      clientHeight: 800
+    },
+    ds: {
+      scale: 1,
+      offset: [0, 0]
+    },
+    setDirty: vi.fn()
+  }
+}
+
+setupMocks()
+
+const defaultCanvasStore = {
+  canvas: mockCanvas,
+  getCanvas: () => defaultCanvasStore.canvas
+}
+
+const defaultSettingStore = {
+  get: vi.fn().mockReturnValue(true),
+  set: vi.fn().mockResolvedValue(undefined)
+}
+
+vi.mock('@/stores/graphStore', () => ({
+  useCanvasStore: vi.fn(() => defaultCanvasStore)
+}))
+
+vi.mock('@/stores/settingStore', () => ({
+  useSettingStore: vi.fn(() => defaultSettingStore)
+}))
+
+vi.mock('@/scripts/api', () => ({
+  api: {
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn()
+  }
+}))
+
+const { useMinimap } = await import('@/composables/useMinimap')
+const { api } = await import('@/scripts/api')
+
+describe('useMinimap', () => {
+  let mockCanvas: any
+  let mockGraph: any
+  let mockCanvasElement: any
+  let mockContainerElement: any
+  let mockContext2D: any
+
+  const createAndInitializeMinimap = async () => {
+    const minimap = useMinimap()
+    minimap.containerRef.value = mockContainerElement
+    minimap.canvasRef.value = mockCanvasElement
+    await minimap.init()
+    await nextTick()
+    await flushPromises()
+    return minimap
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    mockPause.mockClear()
+    mockResume.mockClear()
+
+    mockContext2D = {
+      clearRect: vi.fn(),
+      fillRect: vi.fn(),
+      strokeRect: vi.fn(),
+      beginPath: vi.fn(),
+      moveTo: vi.fn(),
+      lineTo: vi.fn(),
+      stroke: vi.fn(),
+      arc: vi.fn(),
+      fill: vi.fn(),
+      fillStyle: '',
+      strokeStyle: '',
+      lineWidth: 0
+    }
+
+    mockCanvasElement = {
+      getContext: vi.fn().mockReturnValue(mockContext2D),
+      width: 250,
+      height: 200,
+      clientWidth: 250,
+      clientHeight: 200
+    }
+
+    const mockRect = {
+      left: 100,
+      top: 100,
+      width: 250,
+      height: 200,
+      right: 350,
+      bottom: 300,
+      x: 100,
+      y: 100
+    }
+
+    mockContainerElement = {
+      getBoundingClientRect: vi.fn(() => ({ ...mockRect }))
+    }
+
+    const mockNodes = [
+      {
+        id: 'node1',
+        pos: [0, 0],
+        size: [100, 50],
+        color: '#ff0000',
+        constructor: { color: '#666' },
+        outputs: [
+          {
+            links: ['link1']
+          }
+        ]
+      },
+      {
+        id: 'node2',
+        pos: [200, 100],
+        size: [150, 75],
+        constructor: { color: '#666' },
+        outputs: []
+      }
+    ]
+
+    mockGraph = {
+      _nodes: mockNodes,
+      links: {
+        link1: {
+          id: 'link1',
+          target_id: 'node2'
+        }
+      },
+      getNodeById: vi.fn((id) => mockNodes.find((n) => n.id === id)),
+      setDirtyCanvas: vi.fn(),
+      onNodeAdded: null,
+      onNodeRemoved: null,
+      onConnectionChange: null
+    }
+
+    mockCanvas = {
+      graph: mockGraph,
+      canvas: {
+        width: 1000,
+        height: 800,
+        clientWidth: 1000,
+        clientHeight: 800
+      },
+      ds: {
+        scale: 1,
+        offset: [0, 0]
+      },
+      setDirty: vi.fn()
+    }
+
+    defaultCanvasStore.canvas = mockCanvas
+
+    defaultSettingStore.get = vi.fn().mockReturnValue(true)
+    defaultSettingStore.set = vi.fn().mockResolvedValue(undefined)
+
+    Object.defineProperty(window, 'devicePixelRatio', {
+      writable: true,
+      configurable: true,
+      value: 1
+    })
+
+    window.addEventListener = vi.fn()
+    window.removeEventListener = vi.fn()
+  })
+
+  describe('initialization', () => {
+    it('should initialize with default values', () => {
+      const originalCanvas = defaultCanvasStore.canvas
+      defaultCanvasStore.canvas = null
+
+      const minimap = useMinimap()
+
+      expect(minimap.width).toBe(250)
+      expect(minimap.height).toBe(200)
+      expect(minimap.visible.value).toBe(true)
+      expect(minimap.initialized.value).toBe(false)
+
+      defaultCanvasStore.canvas = originalCanvas
+    })
+
+    it('should initialize minimap when canvas is available', async () => {
+      const minimap = useMinimap()
+
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      expect(minimap.initialized.value).toBe(true)
+      expect(defaultSettingStore.get).toHaveBeenCalledWith(
+        'Comfy.Minimap.Visible'
+      )
+      expect(api.addEventListener).toHaveBeenCalledWith(
+        'graphChanged',
+        expect.any(Function)
+      )
+
+      if (minimap.visible.value) {
+        expect(mockResume).toHaveBeenCalled()
+      }
+    })
+
+    it('should not initialize without canvas and graph', async () => {
+      const originalCanvas = defaultCanvasStore.canvas
+      defaultCanvasStore.canvas = null
+
+      const minimap = useMinimap()
+      await minimap.init()
+
+      expect(minimap.initialized.value).toBe(false)
+      expect(api.addEventListener).not.toHaveBeenCalled()
+
+      defaultCanvasStore.canvas = originalCanvas
+    })
+
+    it('should setup event listeners on graph', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      expect(mockGraph.onNodeAdded).toBeDefined()
+      expect(mockGraph.onNodeRemoved).toBeDefined()
+      expect(mockGraph.onConnectionChange).toBeDefined()
+    })
+
+    it('should handle visibility from settings', async () => {
+      defaultSettingStore.get.mockReturnValue(false)
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      expect(minimap.visible.value).toBe(false)
+      expect(mockResume).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('destroy', () => {
+    it('should cleanup all resources', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+      minimap.destroy()
+
+      expect(mockPause).toHaveBeenCalled()
+      expect(api.removeEventListener).toHaveBeenCalledWith(
+        'graphChanged',
+        expect.any(Function)
+      )
+      expect(window.removeEventListener).toHaveBeenCalled()
+      expect(minimap.initialized.value).toBe(false)
+    })
+
+    it('should restore original graph callbacks', async () => {
+      const originalCallbacks = {
+        onNodeAdded: vi.fn(),
+        onNodeRemoved: vi.fn(),
+        onConnectionChange: vi.fn()
+      }
+
+      mockGraph.onNodeAdded = originalCallbacks.onNodeAdded
+      mockGraph.onNodeRemoved = originalCallbacks.onNodeRemoved
+      mockGraph.onConnectionChange = originalCallbacks.onConnectionChange
+
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+      minimap.destroy()
+
+      expect(mockGraph.onNodeAdded).toBe(originalCallbacks.onNodeAdded)
+      expect(mockGraph.onNodeRemoved).toBe(originalCallbacks.onNodeRemoved)
+      expect(mockGraph.onConnectionChange).toBe(
+        originalCallbacks.onConnectionChange
+      )
+    })
+  })
+
+  describe('toggle', () => {
+    it('should toggle visibility and save to settings', async () => {
+      const minimap = useMinimap()
+      const initialVisibility = minimap.visible.value
+
+      await minimap.toggle()
+
+      expect(minimap.visible.value).toBe(!initialVisibility)
+      expect(defaultSettingStore.set).toHaveBeenCalledWith(
+        'Comfy.Minimap.Visible',
+        !initialVisibility
+      )
+
+      await minimap.toggle()
+
+      expect(minimap.visible.value).toBe(initialVisibility)
+      expect(defaultSettingStore.set).toHaveBeenCalledWith(
+        'Comfy.Minimap.Visible',
+        initialVisibility
+      )
+    })
+  })
+
+  describe('rendering', () => {
+    it('should verify context is obtained during render', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      const getContextSpy = vi.spyOn(mockCanvasElement, 'getContext')
+
+      await minimap.init()
+
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      expect(getContextSpy).toHaveBeenCalled()
+      expect(getContextSpy).toHaveBeenCalledWith('2d')
+    })
+
+    it('should render at least once after initialization', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      const renderingOccurred =
+        mockContext2D.clearRect.mock.calls.length > 0 ||
+        mockContext2D.fillRect.mock.calls.length > 0
+
+      if (!renderingOccurred) {
+        console.log('Minimap visible:', minimap.visible.value)
+        console.log('Minimap initialized:', minimap.initialized.value)
+        console.log('Canvas exists:', !!defaultCanvasStore.canvas)
+        console.log('Graph exists:', !!defaultCanvasStore.canvas?.graph)
+      }
+
+      expect(renderingOccurred).toBe(true)
+    })
+
+    it('should not render when context is null', async () => {
+      mockCanvasElement.getContext = vi.fn().mockReturnValue(null)
+
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      expect(mockContext2D.clearRect).not.toHaveBeenCalled()
+
+      mockCanvasElement.getContext = vi.fn().mockReturnValue(mockContext2D)
+    })
+
+    it('should handle empty graph', async () => {
+      const originalNodes = [...mockGraph._nodes]
+      mockGraph._nodes = []
+
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      expect(minimap.initialized.value).toBe(true)
+
+      expect(mockContext2D.fillRect).not.toHaveBeenCalled()
+
+      mockGraph._nodes = originalNodes
+    })
+  })
+
+  describe('mouse interactions', () => {
+    it('should handle mouse down and start dragging', async () => {
+      const minimap = await createAndInitializeMinimap()
+
+      const mouseEvent = new MouseEvent('mousedown', {
+        clientX: 150,
+        clientY: 150
+      })
+
+      minimap.handleMouseDown(mouseEvent)
+
+      expect(mockContainerElement.getBoundingClientRect).toHaveBeenCalled()
+      expect(mockCanvas.setDirty).toHaveBeenCalledWith(true, true)
+    })
+
+    it('should handle mouse move while dragging', async () => {
+      const minimap = await createAndInitializeMinimap()
+
+      const mouseDownEvent = new MouseEvent('mousedown', {
+        clientX: 150,
+        clientY: 150
+      })
+      minimap.handleMouseDown(mouseDownEvent)
+
+      const mouseMoveEvent = new MouseEvent('mousemove', {
+        clientX: 200,
+        clientY: 200
+      })
+      minimap.handleMouseMove(mouseMoveEvent)
+
+      expect(mockCanvas.setDirty).toHaveBeenCalledWith(true, true)
+      expect(mockCanvas.ds.offset).toBeDefined()
+    })
+
+    it('should not move when not dragging', async () => {
+      const minimap = await createAndInitializeMinimap()
+
+      mockCanvas.setDirty.mockClear()
+
+      const mouseMoveEvent = new MouseEvent('mousemove', {
+        clientX: 200,
+        clientY: 200
+      })
+      minimap.handleMouseMove(mouseMoveEvent)
+
+      expect(mockCanvas.setDirty).not.toHaveBeenCalled()
+    })
+
+    it('should handle mouse up to stop dragging', async () => {
+      const minimap = await createAndInitializeMinimap()
+
+      const mouseDownEvent = new MouseEvent('mousedown', {
+        clientX: 150,
+        clientY: 150
+      })
+      minimap.handleMouseDown(mouseDownEvent)
+
+      minimap.handleMouseUp()
+
+      mockCanvas.setDirty.mockClear()
+
+      const mouseMoveEvent = new MouseEvent('mousemove', {
+        clientX: 200,
+        clientY: 200
+      })
+      minimap.handleMouseMove(mouseMoveEvent)
+
+      expect(mockCanvas.setDirty).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('wheel interactions', () => {
+    it('should handle wheel zoom in', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      const wheelEvent = new WheelEvent('wheel', {
+        deltaY: -100,
+        clientX: 150,
+        clientY: 150
+      })
+
+      const preventDefault = vi.fn()
+      Object.defineProperty(wheelEvent, 'preventDefault', {
+        value: preventDefault
+      })
+
+      minimap.handleWheel(wheelEvent)
+
+      expect(preventDefault).toHaveBeenCalled()
+      expect(mockCanvas.ds.scale).toBeCloseTo(1.1)
+      expect(mockCanvas.setDirty).toHaveBeenCalledWith(true, true)
+    })
+
+    it('should handle wheel zoom out', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      const wheelEvent = new WheelEvent('wheel', {
+        deltaY: 100,
+        clientX: 150,
+        clientY: 150
+      })
+
+      const preventDefault = vi.fn()
+      Object.defineProperty(wheelEvent, 'preventDefault', {
+        value: preventDefault
+      })
+
+      minimap.handleWheel(wheelEvent)
+
+      expect(preventDefault).toHaveBeenCalled()
+      expect(mockCanvas.ds.scale).toBeCloseTo(0.9)
+      expect(mockCanvas.setDirty).toHaveBeenCalledWith(true, true)
+    })
+
+    it('should respect zoom limits', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      mockCanvas.ds.scale = 0.1
+
+      const wheelEvent = new WheelEvent('wheel', {
+        deltaY: 100,
+        clientX: 150,
+        clientY: 150
+      })
+
+      const preventDefault = vi.fn()
+      Object.defineProperty(wheelEvent, 'preventDefault', {
+        value: preventDefault
+      })
+
+      minimap.handleWheel(wheelEvent)
+
+      expect(mockCanvas.ds.scale).toBe(0.1)
+    })
+
+    it('should update container rect if needed', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      const wheelEvent = new WheelEvent('wheel', {
+        deltaY: -100,
+        clientX: 150,
+        clientY: 150
+      })
+
+      const preventDefault = vi.fn()
+      Object.defineProperty(wheelEvent, 'preventDefault', {
+        value: preventDefault
+      })
+
+      minimap.handleWheel(wheelEvent)
+
+      expect(mockContainerElement.getBoundingClientRect).toHaveBeenCalled()
+    })
+  })
+
+  describe('viewport updates', () => {
+    it('should update viewport transform correctly', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+      await nextTick()
+
+      const viewportStyles = minimap.viewportStyles.value
+
+      expect(viewportStyles).toBeDefined()
+      expect(viewportStyles.transform).toMatch(
+        /translate\(-?\d+(\.\d+)?px, -?\d+(\.\d+)?px\)/
+      )
+      expect(viewportStyles.width).toMatch(/\d+(\.\d+)?px/)
+      expect(viewportStyles.height).toMatch(/\d+(\.\d+)?px/)
+      expect(viewportStyles.border).toBe('2px solid #FFF')
+    })
+
+    it('should handle canvas dimension updates', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      mockCanvas.canvas.clientWidth = 1200
+      mockCanvas.canvas.clientHeight = 900
+
+      const resizeHandler = (window.addEventListener as any).mock.calls.find(
+        (call: any) => call[0] === 'resize'
+      )?.[1]
+
+      if (resizeHandler) {
+        resizeHandler()
+      }
+
+      await nextTick()
+
+      expect(minimap.viewportStyles.value).toBeDefined()
+    })
+  })
+
+  describe('graph change handling', () => {
+    it('should handle node addition', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      const newNode = {
+        id: 'node3',
+        pos: [300, 200],
+        size: [100, 100],
+        constructor: { color: '#666' }
+      }
+
+      mockGraph._nodes.push(newNode)
+      if (mockGraph.onNodeAdded) {
+        mockGraph.onNodeAdded(newNode)
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 600))
+    })
+
+    it('should handle node removal', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      const removedNode = mockGraph._nodes[0]
+      mockGraph._nodes.splice(0, 1)
+
+      if (mockGraph.onNodeRemoved) {
+        mockGraph.onNodeRemoved(removedNode)
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 600))
+    })
+
+    it('should handle connection changes', async () => {
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      if (mockGraph.onConnectionChange) {
+        mockGraph.onConnectionChange(mockGraph._nodes[0])
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 600))
+    })
+  })
+
+  describe('container styles', () => {
+    it('should provide correct container styles', () => {
+      const minimap = useMinimap()
+      const styles = minimap.containerStyles.value
+
+      expect(styles.width).toBe('250px')
+      expect(styles.height).toBe('200px')
+      expect(styles.backgroundColor).toBe('#15161C')
+      expect(styles.border).toBe('1px solid #333')
+      expect(styles.borderRadius).toBe('8px')
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle missing node outputs', async () => {
+      mockGraph._nodes[0].outputs = null
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await expect(minimap.init()).resolves.not.toThrow()
+      expect(minimap.initialized.value).toBe(true)
+    })
+
+    it('should handle invalid link references', async () => {
+      mockGraph.links.link1.target_id = 'invalid-node'
+      mockGraph.getNodeById.mockReturnValue(null)
+
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await expect(minimap.init()).resolves.not.toThrow()
+      expect(minimap.initialized.value).toBe(true)
+    })
+
+    it('should handle high DPI displays', async () => {
+      window.devicePixelRatio = 2
+
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      expect(minimap.initialized.value).toBe(true)
+    })
+
+    it('should handle nodes without color', async () => {
+      mockGraph._nodes[0].color = undefined
+
+      const minimap = useMinimap()
+      minimap.containerRef.value = mockContainerElement
+      minimap.canvasRef.value = mockCanvasElement
+
+      await minimap.init()
+
+      const renderMinimap = (minimap as any).renderMinimap
+      if (renderMinimap) {
+        renderMinimap()
+      }
+
+      expect(mockContext2D.fillRect).toHaveBeenCalled()
+      expect(mockContext2D.fillStyle).toBeDefined()
+    })
+  })
+
+  describe('setMinimapRef', () => {
+    it('should set minimap reference', () => {
+      const minimap = useMinimap()
+      const ref = { value: 'test-ref' }
+
+      minimap.setMinimapRef(ref)
+
+      expect(() => minimap.setMinimapRef(ref)).not.toThrow()
+    })
+  })
+})