fix: normalize essentials_category to canonical form for case-insensitive backend matching

Backend sends title-cased categories (e.g. 'Image Generation') while
frontend uses lowercase (e.g. 'image generation'). Add canonical lookup
map to resolve backend values to the exact form in ESSENTIALS_CATEGORIES,
preserving special cases like '3D'.

Addresses review feedback from benceruleanlu.

Amp-Thread-ID: https://ampcode.com/threads/T-019c93b8-dae2-77ba-92c5-c7a71a424a3f

Author: christian-byrne

src/constants/essentialsNodes.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import {
   ESSENTIALS_CATEGORIES,
+  ESSENTIALS_CATEGORY_CANONICAL,
   ESSENTIALS_CATEGORY_MAP,
   ESSENTIALS_NODES,
   TOOLKIT_BLUEPRINT_MODULES,
@@ -50,4 +51,12 @@ describe('essentialsNodes', () => {
   it('TOOLKIT_BLUEPRINT_MODULES contains comfy_essentials', () => {
     expect(TOOLKIT_BLUEPRINT_MODULES.has('comfy_essentials')).toBe(true)
   })
+
+  it('ESSENTIALS_CATEGORY_CANONICAL maps every category case-insensitively', () => {
+    for (const category of ESSENTIALS_CATEGORIES) {
+      expect(ESSENTIALS_CATEGORY_CANONICAL.get(category.toLowerCase())).toBe(
+        category
+      )
+    }
+  })
 })

src/constants/essentialsNodes.ts

@@ -79,12 +79,22 @@ export const ESSENTIALS_NODES: Record<EssentialsCategory, readonly string[]> = {
  * Flat map: node name → category (derived from ESSENTIALS_NODES).
  * Used as mock/fallback when backend doesn't provide essentials_category.
  */
-export const ESSENTIALS_CATEGORY_MAP: Record<string, string> =
+export const ESSENTIALS_CATEGORY_MAP: Record<string, EssentialsCategory> =
   Object.fromEntries(
     Object.entries(ESSENTIALS_NODES).flatMap(([category, nodes]) =>
       nodes.map((node) => [node, category])
     )
-  )
+  ) as Record<string, EssentialsCategory>
+
+/**
+ * Case-insensitive lookup: lowercase category → canonical category.
+ * Used to normalize backend categories (which may be title-cased) to the
+ * canonical form used in ESSENTIALS_CATEGORIES.
+ */
+export const ESSENTIALS_CATEGORY_CANONICAL: ReadonlyMap<
+  string,
+  EssentialsCategory
+> = new Map(ESSENTIALS_CATEGORIES.map((c) => [c.toLowerCase(), c]))
 
 /**
  * "Novel" toolkit nodes for telemetry — basics excluded.

src/stores/subgraphStore.test.ts

@@ -516,6 +516,35 @@ describe('useSubgraphStore', () => {
   })
 
   describe('essentials_category passthrough', () => {
+    it('should prefer GlobalSubgraphData essentials_category over definition fallback', async () => {
+      const graphWithEssentials = {
+        ...mockGraph,
+        definitions: {
+          subgraphs: [
+            {
+              ...mockGraph.definitions?.subgraphs?.[0],
+              essentials_category: 'Image Tools'
+            }
+          ]
+        }
+      }
+      await mockFetch(
+        {},
+        {
+          bp_precedence: {
+            name: 'Precedence Blueprint',
+            info: { node_pack: 'test_pack' },
+            data: JSON.stringify(graphWithEssentials),
+            essentials_category: 'Video Generation'
+          }
+        }
+      )
+      const nodeDef = useNodeDefStore().nodeDefs.find(
+        (d) => d.name === 'SubgraphBlueprint.bp_precedence'
+      )
+      expect(nodeDef?.essentials_category).toBe('video generation')
+    })
+
     it('should pass essentials_category from GlobalSubgraphData to node def', async () => {
       await mockFetch(
         {},
@@ -532,7 +561,7 @@ describe('useSubgraphStore', () => {
         (d) => d.name === 'SubgraphBlueprint.bp_essentials'
       )
       expect(nodeDef).toBeDefined()
-      expect(nodeDef?.essentials_category).toBe('Image Generation')
+      expect(nodeDef?.essentials_category).toBe('image generation')
     })
 
     it('should extract essentials_category from subgraph definition as fallback', async () => {
@@ -561,7 +590,26 @@ describe('useSubgraphStore', () => {
         (d) => d.name === 'SubgraphBlueprint.bp_fallback'
       )
       expect(nodeDef).toBeDefined()
-      expect(nodeDef?.essentials_category).toBe('Image Tools')
+      expect(nodeDef?.essentials_category).toBe('image tools')
+    })
+
+    it('should normalize title-cased essentials_category to canonical form', async () => {
+      await mockFetch(
+        {},
+        {
+          bp_3d: {
+            name: 'Test 3D Blueprint',
+            info: { node_pack: 'test_pack', category: 'Test Category' },
+            data: JSON.stringify(mockGraph),
+            essentials_category: '3d'
+          }
+        }
+      )
+      const nodeDef = useNodeDefStore().nodeDefs.find(
+        (d) => d.name === 'SubgraphBlueprint.bp_3d'
+      )
+      expect(nodeDef).toBeDefined()
+      expect(nodeDef?.essentials_category).toBe('3D')
     })
   })
 

src/types/nodeSource.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest'
 
-import { NodeSourceType, getNodeSource } from '@/types/nodeSource'
+import {
+  NodeSourceType,
+  getEssentialsCategory,
+  getNodeSource
+} from '@/types/nodeSource'
 
 describe('getNodeSource', () => {
   it('should return UNKNOWN_NODE_SOURCE when python_module is undefined', () => {
@@ -105,6 +109,36 @@ describe('getNodeSource', () => {
       const result = getNodeSource('nodes.some_module', undefined, 'LoadImage')
       expect(result.type).toBe(NodeSourceType.Essentials)
     })
+
+    it('should normalize title-cased backend categories to canonical form', () => {
+      const result = getNodeSource(
+        'nodes.some_module',
+        'Image Generation',
+        'SomeNode'
+      )
+      expect(result.type).toBe(NodeSourceType.Essentials)
+      expect(getEssentialsCategory('SomeNode', 'Image Generation')).toBe(
+        'image generation'
+      )
+    })
+  })
+
+  describe('getEssentialsCategory', () => {
+    it('should normalize title-cased essentials_category to canonical form', () => {
+      expect(getEssentialsCategory('SomeNode', 'Image Generation')).toBe(
+        'image generation'
+      )
+      expect(getEssentialsCategory('SomeNode', '3d')).toBe('3D')
+      expect(getEssentialsCategory('SomeNode', '3D')).toBe('3D')
+    })
+
+    it('should fall back to ESSENTIALS_CATEGORY_MAP when no category provided', () => {
+      expect(getEssentialsCategory('LoadImage')).toBe('basics')
+    })
+
+    it('should return undefined for unknown node without category', () => {
+      expect(getEssentialsCategory('UnknownNode')).toBeUndefined()
+    })
   })
 
   describe('blueprint nodes', () => {

src/types/nodeSource.ts

@@ -1,4 +1,7 @@
-import { ESSENTIALS_CATEGORY_MAP } from '@/constants/essentialsNodes'
+import {
+  ESSENTIALS_CATEGORY_CANONICAL,
+  ESSENTIALS_CATEGORY_MAP
+} from '@/constants/essentialsNodes'
 
 export enum NodeSourceType {
   Core = 'core',
@@ -35,9 +38,12 @@ export function getEssentialsCategory(
   name?: string,
   essentials_category?: string
 ): string | undefined {
-  return (
-    essentials_category ?? (name ? ESSENTIALS_CATEGORY_MAP[name] : undefined)
-  )
+  const normalizedCategory = essentials_category?.trim().toLowerCase()
+  const canonical = normalizedCategory
+    ? (ESSENTIALS_CATEGORY_CANONICAL.get(normalizedCategory) ??
+      normalizedCategory)
+    : undefined
+  return canonical ?? (name ? ESSENTIALS_CATEGORY_MAP[name] : undefined)
 }
 
 export const getNodeSource = (