fix(tailwindcss-patch): preserve raw runtime class tokens

Author: sonofmagic

.changeset/late-ducks-juggle.md

@@ -0,0 +1,5 @@
+---
+'tailwindcss-patch': patch
+---
+
+Preserve original runtime candidate tokens when collecting the class set for Tailwind CSS v2/v3 projects, so shorthand and full hex arbitrary color classes remain distinct and only match when the exact source token is present.

packages/tailwindcss-patch/src/runtime/class-collector.ts

@@ -6,6 +6,15 @@ import path from 'pathe'
 import { extractValidCandidates } from '../extraction/candidate-extractor'
 import { isObject } from '../utils'
 
+function collectRuntimeCandidateKeys(context: TailwindcssRuntimeContext) {
+  const candidateRuleCache = context.candidateRuleCache
+  if (candidateRuleCache instanceof Map && candidateRuleCache.size > 0) {
+    return candidateRuleCache.keys()
+  }
+
+  return context.classCache.keys()
+}
+
 export function collectClassesFromContexts(
   contexts: TailwindcssRuntimeContext[],
   filter: (className: string) => boolean,
@@ -16,7 +25,7 @@ export function collectClassesFromContexts(
       continue
     }
 
-    for (const key of context.classCache.keys()) {
+    for (const key of collectRuntimeCandidateKeys(context)) {
       const className = key.toString()
       if (filter(className)) {
         set.add(className)

packages/tailwindcss-patch/test/api.tailwindcss-patcher.test.ts

@@ -320,6 +320,81 @@ describe('TailwindcssPatcher', () => {
     expect(firstEntry?.values).toEqual(expect.arrayContaining(['foo', 'bar']))
   })
 
+  it.each([
+    {
+      name: 'only shorthand black token',
+      rawCandidates: ['bg-[#000]'],
+      normalizedClasses: ['bg-[#000000]'],
+      expectedPresent: ['bg-[#000]'],
+      expectedAbsent: ['bg-[#000000]'],
+    },
+    {
+      name: 'only full black token',
+      rawCandidates: ['bg-[#000000]'],
+      normalizedClasses: ['bg-[#000000]'],
+      expectedPresent: ['bg-[#000000]'],
+      expectedAbsent: ['bg-[#000]'],
+    },
+    {
+      name: 'both black tokens',
+      rawCandidates: ['bg-[#000]', 'bg-[#000000]'],
+      normalizedClasses: ['bg-[#000000]'],
+      expectedPresent: ['bg-[#000]', 'bg-[#000000]'],
+      expectedAbsent: [],
+    },
+    {
+      name: 'red shorthand and full tokens',
+      rawCandidates: ['bg-[#f00]', 'bg-[#ff0000]'],
+      normalizedClasses: ['bg-[#ff0000]'],
+      expectedPresent: ['bg-[#f00]', 'bg-[#ff0000]'],
+      expectedAbsent: [],
+    },
+    {
+      name: 'green shorthand and full tokens',
+      rawCandidates: ['bg-[#0f0]', 'bg-[#00ff00]'],
+      normalizedClasses: ['bg-[#00ff00]'],
+      expectedPresent: ['bg-[#0f0]', 'bg-[#00ff00]'],
+      expectedAbsent: [],
+    },
+  ])('prefers raw runtime candidates for precise class set matching: $name', ({ rawCandidates, normalizedClasses, expectedPresent, expectedAbsent }) => {
+    const patcher = new TailwindcssPatcher({
+      apply: {
+        overwrite: false,
+      },
+      cache: false,
+      tailwindcss: {
+        version: 3,
+      },
+    })
+
+    const candidateRuleCache = new Map<string, Set<any>>()
+    for (const candidate of rawCandidates) {
+      candidateRuleCache.set(candidate, new Set())
+    }
+
+    const classCache = new Map<string, any>()
+    for (const cls of normalizedClasses) {
+      classCache.set(cls, [])
+    }
+
+    vi.spyOn(patcher, 'getContexts').mockReturnValue([
+      {
+        candidateRuleCache,
+        classCache,
+      } as any,
+    ])
+
+    const result = patcher.getClassSetSync()
+
+    expect(result).toBeDefined()
+    for (const token of expectedPresent) {
+      expect(result?.has(token)).toBe(true)
+    }
+    for (const token of expectedAbsent) {
+      expect(result?.has(token)).toBe(false)
+    }
+  })
+
   it('treats legacy cache schema as miss to avoid cross-context pollution', () => {
     const cacheFile = path.join(tempDir, 'cache.json')
     fs.writeJSONSync(cacheFile, ['cached-class'])

packages/tailwindcss-patch/test/runtime.class-collector.test.ts

@@ -15,6 +15,23 @@ function createContext(classes: string[]) {
   } as any
 }
 
+function createContextWithCandidateRuleCache(rawCandidates: string[], normalizedClasses: string[]) {
+  const candidateRuleCache = new Map()
+  for (const candidate of rawCandidates) {
+    candidateRuleCache.set(candidate, new Set())
+  }
+
+  const classCache = new Map()
+  for (const cls of normalizedClasses) {
+    classCache.set(cls, [])
+  }
+
+  return {
+    candidateRuleCache,
+    classCache,
+  } as any
+}
+
 describe('collectClassesFromContexts', () => {
   it('aggregates class names respecting the filter', () => {
     const contexts = [createContext(['text-lg', '*', 'font-bold'])]
@@ -23,6 +40,55 @@ describe('collectClassesFromContexts', () => {
     expect(result.has('text-lg')).toBe(true)
     expect(result.has('*')).toBe(false)
   })
+
+  it.each([
+    {
+      name: 'keeps shorthand hex tokens when shorthand is the only source token',
+      rawCandidates: ['bg-[#000]'],
+      normalizedClasses: ['bg-[#000000]'],
+      expectedPresent: ['bg-[#000]'],
+      expectedAbsent: ['bg-[#000000]'],
+    },
+    {
+      name: 'keeps full hex tokens when full hex is the only source token',
+      rawCandidates: ['bg-[#000000]'],
+      normalizedClasses: ['bg-[#000000]'],
+      expectedPresent: ['bg-[#000000]'],
+      expectedAbsent: ['bg-[#000]'],
+    },
+    {
+      name: 'keeps shorthand and full hex tokens distinct when both appear',
+      rawCandidates: ['bg-[#000]', 'bg-[#000000]'],
+      normalizedClasses: ['bg-[#000000]'],
+      expectedPresent: ['bg-[#000]', 'bg-[#000000]'],
+      expectedAbsent: [],
+    },
+    {
+      name: 'does not merge red shorthand and full hex tokens',
+      rawCandidates: ['bg-[#f00]', 'bg-[#ff0000]'],
+      normalizedClasses: ['bg-[#ff0000]'],
+      expectedPresent: ['bg-[#f00]', 'bg-[#ff0000]'],
+      expectedAbsent: [],
+    },
+    {
+      name: 'does not merge green shorthand and full hex tokens',
+      rawCandidates: ['bg-[#0f0]', 'bg-[#00ff00]'],
+      normalizedClasses: ['bg-[#00ff00]'],
+      expectedPresent: ['bg-[#0f0]', 'bg-[#00ff00]'],
+      expectedAbsent: [],
+    },
+  ])('$name', ({ rawCandidates, normalizedClasses, expectedPresent, expectedAbsent }) => {
+    const contexts = [createContextWithCandidateRuleCache(rawCandidates, normalizedClasses)]
+    const result = collectClassesFromContexts(contexts as any, () => true)
+
+    for (const token of expectedPresent) {
+      expect(result.has(token)).toBe(true)
+    }
+
+    for (const token of expectedAbsent) {
+      expect(result.has(token)).toBe(false)
+    }
+  })
 })
 
 describe('collectClassesFromTailwindV4', () => {