From dee00edc5f90873226516f4d558e797bb8a4f895 Mon Sep 17 00:00:00 2001
From: Christian Byrne <cbyrne@comfy.org>
Date: Sat, 31 May 2025 00:39:39 -0700
Subject: [PATCH] [feat] Add node library sorting and grouping controls (#4024)

Co-authored-by: github-actions <github-actions@github.com>
---
 .../sidebar/tabs/NodeLibrarySidebarTab.vue    | 142 ++++++--
 src/locales/en/main.json                      |  18 +-
 src/locales/es/main.json                      |  18 +-
 src/locales/fr/main.json                      |  18 +-
 src/locales/ja/main.json                      |  18 +-
 src/locales/ko/main.json                      |  18 +-
 src/locales/ru/main.json                      |  18 +-
 src/locales/zh/main.json                      |  18 +-
 src/services/nodeOrganizationService.ts       | 159 +++++++++
 src/stores/nodeDefStore.ts                    |  18 +-
 src/types/nodeOrganizationTypes.ts            |  44 +++
 .../services/nodeOrganizationService.test.ts  | 330 ++++++++++++++++++
 12 files changed, 788 insertions(+), 31 deletions(-)
 create mode 100644 src/services/nodeOrganizationService.ts
 create mode 100644 src/types/nodeOrganizationTypes.ts
 create mode 100644 tests-ui/tests/services/nodeOrganizationService.test.ts

diff --git a/src/components/sidebar/tabs/NodeLibrarySidebarTab.vue b/src/components/sidebar/tabs/NodeLibrarySidebarTab.vue
index 89af4b29b..4f78cfb51 100644
--- a/src/components/sidebar/tabs/NodeLibrarySidebarTab.vue
+++ b/src/components/sidebar/tabs/NodeLibrarySidebarTab.vue
@@ -13,13 +13,58 @@
         @click="nodeBookmarkTreeExplorerRef?.addNewBookmarkFolder()"
       />
       <Button
-        v-tooltip.bottom="$t('sideToolbar.nodeLibraryTab.sortOrder')"
-        class="sort-button"
-        :icon="alphabeticalSort ? 'pi pi-sort-alpha-down' : 'pi pi-sort-alt'"
+        v-tooltip.bottom="$t('sideToolbar.nodeLibraryTab.groupBy')"
+        :icon="selectedGroupingIcon"
         text
         severity="secondary"
-        @click="alphabeticalSort = !alphabeticalSort"
+        @click="groupingPopover?.toggle($event)"
       />
+      <Button
+        v-tooltip.bottom="$t('sideToolbar.nodeLibraryTab.sortMode')"
+        :icon="selectedSortingIcon"
+        text
+        severity="secondary"
+        @click="sortingPopover?.toggle($event)"
+      />
+      <Button
+        v-tooltip.bottom="$t('sideToolbar.nodeLibraryTab.resetView')"
+        icon="pi pi-refresh"
+        text
+        severity="secondary"
+        @click="resetOrganization"
+      />
+      <Popover ref="groupingPopover">
+        <div class="flex flex-col gap-1 p-2">
+          <Button
+            v-for="option in groupingOptions"
+            :key="option.id"
+            :icon="option.icon"
+            :label="$t(option.label)"
+            text
+            :severity="
+              selectedGroupingId === option.id ? 'primary' : 'secondary'
+            "
+            class="justify-start"
+            @click="selectGrouping(option.id)"
+          />
+        </div>
+      </Popover>
+      <Popover ref="sortingPopover">
+        <div class="flex flex-col gap-1 p-2">
+          <Button
+            v-for="option in sortingOptions"
+            :key="option.id"
+            :icon="option.icon"
+            :label="$t(option.label)"
+            text
+            :severity="
+              selectedSortingId === option.id ? 'primary' : 'secondary'
+            "
+            class="justify-start"
+            @click="selectSorting(option.id)"
+          />
+        </div>
+      </Popover>
     </template>
     <template #header>
       <SearchBox
@@ -62,6 +107,7 @@
 </template>
 
 <script setup lang="ts">
+import { useLocalStorage } from '@vueuse/core'
 import Button from 'primevue/button'
 import Divider from 'primevue/divider'
 import Popover from 'primevue/popover'
@@ -76,16 +122,20 @@ import SidebarTabTemplate from '@/components/sidebar/tabs/SidebarTabTemplate.vue
 import NodeTreeLeaf from '@/components/sidebar/tabs/nodeLibrary/NodeTreeLeaf.vue'
 import { useTreeExpansion } from '@/composables/useTreeExpansion'
 import { useLitegraphService } from '@/services/litegraphService'
-import { useNodeBookmarkStore } from '@/stores/nodeBookmarkStore'
 import {
-  ComfyNodeDefImpl,
-  buildNodeDefTree,
-  useNodeDefStore
-} from '@/stores/nodeDefStore'
+  DEFAULT_GROUPING_ID,
+  DEFAULT_SORTING_ID,
+  nodeOrganizationService
+} from '@/services/nodeOrganizationService'
+import { useNodeBookmarkStore } from '@/stores/nodeBookmarkStore'
+import { ComfyNodeDefImpl, useNodeDefStore } from '@/stores/nodeDefStore'
+import type {
+  GroupingStrategyId,
+  SortingStrategyId
+} from '@/types/nodeOrganizationTypes'
 import type { TreeNode } from '@/types/treeExplorerTypes'
 import type { TreeExplorerNode } from '@/types/treeExplorerTypes'
 import { FuseFilterWithValue } from '@/utils/fuseUtil'
