From 0e7bdcf209d8765d4b92d2b5b33732249c5aebc4 Mon Sep 17 00:00:00 2001
From: Terry Jia <terryjia88@gmail.com>
Date: Fri, 18 Jul 2025 23:00:48 -0400
Subject: [PATCH] minimap

---
 src/components/graph/GraphCanvas.vue     |  18 +
 src/components/graph/GraphCanvasMenu.vue |  22 +
 src/components/graph/MiniMap.vue         |  88 ++++
 src/composables/useCoreCommands.ts       |  10 +
 src/composables/useMinimap.ts            | 631 +++++++++++++++++++++++
 src/constants/coreKeybindings.ts         |   7 +
 src/constants/coreSettings.ts            |  17 +
 src/locales/en/commands.json             |   4 +
 src/locales/en/main.json                 |   3 +-
 src/schemas/apiSchema.ts                 |   2 +
 10 files changed, 801 insertions(+), 1 deletion(-)
 create mode 100644 src/components/graph/MiniMap.vue
 create mode 100644 src/composables/useMinimap.ts

diff --git a/src/components/graph/GraphCanvas.vue b/src/components/graph/GraphCanvas.vue
index 3c0d20f99..52183bcc6 100644
--- a/src/components/graph/GraphCanvas.vue
+++ b/src/components/graph/GraphCanvas.vue
@@ -19,6 +19,12 @@
         <SubgraphBreadcrumb />
       </div>
       <GraphCanvasMenu v-if="canvasMenuEnabled" class="pointer-events-auto" />
+
+      <MiniMap
+        v-if="comfyAppReady"
+        ref="minimapRef"
+        class="pointer-events-auto"
+      />
     </template>
   </LiteGraphCanvasSplitterOverlay>
   <GraphCanvasMenu v-if="!betaMenuEnabled && canvasMenuEnabled" />
@@ -53,6 +59,7 @@ import BottomPanel from '@/components/bottomPanel/BottomPanel.vue'
 import SubgraphBreadcrumb from '@/components/breadcrumb/SubgraphBreadcrumb.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'
@@ -67,6 +74,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'
@@ -114,6 +122,9 @@ const selectionToolboxEnabled = computed(() =>
   settingStore.get('Comfy.Canvas.SelectionToolbox')
 )
 
+const minimapRef = ref<InstanceType<typeof MiniMap>>()
+const minimap = useMinimap()
+
 watchEffect(() => {
   nodeDefStore.showDeprecated = settingStore.get('Comfy.Node.ShowDeprecated')
 })
@@ -345,6 +356,13 @@ onMounted(async () => {
     }
   )
 
