purgetss 7.7.0 → 7.9.0

package/src/core/images/gen-scales.js

@@ -73,6 +73,26 @@ export const IPHONE_SCALES = Object.freeze([
   { suffix: '@3x', factor: 3 / 4 }
 ])
 
+// Resolve target dimensions for a single scale.
+// `factor * 4` recovers the integer multiplier (1, 1.5, 2, 3, 4 for Android;
+// 1, 2, 3 for iPhone) only because every entry in *_SCALES is normalized to
+// n/4 with the largest scale (xxxhdpi/@4x) at 4/4. If a future density is
+// added beyond xxxhdpi, this conversion factor needs to be revisited.
+function computeScaleTarget(srcMeta, factor, baseWidth) {
+  if (baseWidth == null) {
+    return {
+      targetWidth: Math.max(1, Math.round(srcMeta.width * factor)),
+      targetHeight: Math.max(1, Math.round(srcMeta.height * factor))
+    }
+  }
+  const multiplier = factor * 4
+  const aspect = srcMeta.width > 0 ? (srcMeta.height / srcMeta.width) : 1
+  return {
+    targetWidth: Math.max(1, Math.round(baseWidth * multiplier)),
+    targetHeight: Math.max(1, Math.round(baseWidth * multiplier * aspect))
+  }
+}
+
 /**
  * Scale a source image into all Android density variants.
  *
@@ -85,13 +105,12 @@ export const IPHONE_SCALES = Object.freeze([
  * @returns {Promise<string[]>} Paths written
  */
 export async function genAndroidScales(sourceFile, relPath, androidBaseDir, opts = {}) {
-  const { format = null, quality = 85 } = opts
+  const { format = null, quality = 85, baseWidth = null } = opts
   const src = await readSource(sourceFile)
   const written = []
 
   for (const { name, factor } of ANDROID_SCALES) {
-    const targetWidth = Math.max(1, Math.round(src.meta.width * factor))
-    const targetHeight = Math.max(1, Math.round(src.meta.height * factor))
+    const { targetWidth, targetHeight } = computeScaleTarget(src.meta, factor, baseWidth)
 
     const outDir = path.join(androidBaseDir, name, path.dirname(relPath))
     fs.mkdirSync(outDir, { recursive: true })
@@ -113,7 +132,7 @@ export async function genAndroidScales(sourceFile, relPath, androidBaseDir, opts
  * @returns {Promise<string[]>} Paths written
  */
 export async function genIphoneScales(sourceFile, relPath, iphoneBaseDir, opts = {}) {
-  const { format = null, quality = 85 } = opts
+  const { format = null, quality = 85, baseWidth = null } = opts
   const src = await readSource(sourceFile)
   const written = []
 
@@ -122,8 +141,7 @@ export async function genIphoneScales(sourceFile, relPath, iphoneBaseDir, opts =
   fs.mkdirSync(outDir, { recursive: true })
 
   for (const { suffix, factor } of IPHONE_SCALES) {
-    const targetWidth = Math.max(1, Math.round(src.meta.width * factor))
-    const targetHeight = Math.max(1, Math.round(src.meta.height * factor))
+    const { targetWidth, targetHeight } = computeScaleTarget(src.meta, factor, baseWidth)
 
     // SVG sources can't be written as SVG by Sharp — fall back to PNG if the
     // user didn't specify an explicit output format.

package/src/core/images/index.js

@@ -35,6 +35,7 @@ export async function runImages(opts) {
     iphoneOnly = false,
     format = null,
     quality = 85,
+    baseWidth = null,
     dryRun = false,
     yes = false,
     confirmOverwrites = true
@@ -49,6 +50,11 @@ export async function runImages(opts) {
 
   const files = collectImageFiles(source)
 
+  if (baseWidth == null && files.some(f => path.extname(f).toLowerCase() === '.svg')) {
+    logger.warning('⚠  SVG source detected without --width. Output sizes will be derived from each SVG\'s viewBox (treated as a 4× master).')
+    logger.warning('   For SVGs from vector editors with disproportionate viewBoxes, pass --width <n> (e.g. --width 256) to pin the @1x/mdpi width.')
+  }
+
   console.log()
   mainLogger.info('Generating multi-density image variants...')
   console.log()
@@ -60,6 +66,7 @@ export async function runImages(opts) {
   if (!androidOnly) platforms.push('iPhone (@1x, @2x, @3x)')
   logger.property('Platforms:  ', platforms.join(' + '))
   if (format) logger.property('Format:     ', `convert all to ${format}`)
+  if (baseWidth != null) logger.property('Width:      ', `${baseWidth} px @1x/mdpi`)
   if (dryRun) logger.warning('DRY RUN — no files will be written')
 
   if (files.length === 0) {
@@ -115,11 +122,11 @@ export async function runImages(opts) {
     if (dryRun) continue
 
     if (!iphoneOnly) {
-      const androidFiles = await genAndroidScales(file, relPath, androidBaseDir, { format, quality })
+      const androidFiles = await genAndroidScales(file, relPath, androidBaseDir, { format, quality, baseWidth })
       written.push(...androidFiles)
     }
     if (!androidOnly) {
-      const iphoneFiles = await genIphoneScales(file, relPath, iphoneBaseDir, { format, quality })
+      const iphoneFiles = await genIphoneScales(file, relPath, iphoneBaseDir, { format, quality, baseWidth })
       written.push(...iphoneFiles)
     }
   }

package/src/core/purger/tailwind-purger.js

@@ -14,6 +14,7 @@ import _ from 'lodash'
 import chalk from 'chalk'
 import * as helpers from '../../shared/helpers.js'
 import { logger } from '../../shared/logger.js'
+import { deriveAlphaKey } from '../../shared/semantic-helpers.js'
 import {
   // eslint-disable-next-line camelcase
   projectsTailwind_TSS,
@@ -191,10 +192,20 @@ export function purgeTailwind(uniqueClasses, debug = false) {
       const opacityIndex = _.findIndex(tailwindClasses, line => line.startsWith(`'.${opacityValue.className}'`))
 
       const classProperties = tailwindClasses[opacityIndex]
-      if (opacityIndex > -1 && classProperties.includes('#')) {
-        // ! TODO: Check if color value is a hex value!! (if not, they are using rbg, rgba or semantic colors)
-        // ! In other words, we need to validate the color value, before we can alter its opacity.
-        const defaultHexValue = (classProperties.includes('from')) ? classProperties.match(/#[0-9a-f]{6}/g)[1] : classProperties.match(/#[0-9a-f]{6}/i)[0]
+      if (opacityIndex > -1 && classProperties && !classProperties.includes('#')) {
+        const derivedLine = tryDeriveSemanticOpacityLine(classProperties, opacityValue)
+        if (derivedLine) {
+          purgedClasses += switchPlatform(helpers.checkPlatformAndDevice(derivedLine, opacityValue.classNameWithTransparency))
+        } else {
+          console.warn('')
+          console.warn(chalk.yellow(`   Skipping ".${opacityValue.className}/${opacityValue.decimalValue}" — semantic color, no hex to blend.`))
+          console.warn(chalk.yellow(`   Use a PurgeTSS built-in color, bg-(#AARRGGBB), or "purgetss semantic --single ... --alpha ${opacityValue.decimalValue}".`))
+          console.warn('')
+        }
+      }
+      if (opacityIndex > -1 && classProperties && classProperties.includes('#')) {
+        const hexMatches = classProperties.match(/#[0-9a-f]{6}/gi)
+        const defaultHexValue = (classProperties.includes('from')) ? hexMatches[1] : hexMatches[0]
         let classWithoutDecimalOpacity = `${classProperties.replace(new RegExp(defaultHexValue.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), `#${opacityValue.transparency}${defaultHexValue.substring(1)}`)}`
         // Special case: #000000
         if (classProperties.includes('from') && defaultHexValue === '#000000') classWithoutDecimalOpacity = classWithoutDecimalOpacity.replace('00000000', '000000')
@@ -216,6 +227,31 @@ export function purgeTailwind(uniqueClasses, debug = false) {
   return purgedClasses
 }
 
+// Auto-derive a semantic key with applied alpha and emit a TSS line for the
+// `class/N` form. Returns the rewritten line (with selector renamed to include
+// `/N` and the semantic value swapped for the derived key), or `null` when no
+// candidate matches an entry in semantic.colors.json. Conflict errors from
+// `deriveAlphaKey` propagate naturally.
+function tryDeriveSemanticOpacityLine(classProperties, opacityValue) {
+  const bodyMatch = classProperties.match(/\{([^}]*)\}/)
+  if (!bodyMatch) return null
+  const candidates = (bodyMatch[1].match(/'([^']+)'/g) || [])
+    .map(m => m.slice(1, -1))
+    .filter(v => !v.startsWith('#'))
+  for (const candidate of candidates) {
+    const derivedKey = deriveAlphaKey(candidate, opacityValue.decimalValue)
+    if (derivedKey) {
+      let line = classProperties.replace(new RegExp(`'${candidate}'`, 'g'), `'${derivedKey}'`)
+      line = line.replace(
+        `'.${opacityValue.className}'`,
+        `'.${opacityValue.className}/${opacityValue.decimalValue}'`
+      )
+      return line
+    }
+  }
+  return null
+}
+
 /**
  * Switch platform specific styles - COPIED exactly from original switchPlatform() function
  * NO CHANGES to logic, preserving 100% of original functionality

package/src/shared/helpers/core.js

@@ -1,21 +1,2 @@
-// Import customRules function for resetStyles
-import { customRules } from './utils.js'
-
 // Global configurations
 export const globalOptions = {}
-
-/**
- * Reset styles for common Titanium components
- * Applies default styles to ImageView, View, and Window
- * @returns {string} Generated reset styles
- */
-export function resetStyles() {
-  let convertedStyles = '\n// Custom Styles and Resets\n'
-
-  convertedStyles += customRules({ ios: { hires: true } }, 'ImageView')
-  // convertedStyles += customRules({ default: { width: 'Ti.UI.FILL', height: 'Ti.UI.SIZE' } }, 'Label');
-  convertedStyles += customRules({ default: { width: 'Ti.UI.SIZE', height: 'Ti.UI.SIZE' } }, 'View')
-  convertedStyles += customRules({ default: { backgroundColor: '#ffffff' } }, 'Window')
-
-  return convertedStyles
-}

package/src/shared/helpers/utils.js

@@ -1,5 +1,6 @@
 import fs from 'fs'
 import _ from 'lodash'
+import { deriveAlphaKey } from '../semantic-helpers.js'
 
 // Internal variables and constants
 const _applyClasses = {}
@@ -530,15 +531,38 @@ export function compileApplyDirectives(twClasses) {
           const opacityIndex = findIndexOfClassName(`'.${opacityValue.classNameWithTransparency}`, twClassesArray)
 
           if (opacityIndex > -1) {
-            const defaultHexValue = (twClassesArray[opacityIndex].includes('from')) ? twClassesArray[opacityIndex].match(/#[0-9a-f]{6}/g)[1] : twClassesArray[opacityIndex].match(/#[0-9a-f]{6}/i)[0]
-            const classWithoutDecimalOpacity = `${twClassesArray[opacityIndex].replace(new RegExp(defaultHexValue.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), `#${opacityValue.transparency}${defaultHexValue.substring(1)}`)}`
+            const targetLine = twClassesArray[opacityIndex]
+            const hexMatches = targetLine.match(/#[0-9a-f]{6}/gi)
+
+            if (!hexMatches || (targetLine.includes('from') && hexMatches.length < 2)) {
+              const derivedLine = tryDeriveSemanticOpacity(targetLine, opacityValue.decimalValue)
+              if (derivedLine) {
+                compoundClasses.push(justProperties(derivedLine))
+                return
+              }
+              throw new Error(
+                `Opacity "/${opacityValue.decimalValue}" can't apply to semantic color ".${opacityValue.classNameWithTransparency}" (in apply of "${className}"). Use a PurgeTSS built-in color, an arbitrary value bg-(#AARRGGBB), or set alpha via "purgetss semantic --single ... --alpha ${opacityValue.decimalValue}".`
+              )
+            }
+
+            const defaultHexValue = targetLine.includes('from') ? hexMatches[1] : hexMatches[0]
+            const classWithoutDecimalOpacity = `${targetLine.replace(new RegExp(defaultHexValue.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), `#${opacityValue.transparency}${defaultHexValue.substring(1)}`)}`
 
             compoundClasses.push(justProperties(classWithoutDecimalOpacity))
           }
         })
       }
 
-      twClassesArray[indexOfModifier] = _.replace(twClassesArray[indexOfModifier], /{_applyProperties_}/, fixDuplicateKeys(compoundClasses).join(', '))
+      let mergedProperties
+      try {
+        mergedProperties = fixDuplicateKeys(compoundClasses).join(', ')
+      } catch (mergeError) {
+        const classList = [...values].join(' ')
+        throw new Error(
+          `Failed to merge apply directive of "${className}".\n   Classes: "${classList}".\n   Hint: this usually means an unsupported combination — e.g. "bg-gradient-to-X" together with "from-X to-Y" in the same apply (gradient direction is dropped on merge), or two utilities that map to the same property in incompatible shapes. Try splitting the rule or removing one of the conflicting classes.\n   Internal: ${mergeError.message}`
+        )
+      }
+      twClassesArray[indexOfModifier] = _.replace(twClassesArray[indexOfModifier], /{_applyProperties_}/, mergedProperties)
       twClassesArray[indexOfModifier] = deduplicateLineProperties(twClassesArray[indexOfModifier])
     }
   })
@@ -546,6 +570,26 @@ export function compileApplyDirectives(twClasses) {
   return twClassesArray.join('\n')
 }
 
+// Attempt to derive an alpha-applied semantic key from a TSS line whose value
+// is a semantic name (e.g. `'.bg-surface': { backgroundColor: 'surfaceColor' }`).
+// Returns the rewritten line with the derived key in place of the base name,
+// or `null` when no candidate matches an entry in semantic.colors.json.
+// Conflict errors from `deriveAlphaKey` propagate naturally.
+function tryDeriveSemanticOpacity(targetLine, alphaPercent) {
+  const bodyMatch = targetLine.match(/\{([^}]*)\}/)
+  if (!bodyMatch) return null
+  const candidates = (bodyMatch[1].match(/'([^']+)'/g) || [])
+    .map(m => m.slice(1, -1))
+    .filter(v => !v.startsWith('#'))
+  for (const candidate of candidates) {
+    const derivedKey = deriveAlphaKey(candidate, alphaPercent)
+    if (derivedKey) {
+      return targetLine.replace(new RegExp(`'${candidate}'`, 'g'), `'${derivedKey}'`)
+    }
+  }
+  return null
+}
+
 /**
  * Remove duplicate property keys in a TSS line, keeping the last occurrence.
  * This ensures apply directives override static defaults (e.g. backgroundColor).
@@ -593,13 +637,20 @@ export function justProperties(_foundClass) {
 
 export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
   const sign = (arbitraryValue.startsWith('-')) ? '-' : ''
-  const splitedContent = (arbitraryValue.startsWith('-')) ? arbitraryValue.substring(1).split('-') : arbitraryValue.split('-')
+  const stripped = sign ? arbitraryValue.substring(1) : arbitraryValue
 
-  if (splitedContent.length === 1) {
-    return ''
-  } else if (splitedContent.length === 2) {
-    let rule = splitedContent.slice(0, 1).join('-')
-    let value = splitedContent[1].match(/(?<=\().*(?=\))/).pop()
+  // Extract the value inside the last (...) so a negative value like top-(-10)
+  // is not mis-split by the hyphen inside the parentheses.
+  const parenMatch = stripped.match(/^(.+)-\(([^()]*)\)$/)
+  if (!parenMatch || parenMatch[2].trim() === '') {
+    return (fromXMLs) ? `// Property not yet supported: ${arbitraryValue}` : null
+  }
+
+  const ruleParts = parenMatch[1].split('-')
+  let value = parenMatch[2]
+
+  if (ruleParts.length === 1) {
+    let rule = ruleParts[0]
 
     if (rule === 'text') {
       rule = (value.includes('#') || value.includes('rgb')) ? 'text-color' : 'text-size'
@@ -630,13 +681,12 @@ export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
         ? `'.${arbitraryValue}': { ` + _.replace(properties, /{value}/g, parseValue(value, sign)) + ' }'
         : _.replace(properties, /{value}/g, parseValue(value, sign))
     }
-  } else if (splitedContent.length === 3) {
-    const rule = splitedContent.slice(0, 2).join('-')
-    const value = splitedContent[2].match(/(?<=\().*(?=\))/).pop()
+  } else if (ruleParts.length === 2) {
+    const rule = ruleParts.join('-')
     let properties = arbitraryValuesTable[rule]
 
     if (properties) {
-      if (splitedContent[0] === 'rounded') {
+      if (ruleParts[0] === 'rounded') {
         if (!value.includes(',')) {
           properties = _.replace(properties, /{value1}/g, parseValue(parseValue(value) / 2, sign))
         } else {
@@ -651,9 +701,8 @@ export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
         ? `'.${arbitraryValue}': { ` + _.replace(properties, /{value}/g, parseValue(value, sign)) + ' }'
         : _.replace(properties, /{value}/g, parseValue(value, sign))
     }
-  } else if (splitedContent.length === 4) {
-    const rule = splitedContent.slice(0, 3).join('-')
-    const value = splitedContent[3].match(/(?<=\().*(?=\))/).pop()
+  } else if (ruleParts.length === 3) {
+    const rule = ruleParts.join('-')
     let properties = arbitraryValuesTable[rule]
 
     if (properties) {
@@ -665,9 +714,8 @@ export function formatArbitraryValues(arbitraryValue, fromXMLs = false) {
         ? `'.${arbitraryValue}': { ` + _.replace(properties, /{value}/g, parseValue(value, sign)) + ' }'
         : _.replace(properties, /{value}/g, parseValue(value, sign))
     }
-  } else if (splitedContent.length === 5) {
-    const rule = splitedContent.slice(0, 4).join('-')
-    const value = splitedContent[4].match(/(?<=\().*(?=\))/).pop()
+  } else if (ruleParts.length === 4) {
+    const rule = ruleParts.join('-')
     const properties = arbitraryValuesTable[rule]
 
     if (properties) {
@@ -726,13 +774,22 @@ export function fixDuplicateKeys(compoundClasses) {
   const cleanedStyles = []
   const paddingObject = []
   const backgroundGradientObject = []
+  const backgroundGradientDirection = []
 
   _.each(compoundClasses, value => {
     if (compoundClasses.length > 1) {
       if (value.includes('font:')) {
         fontObject.push(value.replace('font: ', '').replace(/{(.*)}/, '$1').trim())
-      } else if (value.includes('backgroundGradient: { colors')) {
-        backgroundGradientObject.push(value.replace('backgroundGradient: ', '').replace(/{(.*)}/, '$1').trim())
+      } else if (value.includes('backgroundGradient:')) {
+        // Split into 2 buckets: colors (from-X/to-X) vs direction (bg-gradient-to-X with type/startPoint/endPoint).
+        // Both share the same property name `backgroundGradient` so they MUST be merged into a single object,
+        // otherwise the later one overwrites the earlier one in the emitted JS object literal.
+        const inner = value.replace('backgroundGradient: ', '').replace(/{(.*)}/, '$1').trim()
+        if (inner.startsWith('colors')) {
+          backgroundGradientObject.push(inner)
+        } else {
+          backgroundGradientDirection.push(inner)
+        }
       } else if (value.includes('padding:')) {
         paddingObject.push(value.replace('padding: ', '').replace(/{(.*)}/, '$1').trim())
       } else {
@@ -763,13 +820,28 @@ export function fixDuplicateKeys(compoundClasses) {
     cleanedStyles.push(`font: { ${fontObject.sort().join(', ')} }`)
   }
 
-  if (backgroundGradientObject.length === 1) {
-    cleanedStyles.push(`backgroundGradient: { ${backgroundGradientObject} }`)
-  } else if (backgroundGradientObject.length === 2) {
-    const toColor = backgroundGradientObject[1].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',')
-    const fromToColors = backgroundGradientObject[0].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',')
-    fromToColors[0] = toColor[0]
-    cleanedStyles.push(`backgroundGradient: { colors: [ '${fromToColors[0]}', '${fromToColors[1].trim()}' ] }`)
+  // Merge gradient direction (bg-gradient-to-X) and gradient colors (from-X/to-X)
+  // into a single backgroundGradient object. They share the same property name,
+  // so emitting them as separate entries causes the later one to overwrite the earlier.
+  if (backgroundGradientDirection.length || backgroundGradientObject.length) {
+    let colorsPart = ''
+    if (backgroundGradientObject.length === 1) {
+      colorsPart = backgroundGradientObject[0]
+    } else if (backgroundGradientObject.length === 2) {
+      // from-X emits 2 colors (placeholder + actual), to-X emits 1.
+      // After sort() above, indices may swap depending on color name ordering,
+      // so identify by array length instead of position.
+      const colorsA = backgroundGradientObject[0].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',').map(c => c.trim())
+      const colorsB = backgroundGradientObject[1].replace('colors: ', '').replace(/[[\]']+/g, '').trim().split(',').map(c => c.trim())
+      const fromEntry = colorsA.length === 2 ? colorsA : colorsB
+      const toEntry = colorsA.length === 1 ? colorsA : colorsB
+      colorsPart = `colors: [ '${toEntry[0]}', '${fromEntry[1]}' ]`
+    }
+
+    const parts = []
+    if (backgroundGradientDirection.length) parts.push(backgroundGradientDirection[0])
+    if (colorsPart) parts.push(colorsPart)
+    cleanedStyles.push(`backgroundGradient: { ${parts.join(', ')} }`)
   }
 
   // Missing properties to process

package/src/shared/semantic-helpers.js

@@ -0,0 +1,143 @@
+/**
+ * PurgeTSS - Semantic Colors Helpers
+ *
+ * Auto-derivation of semantic color keys with applied alpha for opacity
+ * modifiers (e.g. `bg-surface/65`). Mutates `semantic.colors.json` idempotently
+ * by adding `<originalKey>_<alphaPercent>` entries with `{ color, alpha }` for
+ * `light` and `dark`.
+ *
+ * Lifecycle:
+ *   - Names of semantic colors are tracked via `registerSemanticName()` while
+ *     the utilities builder expands `theme.extend.colors`.
+ *   - Hooks in `tailwind-purger` and `compileApplyDirectives` call
+ *     `deriveAlphaKey()` before falling back to warn/throw on missing hex.
+ *   - CLI commands flush the cached JSON to disk via `flushSemanticColors()`
+ *     at the end of their run.
+ *
+ * @fileoverview Semantic color auto-derivation for opacity modifiers
+ * @since 7.9.0
+ */
+
+import fs from 'fs'
+import { getSemanticColorsPath } from '../cli/utils/project-detection.js'
+
+const _semanticNames = new Set()
+let _cache = null
+let _dirty = false
+let _lastMtime = 0
+let _lastPath = null
+
+/**
+ * Reset all in-memory state. Intended for tests; not part of the public API.
+ */
+export function _resetSemanticHelpersState() {
+  _semanticNames.clear()
+  _cache = null
+  _dirty = false
+  _lastMtime = 0
+  _lastPath = null
+}
+
+/**
+ * Track a name that resolves to a semantic color (string, non-hex). Called by
+ * the utilities builder while expanding `theme.extend.colors`.
+ *
+ * @param {string} name
+ */
+export function registerSemanticName(name) {
+  if (typeof name === 'string' && name.length > 0) _semanticNames.add(name)
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isSemanticColorName(name) {
+  return _semanticNames.has(name)
+}
+
+/**
+ * Load `semantic.colors.json` for the current project. Cached by mtime so
+ * repeated calls in the same build are cheap. The cache is invalidated when
+ * the file mtime changes on disk (relevant for watch-mode cycles where the
+ * JSON gets rewritten between runs).
+ *
+ * @returns {Object} parsed JSON, or `{}` when the file doesn't exist
+ */
+export function loadSemanticColors() {
+  const p = getSemanticColorsPath()
+  if (!fs.existsSync(p)) {
+    _cache = {}
+    _lastMtime = 0
+    _lastPath = p
+    return _cache
+  }
+  const mtime = fs.statSync(p).mtimeMs
+  if (_cache && _lastPath === p && mtime === _lastMtime) return _cache
+  _cache = JSON.parse(fs.readFileSync(p, 'utf8'))
+  _lastMtime = mtime
+  _lastPath = p
+  return _cache
+}
+
+/**
+ * Derive a semantic key with the requested alpha applied. Idempotent: if the
+ * derived key already exists with matching values it's reused; if it exists
+ * with conflicting values an Error is thrown so manual edits aren't silently
+ * overwritten.
+ *
+ * @param {string} baseKey - The original semantic key (e.g. `surfaceColor`).
+ * @param {number|string} alphaPercent - Integer 0..100 (e.g. 65).
+ * @returns {string|null} The derived key, or `null` if `baseKey` isn't in the JSON.
+ */
+export function deriveAlphaKey(baseKey, alphaPercent) {
+  const semantic = loadSemanticColors()
+  const base = semantic[baseKey]
+  if (!base) return null
+
+  const alphaStr = String(alphaPercent)
+  const newKey = `${baseKey}_${alphaStr}`
+
+  const lightHex = typeof base.light === 'string' ? base.light : base.light?.color
+  const darkHex = typeof base.dark === 'string' ? base.dark : base.dark?.color
+
+  if (semantic[newKey]) {
+    const existing = semantic[newKey]
+    const existingLightHex = typeof existing.light === 'string' ? existing.light : existing.light?.color
+    const existingDarkHex = typeof existing.dark === 'string' ? existing.dark : existing.dark?.color
+    const existingLightAlpha = typeof existing.light === 'string' ? null : existing.light?.alpha
+    const existingDarkAlpha = typeof existing.dark === 'string' ? null : existing.dark?.alpha
+
+    if (
+      existingLightHex !== lightHex ||
+      existingDarkHex !== darkHex ||
+      existingLightAlpha !== alphaStr ||
+      existingDarkAlpha !== alphaStr
+    ) {
+      throw new Error(
+        `Conflict: "${newKey}" already exists in semantic.colors.json with different values. Manual edit detected — resolve before continuing.`
+      )
+    }
+    return newKey
+  }
+
+  semantic[newKey] = {
+    light: { color: lightHex, alpha: alphaStr },
+    dark: { color: darkHex, alpha: alphaStr }
+  }
+  _dirty = true
+  return newKey
+}
+
+/**
+ * Persist any pending derivations back to `semantic.colors.json`. No-op when
+ * nothing changed. Writes a trailing newline for clean git diffs.
+ */
+export function flushSemanticColors() {
+  if (!_dirty) return
+  const p = getSemanticColorsPath()
+  fs.writeFileSync(p, JSON.stringify(_cache, null, 2) + '\n')
+  _dirty = false
+  _lastMtime = fs.statSync(p).mtimeMs
+  _lastPath = p
+}

package/src/dev/builders/tailwind-builder.js

@@ -1,26 +0,0 @@
-/**
- * PurgeTSS v7.1 - Tailwind Builder (Development)
- *
- * Builds Tailwind CSS files for development/distribution using auto-generation.
- * COPIED from lib/build-tailwind.js - NO CHANGES to logic.
- *
- * Generates: ./dist/utilities.tss
- *
- * @since 7.1.0 (refactored from lib/)
- * @author César Estrada
- */
-
-import { autoBuildUtilitiesTSS } from '../../../experimental/completions2.js'
-
-/**
- * Main builder function
- * COPIED exactly from original constructor() function
- */
-export function buildTailwind() {
-  autoBuildUtilitiesTSS()
-}
-
-// Execute if run directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  buildTailwind()
-}