purgetss 7.7.1 → 7.11.1

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

@@ -1,26 +1,18 @@
 /**
- * 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.
+ * PurgeTSS - Utilities Builder (Development entry point)
  *
+ * Thin CLI wrapper invoked by the `build:tailwind` npm script.
  * Generates: ./dist/utilities.tss
  *
- * @since 7.1.0 (refactored from lib/)
  * @author César Estrada
  */
 
-import { autoBuildUtilitiesTSS } from '../../../experimental/completions2.js'
+import { autoBuildUtilitiesTSS } from '../../core/builders/auto-utilities-builder.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()
 }

package/src/shared/config-manager.js

@@ -23,6 +23,7 @@ import {
 } from './constants.js'
 import { logger } from './logger.js'
 import { makeSureFolderExists } from './utils.js'
+import { validateConfig } from './validation/config-validator.js'
 
 // Create require for ESM compatibility
 const require = createRequire(import.meta.url)
@@ -105,6 +106,71 @@ export function migrateConfigIfNeeded() {
   }
 }
 
+// Tracks configs already warned about in this process so the deprecation
+// notice prints once per session even if getConfigFile() is called many times.
+const _warnedLegacyBrand = new Set()
+
+/**
+ * Migrate the flat pre-7cb5890 `brand:` schema (padding as number, iosPadding,
+ * bgColor, darkBgColor, top-level notification/splash) into the grouped
+ * schema downstream code expects. Mutates in place; if both legacy and new
+ * keys coexist, the new key wins. Emits ONE warning per config path per session.
+ */
+function normalizeLegacyBrand(configFile, sourcePath) {
+  const brand = configFile.brand
+  if (!brand || typeof brand !== 'object') return
+
+  const hits = []
+
+  if (brand.padding != null && typeof brand.padding !== 'object') {
+    const value = brand.padding
+    brand.padding = { androidLegacy: value, androidAdaptive: value }
+    hits.push(`brand.padding: ${JSON.stringify(value)} → brand.padding.androidLegacy + brand.padding.androidAdaptive`)
+  }
+
+  if ('iosPadding' in brand) {
+    brand.padding = (brand.padding && typeof brand.padding === 'object') ? brand.padding : {}
+    brand.padding.ios = brand.padding.ios ?? brand.iosPadding
+    hits.push('brand.iosPadding → brand.padding.ios')
+    delete brand.iosPadding
+  }
+
+  if ('bgColor' in brand) {
+    brand.colors = brand.colors ?? {}
+    brand.colors.background = brand.colors.background ?? brand.bgColor
+    hits.push('brand.bgColor → brand.colors.background')
+    delete brand.bgColor
+  }
+
+  if ('darkBgColor' in brand) {
+    brand.ios = brand.ios ?? {}
+    brand.ios.darkBackground = brand.ios.darkBackground ?? brand.darkBgColor
+    hits.push('brand.darkBgColor → brand.ios.darkBackground')
+    delete brand.darkBgColor
+  }
+
+  if ('notification' in brand) {
+    brand.android = brand.android ?? {}
+    brand.android.notification = brand.android.notification ?? brand.notification
+    hits.push('brand.notification → brand.android.notification')
+    delete brand.notification
+  }
+
+  if ('splash' in brand) {
+    brand.android = brand.android ?? {}
+    brand.android.splash = brand.android.splash ?? brand.splash
+    hits.push('brand.splash → brand.android.splash')
+    delete brand.splash
+  }
+
+  if (hits.length > 0 && !_warnedLegacyBrand.has(sourcePath)) {
+    _warnedLegacyBrand.add(sourcePath)
+    logger.warn('Legacy brand: schema detected in purgetss/config.cjs — auto-migrated in memory:')
+    for (const hit of hits) logger.item(`  • ${hit}`)
+    logger.item('  Update purgetss/config.cjs to the new grouped schema to silence this warning.')
+  }
+}
+
 /**
  * Get configuration file with fallback to default template
  * Maintains exact same logic as original getConfigFile()
@@ -113,9 +179,11 @@ export function migrateConfigIfNeeded() {
  */
 export function getConfigFile() {
 
-  const configFile = (fs.existsSync(projectsConfigJS))
-    ? require(projectsConfigJS)
-    : require(srcConfigFile)
+  const sourcePath = fs.existsSync(projectsConfigJS) ? projectsConfigJS : srcConfigFile
+  const configFile = require(sourcePath)
+
+  validateConfig(configFile, sourcePath)
+  normalizeLegacyBrand(configFile, sourcePath)
 
   // Apply default values following template structure
   configFile.purge = configFile.purge ?? {}
@@ -133,6 +201,7 @@ export function getConfigFile() {
   configFile.brand.padding.ios = parsePadding(configFile.brand.padding.ios ?? 4, 'brand.padding.ios')
   configFile.brand.padding.androidLegacy = parsePadding(configFile.brand.padding.androidLegacy ?? 10, 'brand.padding.androidLegacy')
   configFile.brand.padding.androidAdaptive = parsePadding(configFile.brand.padding.androidAdaptive ?? 19, 'brand.padding.androidAdaptive')
+  configFile.brand.padding.featureGraphic = parsePadding(configFile.brand.padding.featureGraphic ?? 12, 'brand.padding.featureGraphic')
   configFile.brand.android = configFile.brand.android ?? {}
   configFile.brand.android.notification = configFile.brand.android.notification ?? false
   configFile.brand.android.splash = configFile.brand.android.splash ?? false

package/src/shared/error-reporter.js

@@ -0,0 +1,117 @@
+/**
+ * Centralized error reporter for syntax errors detected by PurgeTSS.
+ *
+ * Visual format matches the patterns already used by:
+ *   - XML Syntax Error (src/cli/commands/purge.js, "compact" variant)
+ *   - Class Syntax Error (src/cli/utils/unsupported-class-reporter.js)
+ *   - XML Syntax Error with Context (src/cli/commands/purge.js, "context" variant)
+ *
+ * Those call sites are NOT migrated yet — they keep their own inline formatters
+ * to avoid any chance of visual regression. New validators (config-validator)
+ * use this module so the look is consistent going forward.
+ *
+ * Two output paths:
+ *   - formatSyntaxError(opts) → { header, lines } suitable for logger.block(...)
+ *   - throwSyntaxError(opts)  → throws an Error whose .message is the full
+ *                               pre-rendered string (for call sites that
+ *                               propagate errors via catch handlers).
+ */
+
+import chalk from 'chalk'
+import path from 'path'
+import { logger } from './logger.js'
+
+/**
+ * Build the displayable parts of a syntax error.
+ *
+ * @param {Object} opts
+ * @param {string} opts.type      - Short name shown in the header, e.g. 'Config', 'XML', 'Class'.
+ * @param {string} [opts.file]    - File path (will be made relative to cwd).
+ * @param {string|number} [opts.path] - Dotted JSON path (optional, for config errors).
+ * @param {number} [opts.line]    - Line number where the error occurred.
+ * @param {string} [opts.content] - One-line snippet of the offending line.
+ * @param {string[]} [opts.contextLines] - Full file lines (1-based; pass src.split('\n') OK with 0-based,
+ *                                          but `line` must point to a 1-based number; we slice ±2).
+ * @param {string} opts.issue     - Description of what is wrong.
+ * @param {string} opts.fix       - Suggested correction.
+ * @returns {{ header: string, lines: string[] }}
+ */
+export function formatSyntaxError(opts) {
+  const {
+    type,
+    file,
+    path: jsonPath,
+    line,
+    content,
+    contextLines,
+    issue,
+    fix
+  } = opts
+
+  const lines = []
+
+  if (file) {
+    const relative = path.relative(process.cwd(), file) || file
+    lines.push(`File: ${chalk.yellow(`"${relative}"`)}`)
+  }
+  if (jsonPath) {
+    lines.push(`Path: ${chalk.yellow(jsonPath)}`)
+  }
+  if (line != null) {
+    lines.push(`Line: ${chalk.yellow(line)}`)
+  }
+
+  // Context block: ± 2 lines around the offending line.
+  if (Array.isArray(contextLines) && line) {
+    const total = contextLines.length
+    const startLine = Math.max(1, line - 2)
+    const endLine = Math.min(total, line + 2)
+
+    lines.push('')
+    lines.push(chalk.gray('Context:'))
+    for (let i = startLine; i <= endLine; i++) {
+      const isTarget = i === line
+      const prefix = isTarget ? chalk.red('>>>') : chalk.gray('   ')
+      const text = contextLines[i - 1] || ''
+      lines.push(`${prefix} ${chalk.gray(String(i).padStart(3, ' '))}: ${text}`)
+    }
+  } else if (content) {
+    lines.push(`Content: ${chalk.yellow(`"${content}"`)}`)
+  }
+
+  lines.push('')
+  lines.push(chalk.red(`Issue: ${issue}`))
+  lines.push(`${chalk.green('Fix:')} ${fix}`)
+
+  return {
+    header: chalk.red(`${type} Syntax Error`),
+    lines
+  }
+}
+
+/**
+ * Log the syntax error directly via logger.block.
+ * Use when you want the error rendered now and execution to continue
+ * (or stop via a sentinel afterward).
+ */
+export function logSyntaxError(opts) {
+  const { header, lines } = formatSyntaxError(opts)
+  logger.block(header, ...lines)
+}
+
+/**
+ * Throw an Error whose .message is the fully rendered report.
+ * Use when the error must bubble up through a catch handler that prints
+ * `error.message` (e.g. the top-level CLI catch in bin/purgetss).
+ *
+ * The thrown Error includes `isSyntaxError: true` so callers can distinguish
+ * presentation-ready errors from generic runtime failures.
+ */
+export function throwSyntaxError(opts) {
+  const { header, lines } = formatSyntaxError(opts)
+  const text = `\n::PurgeTSS:: ${header}\n` + lines.map(l => '   ' + l).join('\n') + '\n'
+  const err = new Error(text)
+  err.isSyntaxError = true
+  err.syntaxErrorType = opts.type
+  throw err
+}

package/src/shared/helpers/colors.js

@@ -1,5 +1,5 @@
 import _ from 'lodash'
-import { processProperties, processComments, parseValue, setModifier2, removeLastDash, addTransparencyToValue } from './utils.js'
+import { processProperties, processComments, parseValue, setModifier2, removeLastDash, addTransparencyToValue, defaultModifier, camelCaseToDash } from './utils.js'
 /**
  * Active tint color for tabs
  * @param {Object} modifiersAndValues - Modifier and value pairs
@@ -646,9 +646,20 @@ export function backgroundGradient(modifiersAndValues) {
   _.each(objectPosition, (properties, rule) => {
     _.each(modifiersAndValues, (value, modifier) => {
       if (typeof value === 'object') {
-        _.each(value, (_value, _modifier) => {
-          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}`)}': ` + _.replace(_.replace(properties, /{transparentValue}/g, `${addTransparencyToValue(parseValue(_value))}`), /{value}/g, parseValue(_value)) + '\n'
-        })
+        const emitLeaf = (leafValue, _modifier, suffix) => {
+          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}${suffix}`)}': ` + _.replace(_.replace(properties, /{transparentValue}/g, `${addTransparencyToValue(parseValue(leafValue))}`), /{value}/g, parseValue(leafValue)) + '\n'
+        }
+        const walk = (val, _modifier, suffix) => {
+          if (val && typeof val === 'object') {
+            _.each(val, (childVal, childKey) => {
+              const newSuffix = defaultModifier(childKey) ? suffix : `${suffix}-${camelCaseToDash(String(childKey))}`
+              walk(childVal, _modifier, newSuffix)
+            })
+          } else {
+            emitLeaf(val, _modifier, suffix)
+          }
+        }
+        _.each(value, (_value, _modifier) => walk(_value, _modifier, ''))
       } else {
         convertedStyles += `'.${setModifier2(rule, modifier)}${setModifier2(modifier)}': ` + _.replace(_.replace(properties, /{value}/g, parseValue(value)), /{transparentValue}/g, `${addTransparencyToValue(parseValue(value))}`) + '\n'
       }
@@ -665,9 +676,20 @@ export function backgroundGradient(modifiersAndValues) {
   _.each(objectPosition, (properties, rule) => {
     _.each(modifiersAndValues, (value, modifier) => {
       if (typeof value === 'object') {
-        _.each(value, (_value, _modifier) => {
-          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}`)}': ` + _.replace(properties, /{value}/g, parseValue(_value)) + '\n'
-        })
+        const emitLeaf = (leafValue, _modifier, suffix) => {
+          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}${suffix}`)}': ` + _.replace(properties, /{value}/g, parseValue(leafValue)) + '\n'
+        }
+        const walk = (val, _modifier, suffix) => {
+          if (val && typeof val === 'object') {
+            _.each(val, (childVal, childKey) => {
+              const newSuffix = defaultModifier(childKey) ? suffix : `${suffix}-${camelCaseToDash(String(childKey))}`
+              walk(childVal, _modifier, newSuffix)
+            })
+          } else {
+            emitLeaf(val, _modifier, suffix)
+          }
+        }
+        _.each(value, (_value, _modifier) => walk(_value, _modifier, ''))
       } else {
         convertedStyles += `'.${setModifier2(rule, modifier)}${setModifier2(modifier)}': ` + _.replace(properties, /{value}/g, parseValue(value)) + '\n'
       }
@@ -688,9 +710,20 @@ export function backgroundSelectedGradient(modifiersAndValues) {
   _.each(objectPosition, (properties, rule) => {
     _.each(modifiersAndValues, (value, modifier) => {
       if (typeof value === 'object') {
-        _.each(value, (_value, _modifier) => {
-          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}`)}': ` + _.replace(_.replace(properties, /{transparentValue}/g, `${addTransparencyToValue(parseValue(_value))}`), /{value}/g, parseValue(_value)) + '\n'
-        })
+        const emitLeaf = (leafValue, _modifier, suffix) => {
+          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}${suffix}`)}': ` + _.replace(_.replace(properties, /{transparentValue}/g, `${addTransparencyToValue(parseValue(leafValue))}`), /{value}/g, parseValue(leafValue)) + '\n'
+        }
+        const walk = (val, _modifier, suffix) => {
+          if (val && typeof val === 'object') {
+            _.each(val, (childVal, childKey) => {
+              const newSuffix = defaultModifier(childKey) ? suffix : `${suffix}-${camelCaseToDash(String(childKey))}`
+              walk(childVal, _modifier, newSuffix)
+            })
+          } else {
+            emitLeaf(val, _modifier, suffix)
+          }
+        }
+        _.each(value, (_value, _modifier) => walk(_value, _modifier, ''))
       } else {
         convertedStyles += `'.${setModifier2(rule, modifier)}${setModifier2(modifier)}': ` + _.replace(_.replace(properties, /{value}/g, parseValue(value)), /{transparentValue}/g, `${addTransparencyToValue(parseValue(value))}`) + '\n'
       }
@@ -707,9 +740,20 @@ export function backgroundSelectedGradient(modifiersAndValues) {
   _.each(objectPosition, (properties, rule) => {
     _.each(modifiersAndValues, (value, modifier) => {
       if (typeof value === 'object') {
-        _.each(value, (_value, _modifier) => {
-          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}`)}': ` + _.replace(properties, /{value}/g, parseValue(_value)) + '\n'
-        })
+        const emitLeaf = (leafValue, _modifier, suffix) => {
+          convertedStyles += `'.${removeLastDash(`${rule}-${setModifier2(modifier, rule)}${setModifier2(_modifier)}${suffix}`)}': ` + _.replace(properties, /{value}/g, parseValue(leafValue)) + '\n'
+        }
+        const walk = (val, _modifier, suffix) => {
+          if (val && typeof val === 'object') {
+            _.each(val, (childVal, childKey) => {
+              const newSuffix = defaultModifier(childKey) ? suffix : `${suffix}-${camelCaseToDash(String(childKey))}`
+              walk(childVal, _modifier, newSuffix)
+            })
+          } else {
+            emitLeaf(val, _modifier, suffix)
+          }
+        }
+        _.each(value, (_value, _modifier) => walk(_value, _modifier, ''))
       } else {
         convertedStyles += `'.${setModifier2(rule, modifier)}${setModifier2(modifier)}': ` + _.replace(properties, /{value}/g, parseValue(value)) + '\n'
       }

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,13 @@
 import fs from 'fs'
 import _ from 'lodash'
+import { deriveAlphaKey } from '../semantic-helpers.js'
+import {
+  projectsFA_TSS_File,
+  srcFontAwesomeTSSFile,
+  srcMaterialIconsTSSFile,
+  srcMaterialSymbolsTSSFile,
+  srcFramework7FontTSSFile
+} from '../constants.js'
 
 // Internal variables and constants
 const _applyClasses = {}
@@ -29,14 +37,25 @@ export function processProperties(info, selectorAndDeclarationBlock, selectorsAn
       _.each(rulesAndValuesPair, (value, rule) => {
         if (debug) console.log('rule:', rule, 'value:', value)
         if (typeof value === 'object') {
-          _.each(value, (_value, key) => {
-            if (debug) console.log('key:', key, '_value:', _value)
-            let processedProperties = _.replace(declarationBlock, /{value}/g, parseValue(_value, minusSigns))
+          const emitLeaf = (leafValue, key, suffix) => {
+            if (debug) console.log('key:', key, 'leafValue:', leafValue, 'suffix:', suffix)
+            let processedProperties = _.replace(declarationBlock, /{value}/g, parseValue(leafValue, minusSigns))
             if (declarationBlock.includes('double')) {
-              processedProperties = _.replace(processedProperties, /{double}/g, parseValue(_value, minusSigns) * 2)
+              processedProperties = _.replace(processedProperties, /{double}/g, parseValue(leafValue, minusSigns) * 2)
             }
-            convertedStyles += defaultModifier(key) ? `'.${setModifier2(mainSelector, rule)}${setModifier2(rule)}${setModifier2(selector)}': ${processedProperties}\n` : `'.${setModifier2(mainSelector, rule)}${setModifier2(rule, key)}${setModifier2(key)}${setModifier2(selector)}': ${processedProperties}\n`
-          })
+            convertedStyles += defaultModifier(key) ? `'.${setModifier2(mainSelector, rule)}${setModifier2(rule)}${suffix}${setModifier2(selector)}': ${processedProperties}\n` : `'.${setModifier2(mainSelector, rule)}${setModifier2(rule, key)}${setModifier2(key)}${suffix}${setModifier2(selector)}': ${processedProperties}\n`
+          }
+          const walk = (val, key, suffix) => {
+            if (val && typeof val === 'object') {
+              _.each(val, (childVal, childKey) => {
+                const newSuffix = defaultModifier(childKey) ? suffix : `${suffix}-${camelCaseToDash(String(childKey))}`
+                walk(childVal, key, newSuffix)
+              })
+            } else {
+              emitLeaf(val, key, suffix)
+            }
+          }
+          _.each(value, (_value, key) => walk(_value, key, ''))
         } else {
           let processedProperties = _.replace(declarationBlock, /{value}/g, parseValue(value, minusSigns))
           if (declarationBlock.includes('double')) {
@@ -463,6 +482,18 @@ export function compileApplyDirectives(twClasses) {
   const twClassesArray = twClasses.split(/\r?\n/)
   const fontsClassesArray = (fs.existsSync(cwd + '/purgetss/styles/fonts.tss')) ? fs.readFileSync(cwd + '/purgetss/styles/fonts.tss', 'utf8').split(/\r?\n/) : null
 
+  // Default icon font sources (FontAwesome, Material Icons/Symbols, Framework7).
+  // Project-level fontawesome.tss (Pro/Beta) takes precedence over the bundled default,
+  // matching the precedence used by purgeFontAwesome().
+  const iconClassesArrays = [
+    fs.existsSync(projectsFA_TSS_File) ? projectsFA_TSS_File : srcFontAwesomeTSSFile,
+    srcMaterialIconsTSSFile,
+    srcMaterialSymbolsTSSFile,
+    srcFramework7FontTSSFile
+  ]
+    .filter(p => fs.existsSync(p))
+    .map(p => fs.readFileSync(p, 'utf8').split(/\r?\n/))
+
   _.each(_applyClasses, (values, className) => {
     const indexOfModifier = findIndexOfClassName(`'${className}':`, twClassesArray)
 
@@ -518,6 +549,14 @@ export function compileApplyDirectives(twClasses) {
             if (!foundClass && fontsClassesArray) {
               foundClass = fontsClassesArray[findIndexOfClassName(genericClassName, fontsClassesArray)]
             }
+            // Last resort: search default icon font sources (FontAwesome, Material Icons/Symbols, Framework7)
+            // so apply: directives can use fas, fa-*, mi-*, ms-*, f7-* without requiring fonts.tss
+            if (!foundClass) {
+              for (const arr of iconClassesArrays) {
+                const idx = findIndexOfClassName(genericClassName, arr)
+                if (idx !== -1) { foundClass = arr[idx]; break }
+              }
+            }
           }
 
           if (foundClass) compoundClasses.push(justProperties(foundClass))
@@ -530,15 +569,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 +608,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).
@@ -563,8 +645,8 @@ function deduplicateLineProperties(line) {
   let depth = 0
   let current = ''
   for (const char of propsStr) {
-    if (char === '{') depth++
-    else if (char === '}') depth--
+    if (char === '{' || char === '[') depth++
+    else if (char === '}' || char === ']') depth--
     else if (char === ',' && depth === 0) {
       if (current.trim()) props.push(current.trim())
       current = ''
@@ -593,13 +675,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
+
+  // 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 (splitedContent.length === 1) {
-    return ''
-  } else if (splitedContent.length === 2) {
-    let rule = splitedContent.slice(0, 1).join('-')
-    let value = splitedContent[1].match(/(?<=\().*(?=\))/).pop()
+  if (ruleParts.length === 1) {
+    let rule = ruleParts[0]
 
     if (rule === 'text') {
       rule = (value.includes('#') || value.includes('rgb')) ? 'text-color' : 'text-size'
@@ -630,13 +719,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 +739,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 +752,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 +812,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 +858,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