+  whenever(
+    () => minimapRef.value,
+    (ref) => {
+      minimap.setMinimapRef(ref)
+    }
+  )
+
   whenever(
     () => useCanvasStore().canvas,
     (canvas) => {
diff --git a/src/components/graph/GraphCanvasMenu.vue b/src/components/graph/GraphCanvasMenu.vue
index 8f5d036cb..a89f72998 100644
--- a/src/components/graph/GraphCanvasMenu.vue
+++ b/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') + ' [Atl + M]'"
+      severity="secondary"
+      :icon="'pi pi-map'"
+      :aria-label="$t('graphCanvasMenu.toggleMinimap')"
+      :class="{ 'minimap-active': minimap.visible.value }"
+      data-testid="toggle-minimap-button"
+      @click="() => commandStore.execute('Comfy.Canvas.ToggleMinimap')"
+    />
   </ButtonGroup>
 </template>
 
@@ -66,6 +75,7 @@ import ButtonGroup from 'primevue/buttongroup'
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 
+import { useMinimap } from '@/composables/useMinimap'
 import { useCommandStore } from '@/stores/commandStore'
 import { useCanvasStore } from '@/stores/graphStore'
 import { useSettingStore } from '@/stores/settingStore'
@@ -74,6 +84,7 @@ const { t } = useI18n()
 const commandStore = useCommandStore()
 const canvasStore = useCanvasStore()
 const settingStore = useSettingStore()
+const minimap = useMinimap()
 
 const linkHidden = computed(
   () => settingStore.get('Comfy.LinkRenderMode') === LiteGraph.HIDDEN_LINK
@@ -107,4 +118,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>
diff --git a/src/components/graph/MiniMap.vue b/src/components/graph/MiniMap.vue
new file mode 100644
index 000000000..dd4583b47
--- /dev/null
+++ b/src/components/graph/MiniMap.vue
@@ -0,0 +1,88 @@
+<template>
+  <div
+    v-if="visible"
+    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>
diff --git a/src/composables/useCoreCommands.ts b/src/composables/useCoreCommands.ts
index 5e4cf6125..5ba604542 100644
--- a/src/composables/useCoreCommands.ts
+++ b/src/composables/useCoreCommands.ts
@@ -7,6 +7,7 @@ import {
 import { Point } from '@comfyorg/litegraph'
 
 import { useFirebaseAuthActions } from '@/composables/auth/useFirebaseAuthActions'
+import { useMinimap } from '@/composables/useMinimap'
 import {
   DEFAULT_DARK_COLOR_PALETTE,
   DEFAULT_LIGHT_COLOR_PALETTE
@@ -313,6 +314,15 @@ export function useCoreCommands(): ComfyCommand[] {
         }
       })()
     },
+    {
+      id: 'Comfy.Canvas.ToggleMinimap',
+      icon: 'pi pi-map',
+      label: 'Canvas Toggle Minimap',
+      versionAdded: '1.24.1',
+      function: async () => {
+        await useMinimap().toggle()
+      }
+    },
     {
       id: 'Comfy.QueuePrompt',
       icon: 'pi pi-play',
diff --git a/src/composables/useMinimap.ts b/src/composables/useMinimap.ts
new file mode 100644
index 000000000..0094a7946
--- /dev/null
+++ b/src/composables/useMinimap.ts
@@ -0,0 +1,631 @@
+import { useRafFn, useThrottleFn } from '@vueuse/core'
+import { computed, nextTick, ref, watch } from 'vue'
+
+import type { NodeId } from '@/schemas/comfyWorkflowSchema'
+import { api } from '@/scripts/api'
+import { useCanvasStore } from '@/stores/graphStore'
+import { useSettingStore } from '@/stores/settingStore'
+
+const globalState = {
+  visible: ref(true),
+  minimapRef: ref<any>(null),
+  initialized: false
+}
+
+export function useMinimap() {
+  const settingStore = useSettingStore()
+  const canvasStore = useCanvasStore()
+
+  const containerRef = ref<HTMLDivElement>()
+  const canvasRef = ref<HTMLCanvasElement>()
+
+  const visible = globalState.visible
+
+  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 = '#666'
+  const viewportColor = '#FFF'
+  const backgroundColor = '#1e1e1e'
+  const borderColor = '#444'
+
+  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}`
+  }))
+
+  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])
+    }
+
+    return {
+      minX,
+      minY,
+      maxX,
+      maxY,
+      width: maxX - minX,
+      height: maxY - minY
+    }
+  }
+
+  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
+
+    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
+
+      ctx.fillStyle = node.color || node.constructor.color || nodeColor
+      ctx.fillRect(x, y, w, h)
+
+      ctx.strokeStyle = 'rgba(0,0,0,0.2)'
+      ctx.lineWidth = 0.5
+      ctx.strokeRect(x, y, w, h)
+    }
+  }
+
+  const renderConnections = (
+    ctx: CanvasRenderingContext2D,
+    offsetX: number,
+    offsetY: number
+  ) => {
+    const g = graph.value
+    if (!g) return
+
+    ctx.strokeStyle = 'rgba(255,255,255,0.2)'
+    ctx.lineWidth = 2
+
+    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
+
+          ctx.beginPath()
+          ctx.moveTo(
+            x1 + node.size[0] * scale.value,
+            y1 + node.size[1] * scale.value * 0.2
+          )
+          ctx.lineTo(x2, y2 + targetNode.size[1] * scale.value * 0.2)
+          ctx.stroke()
+        }
+      }
+    }
+  }
+
+  const renderMinimap = () => {
+    if (!canvasRef.value || !graph.value) return
+
+    const ctx = canvasRef.value.getContext('2d')
+    if (!ctx) 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
+
+      renderConnections(ctx, offsetX, offsetY)
+      renderNodes(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()
+    }
+  }, settingStore.get('Comfy.Minimap.RefreshDelay'))
+
+  const { pause: pauseChangeDetection, resume: resumeChangeDetection } =
+    useRafFn(
+      async () => {
+        if (visible.value) {
+          await checkForChanges()
+        }
+      },
+      { immediate: false }
+    )
+
+  const { pause: pauseViewportUpdate, resume: resumeViewportUpdate } = useRafFn(
+    () => {
+      updateViewport()
+    },
+    { immediate: false, fpsLimit: 60 }
+  )
+
+  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: any = {}
+
+  const handleGraphChanged = useThrottleFn(() => {
+    needsFullRedraw.value = true
+    updateFlags.value.bounds = true
+    updateFlags.value.nodes = true
+    updateFlags.value.connections = true
+    updateMinimap()
+  }, settingStore.get('Comfy.Minimap.RefreshDelay'))
+
+  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()
+        resumeViewportUpdate()
+      }
+      initialized.value = true
+    }
+  }
+
+  const destroy = () => {
+    pauseChangeDetection()
+    pauseViewportUpdate()
+    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()
+        pauseViewportUpdate()
+        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()
+      resumeViewportUpdate()
+    } else {
+      pauseChangeDetection()
+      pauseViewportUpdate()
+    }
+  })
+
+  const toggle = async () => {
+    visible.value = !visible.value
+    await settingStore.set('Comfy.Minimap.Visible', visible.value)
+  }
+
+  const setMinimapRef = (ref: any) => {
+    globalState.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
+  }
+}
diff --git a/src/constants/coreKeybindings.ts b/src/constants/coreKeybindings.ts
index 34f2cc39e..ee4d833d2 100644
--- a/src/constants/coreKeybindings.ts
+++ b/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'
   }
 ]
diff --git a/src/constants/coreSettings.ts b/src/constants/coreSettings.ts
index c3a9b30af..526d087c9 100644
--- a/src/constants/coreSettings.ts
+++ b/src/constants/coreSettings.ts
@@ -812,6 +812,23 @@ 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.24.1'
+  },
+  {
+    id: 'Comfy.Minimap.RefreshDelay',
+    category: ['LiteGraph', 'Canvas', 'MinimapRefreshDelay'],
+    name: 'Minimap refresh delay (ms)',
+    defaultValue: 256,
+    type: 'number',
+    tooltip:
+      'The smaller the value, the smoother it will be, but it will consume more performance. After modification, you need to refresh the page for it to take effect.',
+    versionAdded: '1.24.1'
+  },
   {
     id: 'Comfy.Workflow.AutoSaveDelay',
     name: 'Auto Save Delay (ms)',
diff --git a/src/locales/en/commands.json b/src/locales/en/commands.json
index 780ec7164..5c055852f 100644
--- a/src/locales/en/commands.json
+++ b/src/locales/en/commands.json
@@ -245,5 +245,9 @@
   "Workspace_ToggleSidebarTab_workflows": {
     "label": "Toggle Workflows Sidebar",
     "tooltip": "Workflows"
+  },
+  "Workspace_ToggleMinimap": {
+    "label": "Toggle Minimap",
+    "tooltip": "Minimap"
   }
 }
\ No newline at end of file
diff --git a/src/locales/en/main.json b/src/locales/en/main.json
index df92e481b..2078c7910 100644
--- a/src/locales/en/main.json
+++ b/src/locales/en/main.json
@@ -862,7 +862,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",
diff --git a/src/schemas/apiSchema.ts b/src/schemas/apiSchema.ts
index 12fbe2981..ae6faf7ca 100644
--- a/src/schemas/apiSchema.ts
+++ b/src/schemas/apiSchema.ts
@@ -457,6 +457,8 @@ const zSettings = z.object({
   'Comfy.TutorialCompleted': z.boolean(),
   'Comfy.InstalledVersion': z.string().nullable(),
   'Comfy.Node.AllowImageSizeDraw': z.boolean(),
+  'Comfy.Minimap.Visible': z.boolean(),
+  'Comfy.Minimap.RefreshDelay': z.number(),
   'Comfy-Desktop.AutoUpdate': z.boolean(),
   'Comfy-Desktop.SendStatistics': z.boolean(),
   'Comfy-Desktop.WindowStyle': z.string(),