-import { sortedTree } from '@/utils/treeUtil'
 
 import NodeBookmarkTreeExplorer from './nodeLibrary/NodeBookmarkTreeExplorer.vue'
 
@@ -98,13 +148,67 @@ const nodeBookmarkTreeExplorerRef = ref<InstanceType<
   typeof NodeBookmarkTreeExplorer
 > | null>(null)
 const searchFilter = ref<InstanceType<typeof Popover> | null>(null)
-const alphabeticalSort = ref(false)
+const groupingPopover = ref<InstanceType<typeof Popover> | null>(null)
+const sortingPopover = ref<InstanceType<typeof Popover> | null>(null)
+const selectedGroupingId = useLocalStorage<GroupingStrategyId>(
+  'Comfy.NodeLibrary.GroupBy',
+  DEFAULT_GROUPING_ID
+)
+const selectedSortingId = useLocalStorage<SortingStrategyId>(
+  'Comfy.NodeLibrary.SortBy',
+  DEFAULT_SORTING_ID
+)
 
 const searchQuery = ref<string>('')
 
+const groupingOptions = computed(() =>
+  nodeOrganizationService.getGroupingStrategies().map((strategy) => ({
+    id: strategy.id,
+    label: strategy.label,
+    icon: strategy.icon
+  }))
+)
+const sortingOptions = computed(() =>
+  nodeOrganizationService.getSortingStrategies().map((strategy) => ({
+    id: strategy.id,
+    label: strategy.label,
+    icon: strategy.icon
+  }))
+)
+
+const selectedGroupingIcon = computed(() =>
+  nodeOrganizationService.getGroupingIcon(selectedGroupingId.value)
+)
+const selectedSortingIcon = computed(() =>
+  nodeOrganizationService.getSortingIcon(selectedSortingId.value)
+)
+
+const selectGrouping = (groupingId: string) => {
+  selectedGroupingId.value = groupingId as GroupingStrategyId
+  groupingPopover.value?.hide()
+}
+const selectSorting = (sortingId: string) => {
+  selectedSortingId.value = sortingId as SortingStrategyId
+  sortingPopover.value?.hide()
+}
+
+const resetOrganization = () => {
+  selectedGroupingId.value = DEFAULT_GROUPING_ID
+  selectedSortingId.value = DEFAULT_SORTING_ID
+}
+
 const root = computed(() => {
-  const root = filteredRoot.value || nodeDefStore.nodeTree
-  return alphabeticalSort.value ? sortedTree(root, { groupLeaf: true }) : root
+  // Determine which nodes to use
+  const nodes =
+    filteredNodeDefs.value.length > 0
+      ? filteredNodeDefs.value
+      : nodeDefStore.visibleNodeDefs
+
+  // Use the service to organize nodes
+  return nodeOrganizationService.organizeNodes(nodes, {
+    groupBy: selectedGroupingId.value,
+    sortBy: selectedSortingId.value
+  })
 })
 
 const renderedRoot = computed<TreeExplorerNode<ComfyNodeDefImpl>>(() => {
@@ -144,12 +248,6 @@ const renderedRoot = computed<TreeExplorerNode<ComfyNodeDefImpl>>(() => {
 })
 
 const filteredNodeDefs = ref<ComfyNodeDefImpl[]>([])
-const filteredRoot = computed<TreeNode | null>(() => {
-  if (!filteredNodeDefs.value.length) {
-    return null
-  }
-  return buildNodeDefTree(filteredNodeDefs.value)
-})
 const filters: Ref<
   (SearchFilter & { filter: FuseFilterWithValue<ComfyNodeDefImpl, string> })[]
 > = ref([])
@@ -175,8 +273,10 @@ const handleSearch = async (query: string) => {
   )
 
   await nextTick()
-  // @ts-expect-error fixme ts strict error
-  expandNode(filteredRoot.value)
+  // Expand the search results tree
+  if (filteredNodeDefs.value.length > 0) {
+    expandNode(root.value)
+  }
 }
 
 const onAddFilter = async (
diff --git a/src/locales/en/main.json b/src/locales/en/main.json
index bcf3f7696..ac7520115 100644
--- a/src/locales/en/main.json
+++ b/src/locales/en/main.json
@@ -416,7 +416,23 @@
     "openWorkflow": "Open workflow in local file system",
     "newBlankWorkflow": "Create a new blank workflow",
     "nodeLibraryTab": {
-      "sortOrder": "Sort Order"
+      "groupBy": "Group By",
+      "sortMode": "Sort Mode",
+      "resetView": "Reset View to Default",
+      "groupStrategies": {
+        "category": "Category",
+        "categoryDesc": "Group by node category",
+        "module": "Module",
+        "moduleDesc": "Group by module source",
+        "source": "Source",
+        "sourceDesc": "Group by source type (Core, Custom, API)"
+      },
+      "sortBy": {
+        "original": "Original",
+        "originalDesc": "Keep original order",
+        "alphabetical": "Alphabetical",
+        "alphabeticalDesc": "Sort alphabetically within groups"
+      }
     },
     "modelLibrary": "Model Library",
     "downloads": "Downloads",
diff --git a/src/locales/es/main.json b/src/locales/es/main.json
index 05cea65a9..77eb8edd6 100644
--- a/src/locales/es/main.json
+++ b/src/locales/es/main.json
@@ -1065,7 +1065,23 @@
     "newBlankWorkflow": "Crear un nuevo flujo de trabajo en blanco",
     "nodeLibrary": "Biblioteca de nodos",
     "nodeLibraryTab": {
-      "sortOrder": "Orden de clasificación"
+      "groupBy": "Agrupar por",
+      "groupStrategies": {
+        "category": "Categoría",
+        "categoryDesc": "Agrupar por categoría de nodo",
+        "module": "Módulo",
+        "moduleDesc": "Agrupar por fuente del módulo",
+        "source": "Fuente",
+        "sourceDesc": "Agrupar por tipo de fuente (Core, Custom, API)"
+      },
+      "resetView": "Restablecer vista a la predeterminada",
+      "sortBy": {
+        "alphabetical": "Alfabético",
+        "alphabeticalDesc": "Ordenar alfabéticamente dentro de los grupos",
+        "original": "Original",
+        "originalDesc": "Mantener el orden original"
+      },
+      "sortMode": "Modo de ordenación"
     },
     "openWorkflow": "Abrir flujo de trabajo en el sistema de archivos local",
     "queue": "Cola",
diff --git a/src/locales/fr/main.json b/src/locales/fr/main.json
index ac1b02bfa..e8170b02a 100644
--- a/src/locales/fr/main.json
+++ b/src/locales/fr/main.json
@@ -1065,7 +1065,23 @@
     "newBlankWorkflow": "Créer un nouveau flux de travail vierge",
     "nodeLibrary": "Bibliothèque de nœuds",
     "nodeLibraryTab": {
-      "sortOrder": "Ordre de tri"
+      "groupBy": "Grouper par",
+      "groupStrategies": {
+        "category": "Catégorie",
+        "categoryDesc": "Grouper par catégorie de nœud",
+        "module": "Module",
+        "moduleDesc": "Grouper par source du module",
+        "source": "Source",
+        "sourceDesc": "Grouper par type de source (Core, Custom, API)"
+      },
+      "resetView": "Réinitialiser la vue par défaut",
+      "sortBy": {
+        "alphabetical": "Alphabétique",
+        "alphabeticalDesc": "Trier alphabétiquement dans les groupes",
+        "original": "Original",
+        "originalDesc": "Conserver l'ordre d'origine"
+      },
+      "sortMode": "Mode de tri"
     },
     "openWorkflow": "Ouvrir le flux de travail dans le système de fichiers local",
     "queue": "File d'attente",
diff --git a/src/locales/ja/main.json b/src/locales/ja/main.json
index 6dcf1d4a8..68f75efb0 100644
--- a/src/locales/ja/main.json
+++ b/src/locales/ja/main.json
@@ -1065,7 +1065,23 @@
     "newBlankWorkflow": "新しい空のワークフローを作成",
     "nodeLibrary": "ノードライブラリ",
     "nodeLibraryTab": {
-      "sortOrder": "並び順"
+      "groupBy": "グループ化",
+      "groupStrategies": {
+        "category": "カテゴリ",
+        "categoryDesc": "ノードカテゴリでグループ化",
+        "module": "モジュール",
+        "moduleDesc": "モジュールソースでグループ化",
+        "source": "ソース",
+        "sourceDesc": "ソースタイプ（Core、Custom、API）でグループ化"
+      },
+      "resetView": "ビューをデフォルトにリセット",
+      "sortBy": {
+        "alphabetical": "アルファベット順",
+        "alphabeticalDesc": "グループ内でアルファベット順に並び替え",
+        "original": "元の順序",
+        "originalDesc": "元の順序を維持"
+      },
+      "sortMode": "並び替えモード"
     },
     "openWorkflow": "ローカルでワークフローを開く",
     "queue": "キュー",
diff --git a/src/locales/ko/main.json b/src/locales/ko/main.json
index da595c7ca..1c5b0b1e8 100644
--- a/src/locales/ko/main.json
+++ b/src/locales/ko/main.json
@@ -1065,7 +1065,23 @@
     "newBlankWorkflow": "새 빈 워크플로 만들기",
     "nodeLibrary": "노드 라이브러리",
     "nodeLibraryTab": {
-      "sortOrder": "정렬 순서"
+      "groupBy": "그룹 기준",
+      "groupStrategies": {
+        "category": "카테고리",
+        "categoryDesc": "노드 카테고리별로 그룹화",
+        "module": "모듈",
+        "moduleDesc": "모듈 소스별로 그룹화",
+        "source": "소스",
+        "sourceDesc": "소스 유형(Core, Custom, API)별로 그룹화"
+      },
+      "resetView": "기본 보기로 재설정",
+      "sortBy": {
+        "alphabetical": "알파벳순",
+        "alphabeticalDesc": "그룹 내에서 알파벳순으로 정렬",
+        "original": "원본 순서",
+        "originalDesc": "원래 순서를 유지"
+      },
+      "sortMode": "정렬 방식"
     },
     "openWorkflow": "로컬 파일 시스템에서 워크플로 열기",
     "queue": "실행 대기열",
diff --git a/src/locales/ru/main.json b/src/locales/ru/main.json
index f5ee0e579..dd6090dc7 100644
--- a/src/locales/ru/main.json
+++ b/src/locales/ru/main.json
@@ -1065,7 +1065,23 @@
     "newBlankWorkflow": "Создайте новый пустой рабочий процесс",
     "nodeLibrary": "Библиотека нод",
     "nodeLibraryTab": {
-      "sortOrder": "Порядок сортировки"
+      "groupBy": "Группировать по",
+      "groupStrategies": {
+        "category": "Категория",
+        "categoryDesc": "Группировать по категории узла",
+        "module": "Модуль",
+        "moduleDesc": "Группировать по источнику модуля",
+        "source": "Источник",
+        "sourceDesc": "Группировать по типу источника (Core, Custom, API)"
+      },
+      "resetView": "Сбросить вид по умолчанию",
+      "sortBy": {
+        "alphabetical": "По алфавиту",
+        "alphabeticalDesc": "Сортировать по алфавиту внутри групп",
+        "original": "Оригинальный порядок",
+        "originalDesc": "Сохранять исходный порядок"
+      },
+      "sortMode": "Режим сортировки"
     },
     "openWorkflow": "Открыть рабочий процесс в локальной файловой системе",
     "queue": "Очередь",
diff --git a/src/locales/zh/main.json b/src/locales/zh/main.json
index 619e58118..74db4ab8a 100644
--- a/src/locales/zh/main.json
+++ b/src/locales/zh/main.json
@@ -1065,7 +1065,23 @@
     "newBlankWorkflow": "创建空白工作流",
     "nodeLibrary": "节点库",
     "nodeLibraryTab": {
-      "sortOrder": "排序顺序"
+      "groupBy": "分组方式",
+      "groupStrategies": {
+        "category": "类别",
+        "categoryDesc": "按节点类别分组",
+        "module": "模块",
+        "moduleDesc": "按模块来源分组",
+        "source": "来源",
+        "sourceDesc": "按来源类型分组（核心，自定义，API）"
+      },
+      "resetView": "重置视图为默认",
+      "sortBy": {
+        "alphabetical": "字母顺序",
+        "alphabeticalDesc": "在分组内按字母顺序排序",
+        "original": "原始顺序",
+        "originalDesc": "保持原始顺序"
+      },
+      "sortMode": "排序模式"
     },
     "openWorkflow": "在本地文件系统中打开工作流",
     "queue": "队列",
diff --git a/src/services/nodeOrganizationService.ts b/src/services/nodeOrganizationService.ts
new file mode 100644
index 000000000..fb2e4dff4
--- /dev/null
+++ b/src/services/nodeOrganizationService.ts
@@ -0,0 +1,159 @@
+import { ComfyNodeDefImpl, buildNodeDefTree } from '@/stores/nodeDefStore'
+import type {
+  NodeGroupingStrategy,
+  NodeOrganizationOptions,
+  NodeSortStrategy
+} from '@/types/nodeOrganizationTypes'
+import { NodeSourceType } from '@/types/nodeSource'
+import type { TreeNode } from '@/types/treeExplorerTypes'
+import { sortedTree } from '@/utils/treeUtil'
+
+const DEFAULT_ICON = 'pi pi-sort'
+
+export const DEFAULT_GROUPING_ID = 'category' as const
+export const DEFAULT_SORTING_ID = 'original' as const
+
+export class NodeOrganizationService {
+  private readonly groupingStrategies: NodeGroupingStrategy[] = [
+    {
+      id: 'category',
+      label: 'sideToolbar.nodeLibraryTab.groupStrategies.category',
+      icon: 'pi pi-folder',
+      description: 'sideToolbar.nodeLibraryTab.groupStrategies.categoryDesc',
+      getNodePath: (nodeDef: ComfyNodeDefImpl) => {
+        const category = nodeDef.category || ''
+        const categoryParts = category ? category.split('/') : []
+        return [...categoryParts, nodeDef.name]
+      }
+    },
+    {
+      id: 'module',
+      label: 'sideToolbar.nodeLibraryTab.groupStrategies.module',
+      icon: 'pi pi-box',
+      description: 'sideToolbar.nodeLibraryTab.groupStrategies.moduleDesc',
+      getNodePath: (nodeDef: ComfyNodeDefImpl) => {
+        const pythonModule = nodeDef.python_module || ''
+
+        if (!pythonModule) {
+          return ['unknown_module', nodeDef.name]
+        }
+
+        // Split the module path into components
+        const parts = pythonModule.split('.')
+
+        // Remove common prefixes and organize
+        if (parts[0] === 'nodes') {
+          // Core nodes - just use 'core'
+          return ['core', nodeDef.name]
+        } else if (parts[0] === 'custom_nodes') {
+          // Custom nodes - use the package name as the folder
+          if (parts.length > 1) {
+            // Return the custom node package name
+            return [parts[1], nodeDef.name]
+          }
+          return ['custom_nodes', nodeDef.name]
+        }
+
+        // For other modules, use the full path structure plus node name
+        return [...parts, nodeDef.name]
+      }
+    },
+    {
+      id: 'source',
+      label: 'sideToolbar.nodeLibraryTab.groupStrategies.source',
+      icon: 'pi pi-server',
+      description: 'sideToolbar.nodeLibraryTab.groupStrategies.sourceDesc',
+      getNodePath: (nodeDef: ComfyNodeDefImpl) => {
+        if (nodeDef.api_node) {
+          return ['API nodes', nodeDef.name]
+        } else if (nodeDef.nodeSource.type === NodeSourceType.Core) {
+          return ['Core', nodeDef.name]
+        } else if (nodeDef.nodeSource.type === NodeSourceType.CustomNodes) {
+          return ['Custom nodes', nodeDef.name]
+        } else {
+          return ['Unknown', nodeDef.name]
+        }
+      }
+    }
+  ]
+
+  private readonly sortingStrategies: NodeSortStrategy[] = [
+    {
+      id: 'original',
+      label: 'sideToolbar.nodeLibraryTab.sortBy.original',
+      icon: 'pi pi-sort-alt',
+      description: 'sideToolbar.nodeLibraryTab.sortBy.originalDesc',
+      compare: () => 0
+    },
+    {
+      id: 'alphabetical',
+      label: 'sideToolbar.nodeLibraryTab.sortBy.alphabetical',
+      icon: 'pi pi-sort-alpha-down',
+      description: 'sideToolbar.nodeLibraryTab.sortBy.alphabeticalDesc',
+      compare: (a: ComfyNodeDefImpl, b: ComfyNodeDefImpl) =>
+        (a.display_name ?? '').localeCompare(b.display_name ?? '')
+    }
+  ]
+
+  getGroupingStrategies(): NodeGroupingStrategy[] {
+    return [...this.groupingStrategies]
+  }
+
+  getGroupingStrategy(id: string): NodeGroupingStrategy | undefined {
+    return this.groupingStrategies.find((strategy) => strategy.id === id)
+  }
+
+  getSortingStrategies(): NodeSortStrategy[] {
+    return [...this.sortingStrategies]
+  }
+
+  getSortingStrategy(id: string): NodeSortStrategy | undefined {
+    return this.sortingStrategies.find((strategy) => strategy.id === id)
+  }
+
+  organizeNodes(
+    nodes: ComfyNodeDefImpl[],
+    options: NodeOrganizationOptions = {}
+  ): TreeNode {
+    const { groupBy = DEFAULT_GROUPING_ID, sortBy = DEFAULT_SORTING_ID } =
+      options
+
+    const groupingStrategy = this.getGroupingStrategy(groupBy)
+    const sortingStrategy = this.getSortingStrategy(sortBy)
+
+    if (!groupingStrategy) {
+      throw new Error(`Unknown grouping strategy: ${groupBy}`)
+    }
+
+    if (!sortingStrategy) {
+      throw new Error(`Unknown sorting strategy: ${sortBy}`)
+    }
+
+    const sortedNodes =
+      sortingStrategy.id !== 'original'
+        ? [...nodes].sort(sortingStrategy.compare)
+        : nodes
+
+    const tree = buildNodeDefTree(sortedNodes, {
+      pathExtractor: groupingStrategy.getNodePath
+    })
+
+    if (sortBy === 'alphabetical') {
+      return sortedTree(tree, { groupLeaf: true })
+    }
+
+    return tree
+  }
+
+  getGroupingIcon(groupingId: string): string {
+    const strategy = this.getGroupingStrategy(groupingId)
+    return strategy?.icon || DEFAULT_ICON
+  }
+
+  getSortingIcon(sortingId: string): string {
+    const strategy = this.getSortingStrategy(sortingId)
+    return strategy?.icon || DEFAULT_ICON
+  }
+}
+
+export const nodeOrganizationService = new NodeOrganizationService()
diff --git a/src/stores/nodeDefStore.ts b/src/stores/nodeDefStore.ts
index da2e93e8a..4fc95dced 100644
--- a/src/stores/nodeDefStore.ts
+++ b/src/stores/nodeDefStore.ts
@@ -216,10 +216,22 @@ export const SYSTEM_NODE_DEFS: Record<string, ComfyNodeDefV1> = {
   }
 }
 
-export function buildNodeDefTree(nodeDefs: ComfyNodeDefImpl[]): TreeNode {
-  return buildTree(nodeDefs, (nodeDef: ComfyNodeDefImpl) =>
+export interface BuildNodeDefTreeOptions {
+  /**
+   * Custom function to extract the tree path from a node definition.
+   * If not provided, uses the default path based on nodeDef.nodePath.
+   */
+  pathExtractor?: (nodeDef: ComfyNodeDefImpl) => string[]
+}
+
+export function buildNodeDefTree(
+  nodeDefs: ComfyNodeDefImpl[],
+  options: BuildNodeDefTreeOptions = {}
+): TreeNode {
+  const { pathExtractor } = options
+  const defaultPathExtractor = (nodeDef: ComfyNodeDefImpl) =>
     nodeDef.nodePath.split('/')
-  )
+  return buildTree(nodeDefs, pathExtractor || defaultPathExtractor)
 }
 
 export function createDummyFolderNodeDef(folderPath: string): ComfyNodeDefImpl {
diff --git a/src/types/nodeOrganizationTypes.ts b/src/types/nodeOrganizationTypes.ts
new file mode 100644
index 000000000..c6abb0605
--- /dev/null
+++ b/src/types/nodeOrganizationTypes.ts
@@ -0,0 +1,44 @@
+import type { ComfyNodeDefImpl } from '@/stores/nodeDefStore'
+
+export type GroupingStrategyId = 'category' | 'module' | 'source'
+export type SortingStrategyId = 'original' | 'alphabetical'
+
+/**
+ * Strategy for grouping nodes into tree structure
+ */
+export interface NodeGroupingStrategy {
+  /** Unique identifier for the grouping strategy */
+  id: string
+  /** Display name for UI (i18n key) */
+  label: string
+  /** Icon class for the grouping option */
+  icon: string
+  /** Description for tooltips (i18n key) */
+  description?: string
+  /** Function to extract the tree path from a node definition */
+  getNodePath: (nodeDef: ComfyNodeDefImpl) => string[]
+}
+
+/**
+ * Strategy for sorting nodes within groups
+ */
+export interface NodeSortStrategy {
+  /** Unique identifier for the sort strategy */
+  id: string
+  /** Display name for UI (i18n key) */
+  label: string
+  /** Icon class for the sort option */
+  icon: string
+  /** Description for tooltips (i18n key) */
+  description?: string
+  /** Compare function for sorting nodes within the same group */
+  compare: (a: ComfyNodeDefImpl, b: ComfyNodeDefImpl) => number
+}
+
+/**
+ * Options for organizing nodes
+ */
+export interface NodeOrganizationOptions {
+  groupBy?: string
+  sortBy?: string
+}
diff --git a/tests-ui/tests/services/nodeOrganizationService.test.ts b/tests-ui/tests/services/nodeOrganizationService.test.ts
new file mode 100644
index 000000000..dfc389b14
--- /dev/null
+++ b/tests-ui/tests/services/nodeOrganizationService.test.ts
@@ -0,0 +1,330 @@
+import { describe, expect, it } from 'vitest'
+
+import { nodeOrganizationService } from '@/services/nodeOrganizationService'
+import { ComfyNodeDefImpl } from '@/stores/nodeDefStore'
+import { NodeSourceType } from '@/types/nodeSource'
+
+describe('nodeOrganizationService', () => {
+  const createMockNodeDef = (overrides: any = {}) => {
+    const mockNodeDef = {
+      name: 'TestNode',
+      display_name: 'Test Node',
+      category: 'test/subcategory',
+      python_module: 'custom_nodes.MyPackage.nodes',
+      api_node: false,
+      nodeSource: {
+        type: NodeSourceType.CustomNodes,
+        className: 'comfy-custom',
+        displayText: 'Custom',
+        badgeText: 'C'
+      },
+      ...overrides
+    }
+
+    Object.setPrototypeOf(mockNodeDef, ComfyNodeDefImpl.prototype)
+    return mockNodeDef as ComfyNodeDefImpl
+  }
+
+  describe('getGroupingStrategies', () => {
+    it('should return all grouping strategies', () => {
+      const strategies = nodeOrganizationService.getGroupingStrategies()
+      expect(strategies).toHaveLength(3)
+      expect(strategies.map((s) => s.id)).toEqual([
+        'category',
+        'module',
+        'source'
+      ])
+    })
+
+    it('should return immutable copy', () => {
+      const strategies1 = nodeOrganizationService.getGroupingStrategies()
+      const strategies2 = nodeOrganizationService.getGroupingStrategies()
+      expect(strategies1).not.toBe(strategies2)
+      expect(strategies1).toEqual(strategies2)
+    })
+  })
+
+  describe('getGroupingStrategy', () => {
+    it('should return strategy by id', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('category')
+      expect(strategy).toBeDefined()
+      expect(strategy?.id).toBe('category')
+    })
+
+    it('should return undefined for unknown id', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('unknown')
+      expect(strategy).toBeUndefined()
+    })
+  })
+
+  describe('getSortingStrategies', () => {
+    it('should return all sorting strategies', () => {
+      const strategies = nodeOrganizationService.getSortingStrategies()
+      expect(strategies).toHaveLength(2)
+      expect(strategies.map((s) => s.id)).toEqual(['original', 'alphabetical'])
+    })
+  })
+
+  describe('getSortingStrategy', () => {
+    it('should return strategy by id', () => {
+      const strategy =
+        nodeOrganizationService.getSortingStrategy('alphabetical')
+      expect(strategy).toBeDefined()
+      expect(strategy?.id).toBe('alphabetical')
+    })
+
+    it('should return undefined for unknown id', () => {
+      const strategy = nodeOrganizationService.getSortingStrategy('unknown')
+      expect(strategy).toBeUndefined()
+    })
+  })
+
+  describe('organizeNodes', () => {
+    const mockNodes = [
+      createMockNodeDef({ name: 'NodeA', display_name: 'Zebra Node' }),
+      createMockNodeDef({ name: 'NodeB', display_name: 'Apple Node' })
+    ]
+
+    it('should organize nodes with default options', () => {
+      const tree = nodeOrganizationService.organizeNodes(mockNodes)
+      expect(tree).toBeDefined()
+      expect(tree.children).toBeDefined()
+    })
+
+    it('should organize nodes with custom grouping', () => {
+      const tree = nodeOrganizationService.organizeNodes(mockNodes, {
+        groupBy: 'module'
+      })
+      expect(tree).toBeDefined()
+      expect(tree.children).toBeDefined()
+    })
+
+    it('should organize nodes with custom sorting', () => {
+      const tree = nodeOrganizationService.organizeNodes(mockNodes, {
+        sortBy: 'alphabetical'
+      })
+      expect(tree).toBeDefined()
+      expect(tree.children).toBeDefined()
+    })
+
+    it('should throw error for unknown grouping strategy', () => {
+      expect(() => {
+        nodeOrganizationService.organizeNodes(mockNodes, {
+          groupBy: 'unknown'
+        })
+      }).toThrow('Unknown grouping strategy: unknown')
+    })
+
+    it('should throw error for unknown sorting strategy', () => {
+      expect(() => {
+        nodeOrganizationService.organizeNodes(mockNodes, {
+          sortBy: 'unknown'
+        })
+      }).toThrow('Unknown sorting strategy: unknown')
+    })
+  })
+
+  describe('getGroupingIcon', () => {
+    it('should return strategy icon', () => {
+      const icon = nodeOrganizationService.getGroupingIcon('category')
+      expect(icon).toBe('pi pi-folder')
+    })
+
+    it('should return fallback icon for unknown strategy', () => {
+      const icon = nodeOrganizationService.getGroupingIcon('unknown')
+      expect(icon).toBe('pi pi-sort')
+    })
+  })
+
+  describe('getSortingIcon', () => {
+    it('should return strategy icon', () => {
+      const icon = nodeOrganizationService.getSortingIcon('alphabetical')
+      expect(icon).toBe('pi pi-sort-alpha-down')
+    })
+
+    it('should return fallback icon for unknown strategy', () => {
+      const icon = nodeOrganizationService.getSortingIcon('unknown')
+      expect(icon).toBe('pi pi-sort')
+    })
+  })
+
+  describe('grouping path extraction', () => {
+    const mockNodeDef = createMockNodeDef()
+
+    it('category grouping should use category path', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('category')
+      const path = strategy?.getNodePath(mockNodeDef)
+      expect(path).toEqual(['test', 'subcategory', 'TestNode'])
+    })
+
+    it('module grouping should extract module path', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('module')
+      const path = strategy?.getNodePath(mockNodeDef)
+      expect(path).toEqual(['MyPackage', 'TestNode'])
+    })
+
+    it('source grouping should categorize by source type', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('source')
+      const path = strategy?.getNodePath(mockNodeDef)
+      expect(path).toEqual(['Custom nodes', 'TestNode'])
+    })
+  })
+
+  describe('edge cases', () => {
+    describe('module grouping edge cases', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('module')
+
+      it('should handle empty python_module', () => {
+        const nodeDef = createMockNodeDef({ python_module: '' })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['unknown_module', 'TestNode'])
+      })
+
+      it('should handle undefined python_module', () => {
+        const nodeDef = createMockNodeDef({ python_module: undefined })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['unknown_module', 'TestNode'])
+      })
+
+      it('should handle modules with spaces in the name', () => {
+        const nodeDef = createMockNodeDef({
+          python_module: 'custom_nodes.My Package With Spaces.nodes'
+        })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['My Package With Spaces', 'TestNode'])
+      })
+
+      it('should handle modules with special characters', () => {
+        const nodeDef = createMockNodeDef({
+          python_module: 'custom_nodes.my-package_v2.0.nodes'
+        })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['my-package_v2', 'TestNode'])
+      })
+
+      it('should handle deeply nested modules', () => {
+        const nodeDef = createMockNodeDef({
+          python_module: 'custom_nodes.package.subpackage.module.nodes'
+        })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['package', 'TestNode'])
+      })
+
+      it('should handle core nodes module path', () => {
+        const nodeDef = createMockNodeDef({ python_module: 'nodes' })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['core', 'TestNode'])
+      })
+
+      it('should handle non-standard module paths', () => {
+        const nodeDef = createMockNodeDef({
+          python_module: 'some.other.module.path'
+        })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['some', 'other', 'module', 'path', 'TestNode'])
+      })
+    })
+
+    describe('category grouping edge cases', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('category')
+
+      it('should handle empty category', () => {
+        const nodeDef = createMockNodeDef({ category: '' })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['TestNode'])
+      })
+
+      it('should handle undefined category', () => {
+        const nodeDef = createMockNodeDef({ category: undefined })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['TestNode'])
+      })
+
+      it('should handle category with trailing slash', () => {
+        const nodeDef = createMockNodeDef({ category: 'test/subcategory/' })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['test', 'subcategory', '', 'TestNode'])
+      })
+
+      it('should handle category with multiple consecutive slashes', () => {
+        const nodeDef = createMockNodeDef({ category: 'test//subcategory' })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['test', '', 'subcategory', 'TestNode'])
+      })
+    })
+
+    describe('source grouping edge cases', () => {
+      const strategy = nodeOrganizationService.getGroupingStrategy('source')
+
+      it('should handle API nodes', () => {
+        const nodeDef = createMockNodeDef({
+          api_node: true,
+          nodeSource: {
+            type: NodeSourceType.Core,
+            className: 'comfy-core',
+            displayText: 'Core',
+            badgeText: 'C'
+          }
+        })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['API nodes', 'TestNode'])
+      })
+
+      it('should handle unknown source type', () => {
+        const nodeDef = createMockNodeDef({
+          nodeSource: {
+            type: 'unknown' as any,
+            className: 'unknown',
+            displayText: 'Unknown',
+            badgeText: '?'
+          }
+        })
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['Unknown', 'TestNode'])
+      })
+    })
+
+    describe('node name edge cases', () => {
+      it('should handle nodes with special characters in name', () => {
+        const nodeDef = createMockNodeDef({
+          name: 'Test/Node:With*Special<Chars>'
+        })
+        const strategy = nodeOrganizationService.getGroupingStrategy('category')
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual([
+          'test',
+          'subcategory',
+          'Test/Node:With*Special<Chars>'
+        ])
+      })
+
+      it('should handle nodes with very long names', () => {
+        const longName = 'A'.repeat(100)
+        const nodeDef = createMockNodeDef({ name: longName })
+        const strategy = nodeOrganizationService.getGroupingStrategy('category')
+        const path = strategy?.getNodePath(nodeDef)
+        expect(path).toEqual(['test', 'subcategory', longName])
+      })
+    })
+  })
+
+  describe('sorting comparison', () => {
+    it('original sort should keep order', () => {
+      const strategy = nodeOrganizationService.getSortingStrategy('original')
+      const nodeA = createMockNodeDef({ display_name: 'Zebra' })
+      const nodeB = createMockNodeDef({ display_name: 'Apple' })
+
+      expect(strategy?.compare(nodeA, nodeB)).toBe(0)
+    })
+
+    it('alphabetical sort should compare display names', () => {
+      const strategy =
+        nodeOrganizationService.getSortingStrategy('alphabetical')
+      const nodeA = createMockNodeDef({ display_name: 'Zebra' })
+      const nodeB = createMockNodeDef({ display_name: 'Apple' })
+
+      expect(strategy?.compare(nodeA, nodeB)).toBeGreaterThan(0)
+      expect(strategy?.compare(nodeB, nodeA)).toBeLessThan(0)
+    })
+  })
+})