purgetss 7.5.3 → 7.6.1

package/src/cli/commands/icon-library.js

@@ -100,7 +100,7 @@ function copyFreeFonts() {
   fs.copyFile(srcFonts_Folder + '/FontAwesome7Free-Regular.ttf', projectsFontsFolder + '/FontAwesome7Free-Regular.ttf', callback)
   fs.copyFile(srcFonts_Folder + '/FontAwesome7Free-Solid.ttf', projectsFontsFolder + '/FontAwesome7Free-Solid.ttf', callback)
 
-  logger.warn(' - Font Awesome Free')
+  logger.item(chalk.green('Font Awesome Free'))
 }
 
 /**
@@ -111,7 +111,7 @@ function copyFreeFonts() {
 function copyProFonts(fontFamilies, webFonts) {
   _.each(fontFamilies, (dest, src) => {
     if (copyFile(`${webFonts}/${src}`, dest)) {
-      logger.warn(` - ${dest} Font copied to`, chalk.yellow('./app/assets/fonts'), 'folder')
+      logger.item(`${dest} copied to ${chalk.yellow('./app/assets/fonts')}`)
     }
   })
 }
@@ -133,7 +133,7 @@ function copyMaterialIconsFonts() {
     copyFile(`${srcFonts_Folder}/${familyName}`, familyName)
   })
 
-  logger.warn(' - Material Icons')
+  logger.item(chalk.green('Material Icons'))
 }
 
 /**
@@ -151,7 +151,7 @@ function copyMaterialSymbolsFonts() {
     copyFile(`${srcFonts_Folder}/${familyName}`, familyName)
   })
 
-  logger.warn(' - Material Symbols')
+  logger.item(chalk.green('Material Symbols'))
 }
 
 /**
@@ -160,7 +160,7 @@ function copyMaterialSymbolsFonts() {
 function copyFramework7IconsFonts() {
   // Framework7 Font
   copyFile(srcFonts_Folder + '/Framework7-Icons.ttf', 'Framework7-Icons.ttf')
-  logger.warn(' - Framework 7')
+  logger.item(chalk.green('Framework 7'))
 }
 
 /**
@@ -170,7 +170,7 @@ function copyFramework7IconsFonts() {
 function buildFontAwesomeJS() {
   // This function should be imported from the fonts module
   // For now, just log that it would be called
-  logger.warn(' - Font Awesome JS module would be built')
+  logger.item(chalk.yellow('Font Awesome JS module would be built'))
 }
 
 /**
@@ -218,23 +218,23 @@ function copyFontLibrary(vendor) {
         buildFontAwesomeJS()
       } else {
         fs.copyFileSync(srcLibFA, projectsLibFolder + '/fontawesome.js')
-        logger.warn(' - fontawesome.js')
+        logger.item(chalk.yellow('fontawesome.js'))
       }
       break
     case 'mi':
     case 'materialicons':
       fs.copyFileSync(srcLibMI, projectsLibFolder + '/materialicons.js')
-      logger.warn(' - materialicons.js')
+      logger.item(chalk.yellow('materialicons.js'))
       break
     case 'ms':
     case 'materialsymbol':
       fs.copyFileSync(srcLibMS, projectsLibFolder + '/materialsymbols.js')
-      logger.warn(' - materialsymbols.js')
+      logger.item(chalk.yellow('materialsymbols.js'))
       break
     case 'f7':
     case 'framework7':
       fs.copyFileSync(srcLibF7, projectsLibFolder + '/framework7icons.js')
-      logger.warn(' - framework7icons.js')
+      logger.item(chalk.yellow('framework7icons.js'))
       break
   }
 }
@@ -251,23 +251,23 @@ function copyFontStyle(vendor) {
         buildFontAwesomeJS()
       } else {
         fs.copyFileSync(srcFontAwesomeTSSFile, projectsPurge_TSS_Styles_Folder + '/fontawesome.tss')
-        logger.warn(' - fontawesome.tss')
+        logger.item(chalk.yellow('fontawesome.tss'))
       }
       break
     case 'mi':
     case 'materialicons':
       fs.copyFileSync(srcMaterialIconsTSSFile, projectsPurge_TSS_Styles_Folder + '/materialicons.tss')
-      logger.warn(' - materialicons.tss')
+      logger.item(chalk.yellow('materialicons.tss'))
       break
     case 'ms':
     case 'materialsymbol':
       fs.copyFileSync(srcMaterialSymbolsTSSFile, projectsPurge_TSS_Styles_Folder + '/materialsymbols.tss')
-      logger.warn(' - materialsymbols.tss')
+      logger.item(chalk.yellow('materialsymbols.tss'))
       break
     case 'f7':
     case 'framework7':
       fs.copyFileSync(srcFramework7FontTSSFile, projectsPurge_TSS_Styles_Folder + '/framework7icons.tss')
-      logger.warn(' - framework7icons.tss')
+      logger.item(chalk.yellow('framework7icons.tss'))
       break
   }
 }
@@ -391,8 +391,10 @@ export async function copyModulesLibrary() {
       logger.info(chalk.yellow('purgetss.ui'), 'module copied to', chalk.yellow('./Resources/lib'), 'folder')
       return true
     } else {
-      logger.info(`Please make sure you are running ${chalk.green('purgetss')} within an Alloy or Classic Project.`)
-      logger.info(`For more information, visit ${chalk.green('https://purgetss.com')}`)
+      logger.block(
+        `Please make sure you are running ${chalk.green('purgetss')} within an Alloy or Classic Project.`,
+        `For more information, visit ${chalk.green('https://purgetss.com')}`
+      )
       return false
     }
   } catch (error) {

package/src/cli/commands/images.js

@@ -0,0 +1,116 @@
+/**
+ * PurgeTSS - Images Command
+ *
+ * Generates multi-density variants of UI images for Titanium Alloy or Classic
+ * projects. Auto-discovers sources in `./purgetss/images/` by default; accepts
+ * a path argument to override (file or directory).
+ *
+ * Precedence for every option: CLI flag > `images:` section in config > default.
+ *
+ * @fileoverview Assets command entry point
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import chalk from 'chalk'
+import { runImages } from '../../core/images/index.js'
+import { logger } from '../../core/branding/branding-logger.js'
+import { ensureImagesSection } from '../../core/images/ensure-images-section.js'
+import { getConfigFile } from '../../shared/config-manager.js'
+import { projectsPurge_TSS_Images_Folder } from '../../shared/constants.js'
+
+const VALID_FORMATS = new Set(['webp', 'jpeg', 'jpg', 'png', 'avif', 'gif', 'tiff'])
+
+export async function images(cliSource, options = {}) {
+  if (options.debug) logger.setDebugMode(true)
+
+  const projectRoot = options.project ? path.resolve(options.project) : process.cwd()
+
+  if (!options.project) ensureImagesSection()
+
+  const cfg = loadImagesSection()
+
+  // --android and --ios are mutually exclusive.
+  if (options.android && options.ios) {
+    logger.error('--android and --ios are mutually exclusive. Pass neither to generate both, or pick one.')
+    process.exit(1)
+  }
+
+  const format = options.format ?? cfg.format ?? null
+  if (format && !VALID_FORMATS.has(format.toLowerCase())) {
+    logger.error(`Invalid --format '${format}'. Valid: ${[...VALID_FORMATS].join(', ')}`)
+    process.exit(1)
+  }
+
+  const source = resolveSource(cliSource, projectRoot)
+  if (!source) {
+    printMissingSourceHelp(projectRoot)
+    process.exit(1)
+  }
+
+  try {
+    await runImages({
+      source,
+      projectRoot,
+      androidOnly: Boolean(options.android),
+      iphoneOnly: Boolean(options.ios),
+      format: format ? format.toLowerCase() : null,
+      quality: options.quality ?? cfg.quality ?? 85,
+      dryRun: Boolean(options.dryRun),
+      yes: Boolean(options.yes),
+      confirmOverwrites: cfg.confirmOverwrites !== false
+    })
+  } catch (err) {
+    logger.error(err.message)
+    if (options.debug) console.error(err.stack)
+    process.exit(1)
+  }
+}
+
+function loadImagesSection() {
+  try {
+    const cfg = getConfigFile()
+    if (cfg && typeof cfg.images === 'object') return cfg.images
+  } catch {}
+  return {}
+}
+
+function resolveSource(cliSource, projectRoot) {
+  const imagesFolder = projectRoot === process.cwd()
+    ? projectsPurge_TSS_Images_Folder
+    : path.join(projectRoot, 'purgetss', 'images')
+
+  if (cliSource) {
+    if (path.isAbsolute(cliSource)) {
+      return fs.existsSync(cliSource) ? cliSource : null
+    }
+    // Relative paths: try purgetss/images/ first (convention), then cwd.
+    // Lets users write short paths like `background/pink.png` without the prefix.
+    const insideImages = path.resolve(imagesFolder, cliSource)
+    if (fs.existsSync(insideImages)) return insideImages
+
+    const cwdResolved = path.resolve(projectRoot, cliSource)
+    if (fs.existsSync(cwdResolved)) return cwdResolved
+
+    return null
+  }
+  return fs.existsSync(imagesFolder) ? imagesFolder : null
+}
+
+function printMissingSourceHelp(projectRoot) {
+  const rel = (p) => path.relative(projectRoot, p) || '.'
+  const imagesDir = path.join(projectRoot, 'purgetss', 'images')
+
+  logger.error('No source images found.')
+  console.log()
+  console.log(`  Expected images inside ${chalk.cyan(rel(imagesDir) + '/')}.`)
+  console.log(`  The folder already exists — drop your images into it (subdirectories are preserved):`)
+  console.log(`     ${chalk.cyan('cp my-ui-asset.png ' + rel(imagesDir) + '/')}`)
+  console.log()
+  console.log('  Alternatives:')
+  console.log(`    ${chalk.gray('•')} Pass a file or directory explicitly:`)
+  console.log(`       ${chalk.cyan('purgetss images ./docs/screenshots')}`)
+  console.log(`       ${chalk.cyan('purgetss images ./logo.png')}`)
+  console.log()
+}

package/src/cli/commands/init.js

@@ -21,6 +21,8 @@ import {
   projectsAlloyJMKFile,
   projectsPurgeTSSFolder,
   projectsPurge_TSS_Fonts_Folder,
+  projectsPurge_TSS_Brand_Folder,
+  projectsPurge_TSS_Images_Folder,
   srcConfigFile,
   projectsFA_TSS_File,
   srcFontAwesomeTSSFile,
@@ -70,6 +72,8 @@ export function createConfigFile() {
   if (alloyProject()) {
     makeSureFolderExists(projectsPurgeTSSFolder)
     makeSureFolderExists(projectsPurge_TSS_Fonts_Folder)
+    makeSureFolderExists(projectsPurge_TSS_Brand_Folder)
+    makeSureFolderExists(projectsPurge_TSS_Images_Folder)
 
     if (fs.existsSync(projectsConfigJS)) {
       logger.warn('./purgetss/config.cjs', chalk.red('file already exists!'))

package/src/cli/commands/module.js

@@ -41,8 +41,10 @@ export function copyModulesLibrary() {
     return true
   } else {
     // Not in a valid project
-    logger.info(`Please make sure you are running ${chalk.green('purgetss')} within an Alloy or Classic Project.`)
-    logger.info(`For more information, visit ${chalk.green('https://purgetss.com')}`)
+    logger.block(
+      `Please make sure you are running ${chalk.green('purgetss')} within an Alloy or Classic Project.`,
+      `For more information, visit ${chalk.green('https://purgetss.com')}`
+    )
     return false
   }
 }

package/src/cli/commands/purge.js

@@ -31,6 +31,7 @@ import { init } from './init.js'
 import { getConfigOptions, getConfigFile, ensureConfig } from '../../shared/config-manager.js'
 
 // Import purger functions from core modules
+import { processControllers } from '../../core/analyzers/class-extractor.js'
 import { purgeTailwind } from '../../core/purger/tailwind-purger.js'
 import {
   purgeFontAwesome,
@@ -385,12 +386,16 @@ function throwPreValidationError({ relativePath, lineNumber, lineContent, messag
   error.lineNumber = lineNumber
   error.lineContent = lineContent
 
-  logger.error('XML Syntax Error\n')
-  logger.info(`File: "${relativePath}"`)
-  logger.info(`Line: ${lineNumber}`)
-  logger.info(`Content: "${lineContent}"\n`)
-  logger.error(message)
-  logger.info(chalk.green(`Fix: ${fix}\n`))
+  logger.block(
+    chalk.red('XML Syntax Error'),
+    `File: ${chalk.yellow(`"${relativePath}"`)}`,
+    `Line: ${chalk.yellow(lineNumber)}`,
+    `Content: ${chalk.yellow(`"${lineContent}"`)}`,
+    '',
+    chalk.red(message),
+    '',
+    `${chalk.green('Fix:')} ${fix}`
+  )
 
   throw error
 }
@@ -412,69 +417,6 @@ function extractClasses(currentText, currentFile) {
   }
 }
 
-/**
- * Process controller files for classes
- * COPIED exactly from original processControllers() function
- */
-function processControllers(data) {
-  const allWords = []
-  const lines = data.split(/\r?\n/)
-
-  lines.forEach(line => {
-    const words = extractWordsFromLine(line)
-    if (words.length > 0) {
-      allWords.push(...words)
-    }
-  })
-
-  return allWords
-}
-
-/**
- * Extract words from a line of controller code
- * COPIED exactly from original extractWordsFromLine() function
- */
-function extractWordsFromLine(line) {
-  const patterns = [
-    {
-      // apply: 'classes'
-      regex: /apply:\s*'([^']+)'/,
-      process: match => match[1].split(/\s+/)
-    },
-    {
-      // classes: ['class1', 'class2'] o classes: ['class1 class2']
-      regex: /classes:\s*\[([^\]]+)\]/,
-      process: match => match[1].split(',').map(item => item.trim().replace(/['"]/g, ''))
-    },
-    {
-      // classes: 'class1 class2'
-      regex: /classes:\s*'([^']+)'/,
-      process: match => match[1].split(/\s+/)
-    }
-  ]
-
-  // Process simple patterns
-  const words = patterns.reduce((acc, { regex, process }) => {
-    const match = regex.exec(line)
-    return match ? [...acc, ...process(match)] : acc
-  }, [])
-
-  // Process addClass, removeClass, resetClass
-  const classFunctionRegex = /(?:\.\w+Class|resetClass)\([^,]+,\s*(?:'([^']+)'|\[([^\]]+)\])/g
-  let classFunctionMatch
-  while ((classFunctionMatch = classFunctionRegex.exec(line)) !== null) {
-    const content = classFunctionMatch[1] || classFunctionMatch[2]
-    if (content) {
-      const classes = content.includes(',')
-        ? content.split(',').map(item => item.trim().replace(/['"]/g, ''))
-        : content.replace(/['"]/g, '').split(/\s+/)
-      words.push(...classes)
-    }
-  }
-
-  return words
-}
-
 /**
  * Filter invalid characters from class names
  * COPIED exactly from original filterCharacters() function
@@ -737,49 +679,57 @@ export function purgeClasses(options) {
 
   if (Date.now() > (fs.statSync(projectsAppTSS).mtimeMs + 2000) || recentlyCreated) {
     start()
-
-    init(options)
-
-    backupOriginalAppTss()
-
-    let uniqueClasses
-
+    logger.startSection()
     try {
-      uniqueClasses = getUniqueClasses()
-    } catch (error) {
-      // Handle pre-validation errors (XML syntax errors detected before parsing)
-      if (error.isPreValidationError) {
-        // Error already printed by preValidateXML, exit cleanly
-        // eslint-disable-next-line n/no-process-exit
-        process.exit(1)
+      // Explicit header so every purge run shows which project is being
+      // processed — mirrors the Auto-Purging line emitted by the alloy.jmk hook.
+      logger.info('Purging', chalk.yellow(cwd))
+
+      init(options)
+
+      backupOriginalAppTss()
+
+      let uniqueClasses
+
+      try {
+        uniqueClasses = getUniqueClasses()
+      } catch (error) {
+        // Handle pre-validation errors (XML syntax errors detected before parsing)
+        if (error.isPreValidationError) {
+          // Error already printed by preValidateXML, exit cleanly
+          // eslint-disable-next-line n/no-process-exit
+          process.exit(1)
+        }
+        // Re-throw other errors
+        throw error
       }
-      // Re-throw other errors
-      throw error
-    }
 
-    let tempPurged = copyResetTemplateAnd_appTSS()
+      let tempPurged = copyResetTemplateAnd_appTSS()
 
-    tempPurged += purgeTailwind(uniqueClasses, purgingDebug)
+      tempPurged += purgeTailwind(uniqueClasses, purgingDebug)
 
-    const cleanUniqueClasses = cleanClasses(uniqueClasses)
+      const cleanUniqueClasses = cleanClasses(uniqueClasses)
 
-    tempPurged += purgeFontAwesome(uniqueClasses, cleanUniqueClasses, purgingDebug)
+      tempPurged += purgeFontAwesome(uniqueClasses, cleanUniqueClasses, purgingDebug)
 
-    tempPurged += purgeMaterialIcons(uniqueClasses, cleanUniqueClasses, purgingDebug)
+      tempPurged += purgeMaterialIcons(uniqueClasses, cleanUniqueClasses, purgingDebug)
 
-    tempPurged += purgeMaterialSymbols(uniqueClasses, cleanUniqueClasses, purgingDebug)
+      tempPurged += purgeMaterialSymbols(uniqueClasses, cleanUniqueClasses, purgingDebug)
 
-    tempPurged += purgeFramework7(uniqueClasses, cleanUniqueClasses, purgingDebug)
+      tempPurged += purgeFramework7(uniqueClasses, cleanUniqueClasses, purgingDebug)
 
-    tempPurged += purgeFonts(uniqueClasses, cleanUniqueClasses, purgingDebug)
+      tempPurged += purgeFonts(uniqueClasses, cleanUniqueClasses, purgingDebug)
 
-    tempPurged += processMissingClasses(tempPurged)
+      tempPurged += processMissingClasses(tempPurged)
 
-    saveFile(projectsAppTSS, tempPurged)
+      saveFile(projectsAppTSS, tempPurged)
 
-    logger.file('app.tss')
+      logger.file('app.tss')
 
-    finish()
+      finish()
+    } finally {
+      logger.endSection()
+    }
 
     return true
   } else {

package/src/cli/commands/semantic.js

@@ -0,0 +1,180 @@
+/**
+ * PurgeTSS - `semantic` command
+ *
+ * Generates Titanium semantic colors (app/assets/semantic.colors.json) in two
+ * modes, dispatched by --single:
+ *
+ *   Palette mode (no --single):
+ *     One base hex → 11-step tonal palette with mirror-by-index Light/Dark
+ *     inversion (anchored at shade 500). Writes JSON + config mapping (the
+ *     11 shade keys are mechanically derived from the family name, so the
+ *     class mapping is unambiguous).
+ *
+ *   Single mode (--single):
+ *     Explicit light + optional dark + optional alpha → one purpose-based
+ *     semantic color. Writes JSON ONLY. The class name mapping in config.cjs
+ *     is a design-layer decision (designers pick `bg-surface` to point at
+ *     `surfaceColor`, `text-on-surface` to point at `textColor`, etc.) and
+ *     should not be auto-derived from the semantic key. The command tells
+ *     the user how to add the mapping.
+ *
+ *     If the name matches an existing palette shade (e.g. `amazon50` while
+ *     palette `amazon` exists), the operation narrows to an in-place JSON
+ *     value edit — no new top-level entry, no config touch.
+ *
+ * @author César Estrada
+ */
+
+import chalk from 'chalk'
+import { alloyProject } from '../../shared/utils.js'
+import { logger } from '../../shared/logger.js'
+import { ensureConfig, getConfigFile } from '../../shared/config-manager.js'
+import {
+  toCamelCase,
+  buildSemanticPalette,
+  buildSingleSemantic,
+  writeSemanticColors,
+  writeSemanticJSON,
+  writeConfigMapping,
+  updateSemanticEntry,
+  wrapHexWithAlpha,
+  detectFamilyShadeConflict,
+  normalizeAlpha,
+  checkIfColorModule,
+  missingHexMessage
+} from './shades.js'
+
+/**
+ * Normalize a user-supplied name into both kebab and camel forms while
+ * preserving the user's case. Handles three input shapes:
+ *   - camelCase ('surfaceColor')   → { kebab: 'surface-color', camel: 'surfaceColor' }
+ *   - kebab     ('surface-color')  → { kebab: 'surface-color', camel: 'surfaceColor' }
+ *   - natural   ('Surface Color')  → { kebab: 'surface-color', camel: 'surfaceColor' }
+ */
+function parseName(raw) {
+  const clean = String(raw).replace(/'/g, '').replace(/\//g, '').trim()
+  if (/\s/.test(clean)) {
+    const kebab = clean.toLowerCase().split(/\s+/).join('-')
+    return { kebab, camel: toCamelCase(kebab) }
+  }
+  if (clean.includes('-')) {
+    const kebab = clean.toLowerCase()
+    return { kebab, camel: toCamelCase(kebab) }
+  }
+  // No space, no hyphen: treat as camelCase or single word, preserve case
+  const camel = clean
+  const kebab = camel.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+  return { kebab, camel }
+}
+
+export async function semantic(args, options) {
+  const silent = options.log
+
+  if (options.single) {
+    return runSingle(args, options, silent)
+  }
+
+  return runPalette(args, options, silent)
+}
+
+async function runPalette(args, options, silent) {
+  if (!args.hexcode && !options.random) {
+    logger.block(...missingHexMessage('semantic'))
+    return false
+  }
+
+  const chroma = (await import('chroma-js')).default
+  const referenceColorFamilies = (await import('../../../lib/color-shades/tailwindColors.js')).default
+  const generateColorShades = (await import('../../../lib/color-shades/generateColorShades.js')).default
+
+  const colorFamily = options.random
+    ? generateColorShades(chroma.random(), referenceColorFamilies)
+    : generateColorShades(args.hexcode, referenceColorFamilies)
+
+  if (args.name) colorFamily.name = args.name
+  else if (options.name) colorFamily.name = options.name
+
+  colorFamily.name = colorFamily.name.replace(/'/g, '').replace(/\//g, '').replace(/\s+/g, ' ')
+
+  const { kebab: kebabName } = parseName(colorFamily.name)
+  const { semanticEntries, configMapping } = buildSemanticPalette(colorFamily, kebabName)
+
+  if (alloyProject(silent) && !silent) {
+    ensureConfig()
+    writeSemanticColors(semanticEntries, kebabName, configMapping, options)
+    logger.info(`${chalk.hex(colorFamily.hexcode).bold(`"${colorFamily.name}"`)} palette (11 shades) saved to`, chalk.yellow('app/assets/semantic.colors.json'))
+  } else {
+    logger.info(`${chalk.hex(colorFamily.hexcode).bold(`"${colorFamily.name}"`)} palette preview:\n${JSON.stringify(semanticEntries, null, 2)}`)
+  }
+
+  return true
+}
+
+function runSingle(args, options, silent) {
+  const lightHex = args.hexcode
+  const rawName = args.name || options.name
+  if (!lightHex) {
+    logger.info(`${chalk.red('Missing light hex.')} Usage: ${chalk.green("pt semantic --single '#F9FAFB' surfaceColor [--dark '#0f172a'] [--alpha 50]")}`)
+    return false
+  }
+  if (!rawName) {
+    logger.info(`${chalk.red('Missing name.')} Usage: ${chalk.green("pt semantic --single '#F9FAFB' surfaceColor [--dark '#0f172a'] [--alpha 50]")}`)
+    return false
+  }
+
+  const darkHex = options.dark || lightHex
+  const alpha = normalizeAlpha(options.alpha)
+  const { kebab: kebabName, camel: camelName } = parseName(rawName)
+
+  // Preview mode: log the JSON, no writes, no Alloy check
+  if (silent) {
+    const { semanticEntries } = buildSingleSemantic(camelName, lightHex, darkHex, alpha)
+    logger.info(`${chalk.hex(lightHex).bold(`"${camelName}"`)} preview:\n${JSON.stringify(semanticEntries, null, 2)}`)
+    return true
+  }
+
+  if (!alloyProject(silent)) return false
+  ensureConfig()
+
+  // If the name matches an existing palette shade (e.g. `amazon50` when palette
+  // `amazon` is already declared), interpret as an in-place value edit. Update
+  // the JSON entry, leave config.cjs alone (palette already maps to this key).
+  const conflict = detectFamilyShadeConflict(getConfigFile(), kebabName, camelName)
+  if (conflict) {
+    const value = {
+      light: wrapHexWithAlpha(lightHex, alpha),
+      dark: wrapHexWithAlpha(darkHex, alpha)
+    }
+    updateSemanticEntry(conflict.camelKey, value)
+    checkIfColorModule()
+    logger.info(`${chalk.hex(lightHex).bold(conflict.camelKey)} updated in ${chalk.yellow('app/assets/semantic.colors.json')} — palette ${chalk.yellow(conflict.parentName)} already references this key, config.cjs left unchanged.`)
+    return true
+  }
+
+  // Fresh single entry: write JSON + auto-map config.cjs to a sensible class name.
+  // Convention: strip the trailing 'Color' suffix (Titanium's semantic naming
+  // pattern) and kebab-case the rest. Users who want a different class name
+  // (`on-surface` for `textColor`, etc.) edit config.cjs after the fact —
+  // overriding the auto-mapping is one keystroke; typing it from scratch is many.
+  const { semanticEntries } = buildSingleSemantic(camelName, lightHex, darkHex, alpha)
+  const className = suggestClassName(camelName)
+  writeSemanticJSON(semanticEntries, camelName)
+  writeConfigMapping(className, camelName, options)
+  logger.info(`${chalk.hex(lightHex).bold(`"${camelName}"`)} saved to ${chalk.yellow('app/assets/semantic.colors.json')} and mapped to class ${chalk.green(className)} in ${chalk.yellow('config.cjs')}.`)
+  return true
+}
+
+/**
+ * Derive a class name from a Titanium semantic key by stripping the
+ * conventional `Color` suffix and kebab-casing the result.
+ *   'surfaceColor'      → 'surface'
+ *   'surfaceHighColor'  → 'surface-high'
+ *   'borderColor'       → 'border'
+ *   'overlay'           → 'overlay'  (no Color suffix → unchanged)
+ */
+function suggestClassName(camelKey) {
+  const stripped = camelKey.replace(/Color$/, '') || camelKey
+  return stripped.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+export default { semantic }