purgetss 7.7.1 → 7.9.0

package/README.md

@@ -377,6 +377,14 @@ Button: {
 
 ## Recent changes
 
+### v7.8.0
+
+- **`--width <n>` flag for `images`.** Pin Android `mdpi` / iPhone `@1x` to a specific width in pixels (e.g. `purgetss images logo.svg --width 256`); larger scales derive at ×1.5, ×2, ×3, ×4 with height staying proportional. Recommended when the source is an SVG export from Affinity / Illustrator with a disproportionate viewBox — the legacy 4× master convention produces unpredictable sizes there, and the new flag pins the result exactly. When you pass an SVG without `--width`, `images` now prints a one-time hint suggesting the flag, then falls back to the legacy behavior.
+- **Class syntax pre-validation.** `purgetss` now halts with a structured `Class Syntax Error` block (file + line + suggested fix) when it detects known authoring mistakes in your class names: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind-style brackets (`top-[10px]` → `top-(10px)`), empty parentheses (`wh-()`), whitespace inside parentheses (`wh-( 200 )`), and redundant `px` unit (`top-(10px)` → `top-(10)`).
+- All offenders are reported in a single run, so you can fix them in one pass.
+- Generic unknown classes (typos, vendor utilities not enabled, custom classes not yet declared) are NOT flagged by the validator — they continue to flow silently into the `// Unused or unsupported classes` block in `app.tss`, exactly as in previous versions.
+- **Arbitrary-value parser no longer crashes on negative values inside parentheses.** Classes like `top-(-10)`, `mt-(-5)`, or `origin-(-10,-20)` used to trigger a `Cannot read properties of null (reading 'pop')` exception. The parser was rewritten to extract the `(...)` portion first, so a `-` inside the value never breaks the split — and the new pre-validator catches the inverted-sign form before it gets that far.
+
 ### v7.7.0
 
 - `brand` now uses grouped config sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, and `brand.colors`.

package/bin/purgetss

@@ -353,6 +353,13 @@ Writes directly to the project (auto-detects Alloy vs Classic):
 Defaults come from the ${chalk.cyan('images:')} section in ${chalk.cyan('purgetss/config.cjs')}.
 CLI flags always win over config values.
 
+Sizing:
+  By default, sources are treated as 4× masters (xxxhdpi/@4x); all other
+  scales derive at 1/4, 1.5/4, 2/4, 3/4 of the source's natural pixels.
+  Pass ${chalk.cyan('--width <n>')} to pin Android mdpi (= iPhone @1x) to a specific width;
+  larger scales derive as ×1.5, ×2, ×3, ×4 (height stays proportional).
+  Recommended for SVGs from vector editors with oversized viewBoxes.
+
 Examples:
   ${chalk.cyan('purgetss images')}                                  # uses purgetss/images/ + config
   ${chalk.cyan('purgetss images')} ./docs/screenshots               # scope to one folder
@@ -361,12 +368,15 @@ Examples:
   ${chalk.cyan('purgetss images')} --ios                            # iPhone scales only
   ${chalk.cyan('purgetss images')} --format webp                    # convert all outputs to WebP
   ${chalk.cyan('purgetss images')} --format png --quality 95
+  ${chalk.cyan('purgetss images')} logo.svg --width 256             # pin @1x/mdpi to 256 px wide
+  ${chalk.cyan('purgetss images')} banner.svg --width 512 --format webp
   ${chalk.cyan('purgetss images')} --dry-run
 `)
   .option('--android', 'Generate only Android density variants (skip iPhone)')
   .option('--ios', 'Generate only iPhone scale variants (skip Android)')
   .option('--format <ext>', 'Convert all outputs to this format: webp|jpeg|png|avif|gif|tiff')
   .option('--quality <n>', 'JPEG/WebP/AVIF quality 0-100 (default: 85)', (v) => parseInt(v, 10))
+  .option('--width <n>', 'Target width in px for @1x/mdpi (other scales derive: ×1.5, ×2, ×3, ×4)', (v) => parseInt(v, 10))
   .option('--project <path>', 'Project root (default: cwd)')
   .option('--dry-run', 'Preview without writing any files')
   .option('-y, --yes', 'Skip the overwrite confirmation prompt')

package/dist/purgetss.ui.js

@@ -1,4 +1,4 @@
-// PurgeTSS v7.7.1
+// PurgeTSS v7.8.0
 // Created by César Estrada
 // https://purgetss.com
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "purgetss",
-  "version": "7.7.1",
+  "version": "7.9.0",
   "main": "src/index.js",
   "bin": {
     "purgetss": "bin/purgetss"
@@ -17,7 +17,7 @@
     "dist/*.tss",
     "dist/configs/",
     "assets/fonts/",
-    "experimental/completions2.js"
+    "src/core/builders/auto-utilities-builder.js"
   ],
   "publishConfig": {
     "access": "public"

package/src/cli/commands/build.js

@@ -14,6 +14,7 @@ import { alloyProject } from '../../shared/utils.js'
 import { ensureConfig } from '../../shared/config-manager.js'
 import { buildTailwindBasedOnConfigOptions } from '../../core/builders/tailwind-builder.js'
 import { createDefinitionsFile } from './init.js'
+import { flushSemanticColors } from '../../shared/semantic-helpers.js'
 
 // Import FontAwesome functions from their new modular location
 import { buildFontAwesome, buildFontAwesomeJS } from '../../dev/builders/fontawesome-builder.js'
@@ -28,10 +29,14 @@ import { buildFontAwesome, buildFontAwesomeJS } from '../../dev/builders/fontawe
 export function build(options) {
   if (alloyProject()) {
     ensureConfig()
-    buildTailwindBasedOnConfigOptions(options)
-    buildFontAwesome()
-    buildFontAwesomeJS()
-    createDefinitionsFile()
+    try {
+      buildTailwindBasedOnConfigOptions(options)
+      buildFontAwesome()
+      buildFontAwesomeJS()
+      createDefinitionsFile()
+    } finally {
+      flushSemanticColors()
+    }
     return true
   }
   return false

package/src/cli/commands/images.js

@@ -37,6 +37,13 @@ export async function images(cliSource, options = {}) {
     process.exit(1)
   }
 
+  if (options.width !== undefined) {
+    if (!Number.isFinite(options.width) || !Number.isInteger(options.width) || options.width < 1 || options.width > 8192) {
+      logger.error(`Invalid --width '${options.width}'. Must be an integer between 1 and 8192.`)
+      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(', ')}`)
@@ -57,6 +64,7 @@ export async function images(cliSource, options = {}) {
       iphoneOnly: Boolean(options.ios),
       format: format ? format.toLowerCase() : null,
       quality: options.quality ?? cfg.quality ?? 85,
+      baseWidth: options.width ?? null,
       dryRun: Boolean(options.dryRun),
       yes: Boolean(options.yes),
       confirmOverwrites: cfg.confirmOverwrites !== false

package/src/cli/commands/purge.js

@@ -33,6 +33,7 @@ import { getConfigOptions, getConfigFile, ensureConfig } from '../../shared/conf
 // Import purger functions from core modules
 import { processControllers } from '../../core/analyzers/class-extractor.js'
 import { purgeTailwind } from '../../core/purger/tailwind-purger.js'
+import { flushSemanticColors } from '../../shared/semantic-helpers.js'
 import {
   purgeFontAwesome,
   purgeMaterialIcons,
@@ -40,6 +41,7 @@ import {
   purgeFramework7
 } from '../../core/purger/icon-purger.js'
 import { purgeFonts } from '../../core/purger/fonts-purger.js'
+import { validateClassSyntax } from '../utils/unsupported-class-reporter.js'
 
 // Global variables (EXACT copies from original src/index.js)
 let configOptions = {}
@@ -693,10 +695,21 @@ export function purgeClasses(options) {
 
       try {
         uniqueClasses = getUniqueClasses()
+
+        // Pre-validate class syntax. Halts on inverted negatives, Tailwind
+        // brackets, empty parens, etc. — but NOT on generic unknown classes
+        // (those fall through silently to "// Unused or unsupported classes").
+        validateClassSyntax({
+          classes: uniqueClasses,
+          viewPaths: getViewPaths(),
+          controllerPaths: getControllerPaths()
+        })
       } catch (error) {
-        // Handle pre-validation errors (XML syntax errors detected before parsing)
-        if (error.isPreValidationError) {
-          // Error already printed by preValidateXML, exit cleanly
+        // Handle pre-validation errors (XML syntax errors detected before
+        // parsing) and class-syntax errors (authoring mistakes detected
+        // before purging). In both cases the error block was already
+        // printed; just exit cleanly.
+        if (error.isPreValidationError || error.isClassSyntaxError) {
           // eslint-disable-next-line n/no-process-exit
           process.exit(1)
         }
@@ -728,6 +741,7 @@ export function purgeClasses(options) {
 
       finish()
     } finally {
+      flushSemanticColors()
       logger.endSection()
     }
 

package/src/cli/commands/shades.js

@@ -329,8 +329,8 @@ export function buildSemanticPalette(family, kebabName, alpha) {
     const mirror = sorted[sorted.length - 1 - i]
     const key = `${camelName}${shade.number}`
     semanticEntries[key] = {
-      light: wrapValue(mirror.hexcode, alpha),
-      dark: wrapValue(shade.hexcode, alpha)
+      light: wrapValue(shade.hexcode, alpha),
+      dark: wrapValue(mirror.hexcode, alpha)
     }
     configMapping[shade.number] = key
   })

package/src/cli/utils/unsupported-class-reporter.js

@@ -0,0 +1,209 @@
+/**
+ * PurgeTSS - Class Syntax Validator
+ *
+ * Pre-validation helper that runs BEFORE the purge starts. Scans every unique
+ * class name pulled from XML views (and JS controllers) for well-known
+ * authoring mistakes:
+ *
+ *   - Inverted negative sign:  top-(-10)   → -top-(10)
+ *   - Tailwind-style brackets: top-[10px]  → top-(10px)
+ *   - Empty parentheses:       wh-()       → wh-(<value>)
+ *   - Whitespace in parens:    wh-( 200 )  → wh-(200)
+ *   - Redundant px units:      top-(10px)  → top-(10)
+ *
+ * On any match the validator collects every offender, prints one block per
+ * offender (file + line + fix, mirroring throwPreValidationError) and throws
+ * an `isClassSyntaxError` so the CLI exits cleanly without running the purge.
+ *
+ * Generic unknown classes (typos, vendor utilities not enabled, custom
+ * classes not yet defined) are intentionally left alone — they are still
+ * captured silently in the "// Unused or unsupported classes" section of
+ * app.tss, but never trigger warnings or halts. That's the only way to keep
+ * the workflow usable on projects with dozens of in-progress class names.
+ *
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import chalk from 'chalk'
+import { logger } from '../../shared/logger.js'
+
+const cwd = process.cwd()
+
+/**
+ * Pattern detectors. Each detector receives the className and returns
+ * { issue, suggestion } when it recognises the problem, or null otherwise.
+ * Order matters: more specific detectors first.
+ */
+const detectors = [
+  // top-(-10) → -top-(10)
+  function detectInvertedNegative(className) {
+    const m = className.match(/^([a-zA-Z][\w-]*?)-\(-([^()]+)\)$/)
+    if (!m) return null
+    return {
+      issue: 'Negative sign is inside the parentheses',
+      suggestion: `Use ${chalk.green(`"-${m[1]}-(${m[2]})"`)} — PurgeTSS expects the "-" prefix BEFORE the rule, not inside the value`
+    }
+  },
+
+  // top-[10px] → top-(10)
+  function detectTailwindBrackets(className) {
+    if (!className.includes('[') && !className.includes(']')) return null
+    const fixed = className.replace(/\[/g, '(').replace(/\]/g, ')')
+    return {
+      issue: 'Tailwind-style brackets "[ ]" are not supported',
+      suggestion: `Use parentheses instead: ${chalk.green(`"${fixed}"`)}`
+    }
+  },
+
+  // wh-() → "Add a value"
+  function detectEmptyParens(className) {
+    const m = className.match(/^([\w-]+)-\(\s*\)$/)
+    if (!m) return null
+    return {
+      issue: 'Empty value inside parentheses',
+      suggestion: `Add a value, e.g. ${chalk.green(`"${m[1]}-(10)"`)}`
+    }
+  },
+
+  // wh-( 200 ) → wh-(200)
+  function detectSpacesInParens(className) {
+    const m = className.match(/^([\w-]+)-\(\s+([^()]*?)\s*\)$|^([\w-]+)-\(([^()]*?)\s+\)$/)
+    if (!m) return null
+    const rule = m[1] || m[3]
+    const value = (m[2] || m[4] || '').trim()
+    if (!value) return null
+    return {
+      issue: 'Whitespace inside parentheses',
+      suggestion: `Remove the spaces: ${chalk.green(`"${rule}-(${value})"`)}`
+    }
+  },
+
+  // top-(10px) — units inside parens that PurgeTSS would strip anyway.
+  // Only flag when value is purely numeric+unit; never blanket-flag because
+  // some properties (durations, percentages) accept units.
+  function detectRedundantUnits(className) {
+    const m = className.match(/^([\w-]+)-\((-?\d+(?:\.\d+)?)px\)$/)
+    if (!m) return null
+    return {
+      issue: 'Explicit "px" unit is redundant',
+      suggestion: `PurgeTSS treats unit-less values as pixels: ${chalk.green(`"${m[1]}-(${m[2]})"`)}`
+    }
+  }
+]
+
+function detectIssue(className) {
+  for (const detector of detectors) {
+    const result = detector(className)
+    if (result) return result
+  }
+  return null
+}
+
+/**
+ * Find every (file, line) where `className` appears as a whole token inside a
+ * class="..." attribute. Uses an attribute-then-split strategy (rather than
+ * matching the class name directly) so arbitrary-value class names like
+ * "top-(-10)" — which contain regex-special characters — do not need escaping
+ * and cannot false-match a partial substring.
+ */
+function findLocations(className, paths) {
+  const locations = []
+  const attrRe = /class\s*=\s*["']([^"']*)["']/g
+
+  for (const filePath of paths) {
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch {
+      continue
+    }
+    const lines = content.split(/\r?\n/)
+    for (let i = 0; i < lines.length; i++) {
+      attrRe.lastIndex = 0
+      let match
+      while ((match = attrRe.exec(lines[i])) !== null) {
+        const tokens = match[1].split(/\s+/).filter(Boolean)
+        if (tokens.includes(className)) {
+          locations.push({
+            filePath,
+            lineNumber: i + 1,
+            lineContent: lines[i].trim()
+          })
+          break
+        }
+      }
+    }
+  }
+  return locations
+}
+
+function relativePath(filePath) {
+  return filePath.startsWith(cwd + '/') ? filePath.slice(cwd.length + 1) : filePath
+}
+
+/**
+ * Pre-validate every unique class against the syntax detectors. Collects all
+ * offenders (so the dev sees the full list in a single run instead of
+ * one-fix-per-attempt), prints a block per offender, then throws.
+ *
+ * Generic unknown classes are NOT flagged — they fall through silently to
+ * the "// Unused or unsupported classes" comment block in app.tss.
+ *
+ * @param {Object} args
+ * @param {string[]} args.classes           Unique classes pulled from views/controllers.
+ * @param {string[]} args.viewPaths         Absolute paths to XML view files.
+ * @param {string[]} [args.controllerPaths] Absolute paths to JS controller files.
+ * @throws {Error} with `isClassSyntaxError === true` if any class matches a detector.
+ */
+export function validateClassSyntax({ classes, viewPaths, controllerPaths = [] }) {
+  if (!classes || classes.length === 0) return
+
+  const allPaths = [...viewPaths, ...controllerPaths]
+  const offenders = []
+
+  for (const className of classes) {
+    const issue = detectIssue(className)
+    if (!issue) continue
+    offenders.push({
+      className,
+      issue,
+      locations: findLocations(className, allPaths)
+    })
+  }
+
+  if (offenders.length === 0) return
+
+  for (const offender of offenders) {
+    const lines = []
+    lines.push(`Class: ${chalk.yellow(`"${offender.className}"`)}`)
+
+    if (offender.locations.length > 0) {
+      const first = offender.locations[0]
+      lines.push(`File: ${chalk.yellow(`"${relativePath(first.filePath)}"`)}`)
+      lines.push(`Line: ${chalk.yellow(first.lineNumber)}`)
+      lines.push(`Content: ${chalk.gray(first.lineContent)}`)
+      if (offender.locations.length > 1) {
+        const more = offender.locations.length - 1
+        lines.push(chalk.gray(`(also used in ${more} other location${more === 1 ? '' : 's'})`))
+      }
+    } else {
+      lines.push(chalk.gray('Location: not found in views — likely from a controller or safelist'))
+    }
+
+    lines.push('')
+    lines.push(chalk.red(`Issue: ${offender.issue.issue}`))
+    lines.push(`${chalk.green('Fix:')} ${offender.issue.suggestion}`)
+
+    logger.block(chalk.red('Class Syntax Error'), ...lines)
+  }
+
+  const word = offenders.length === 1 ? 'class syntax error' : 'class syntax errors'
+  logger.block(
+    chalk.red(`Found ${offenders.length} ${word} — fix the ${offenders.length === 1 ? 'class' : 'classes'} above and re-run purgetss`)
+  )
+
+  const error = new Error('Class syntax errors detected')
+  error.isClassSyntaxError = true
+  throw error
+}

package/{experimental/completions2.js → src/core/builders/auto-utilities-builder.js}

@@ -7,28 +7,21 @@ import path from 'path'
 import { fileURLToPath } from 'url'
 import { createRequire } from 'module'
 import _ from 'lodash'
-import chalk from 'chalk'
 let saveGlossary = false
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 const require = createRequire(import.meta.url)
 const cwd = process.cwd()
-import { colores } from '../src/shared/brand-colors.js'
+import { colores } from '../../shared/brand-colors.js'
 export { colores }
-const purgeLabel = colores.purgeLabel
 
-import * as helpers from '../src/shared/helpers.js'
-import { getConfigFile } from '../src/shared/config-manager.js'
-import { projectsConfigJS } from '../src/shared/constants.js'
-const tiCompletionsFile = require('../lib/completions/titanium/completions-v3.json')
-
-const logger = {
-  info: (...args) => console.log(purgeLabel, args.join(' ')),
-  warn: (...args) => console.log(purgeLabel, chalk.yellow(args.join(' '))),
-  error: (...args) => console.log(purgeLabel, chalk.red(args.join(' '))),
-  file: (...args) => console.log(purgeLabel, chalk.yellow(args.join(' ')), 'file created!')
-}
+import * as helpers from '../../shared/helpers.js'
+import { getConfigFile } from '../../shared/config-manager.js'
+import { projectsConfigJS } from '../../shared/constants.js'
+import { logger } from '../../shared/logger.js'
+import { registerSemanticName } from '../../shared/semantic-helpers.js'
+const tiCompletionsFile = require('../../../lib/completions/titanium/completions-v3.json')
 
 // Keys whose numeric values are interpreted with `ti.ui.defaultunit` from tiapp.xml.
 // The glossary .md files for these keys receive an inline "// Unit: ..." note
@@ -174,7 +167,7 @@ function buildSubfolderIndex(folder) {
 }
 
 function glossaryBaseFolder() {
-  if (!fs.existsSync(projectsConfigJS)) return path.resolve(__dirname, '../dist/glossary/')
+  if (!fs.existsSync(projectsConfigJS)) return path.resolve(__dirname, '../../../dist/glossary/')
   if (saveGlossary) return cwd + '/purgetss/glossary/'
   return ''
 }
@@ -236,7 +229,7 @@ function autoBuildUtilitiesTSS(options = {}) {
 
   saveGlossary = options.glossary ?? false
   scaffoldGlossary()
-  let tailwindStyles = fs.readFileSync(path.resolve(__dirname, '../lib/templates/tailwind/custom-template.tss'), 'utf8')
+  let tailwindStyles = fs.readFileSync(path.resolve(__dirname, '../../../lib/templates/tailwind/custom-template.tss'), 'utf8')
   tailwindStyles += (fs.existsSync(projectsConfigJS)) ? `// config.js file updated on: ${getFileUpdatedDate(projectsConfigJS)}\n` : '// default config.js file\n'
 
   const baseValues = combineDefaultThemeWithConfigFile()
@@ -255,7 +248,7 @@ function autoBuildUtilitiesTSS(options = {}) {
     saveFile(cwd + '/purgetss/styles/utilities.tss', tailwindStyles)
     logger.file('./purgetss/styles/utilities.tss')
   } else {
-    saveFile(path.resolve(__dirname, '../dist/utilities.tss'), tailwindStyles)
+    saveFile(path.resolve(__dirname, '../../../dist/utilities.tss'), tailwindStyles)
     logger.file('./dist/utilities.tss')
   }
 }
@@ -311,7 +304,7 @@ function processCompletionsClasses(_completionsWithBaseValues) {
 
 function generateGlossary(_key, _theClasses, _keyName = null) {
   let baseDestinationFolder = ''
-  if (!fs.existsSync(projectsConfigJS)) baseDestinationFolder = path.resolve(__dirname, '../dist/glossary/')
+  if (!fs.existsSync(projectsConfigJS)) baseDestinationFolder = path.resolve(__dirname, '../../../dist/glossary/')
   else if (saveGlossary) baseDestinationFolder = cwd + '/purgetss/glossary/'
 
   if (baseDestinationFolder !== '') {
@@ -378,7 +371,7 @@ function getTiUIComponents(_base) {
 
 function processCompoundClasses({ ..._base }) {
   let compoundClasses = ''
-  const compoundTemplate = require('../lib/templates/tailwind/compoundTemplate.json')
+  const compoundTemplate = require('../../../lib/templates/tailwind/compoundTemplate.json')
 
   _.each(compoundTemplate, (value, key) => {
     compoundClasses += generateGlossary(key, helpers.processProperties(value.description, value.template, value.base ?? { default: _base[key] }))
@@ -534,6 +527,11 @@ function combineDefaultThemeWithConfigFile() {
   }
 
   _.merge(base.colors, themeOrDefaultValues.colors, configFile.theme.extend.colors)
+  // Track semantic color names so opacity modifiers (bg-X/65) can later
+  // auto-derive an alpha-applied entry in semantic.colors.json. A value is
+  // "semantic" when it's a string that isn't a hex literal or a Ti reserved
+  // keyword.
+  _.each(base.colors, value => collectSemanticReferences(value))
   _.merge(base.size, themeOrDefaultValues.spacing, configFile.theme.extend.spacing)
   _.merge(base.spacing, themeOrDefaultValues.spacing, configFile.theme.extend.spacing)
 
@@ -572,8 +570,16 @@ function combineDefaultThemeWithConfigFile() {
   delete base.zIndex.auto
 
   // ! Process custom Window, View and ImageView
-  // Merge extend values into theme (same as colors, spacing, etc.)
+  // Track whether the user defined each Ti Element at the theme.X (replace) level
+  // BEFORE merging extend into theme. This mirrors the Tailwind convention:
+  //   theme.X         → REPLACE the framework's defaults entirely
+  //   theme.extend.X  → MERGE with the framework's defaults
+  // Without this distinction, presets (like Window's backgroundColor: '#FFFFFF')
+  // leak into a strict-replace config and surface as ghost properties in app.tss.
+  const userReplaced = {}
   _.each(['Window', 'View', 'ImageView'], comp => {
+    userReplaced[comp] = !!configFile.theme[comp] && !configFile.theme.extend[comp]
+
     if (configFile.theme.extend[comp]) {
       configFile.theme[comp] = _.merge({}, configFile.theme[comp], configFile.theme.extend[comp])
       delete configFile.theme.extend[comp]
@@ -584,11 +590,18 @@ function combineDefaultThemeWithConfigFile() {
     }
   })
 
-  // Merge user config WITH defaults, then write back to configFile.theme
-  // so that getTiUIComponents/combineKeys picks up the full merged object
-  configFile.theme.Window = _.merge({ default: { backgroundColor: '#FFFFFF' } }, configFile.theme.Window)
-  configFile.theme.ImageView = _.merge({ ios: { hires: true } }, configFile.theme.ImageView)
-  configFile.theme.View = _.merge({ default: { width: 'Ti.UI.SIZE', height: 'Ti.UI.SIZE' } }, configFile.theme.View)
+  // Apply framework defaults only when NOT in strict-replace mode. In replace
+  // mode the user's config is the single source of truth — presets must not be
+  // silently re-injected.
+  if (!userReplaced.Window) {
+    configFile.theme.Window = _.merge({ default: { backgroundColor: '#FFFFFF' } }, configFile.theme.Window)
+  }
+  if (!userReplaced.ImageView) {
+    configFile.theme.ImageView = _.merge({ ios: { hires: true } }, configFile.theme.ImageView)
+  }
+  if (!userReplaced.View) {
+    configFile.theme.View = _.merge({ default: { width: 'Ti.UI.SIZE', height: 'Ti.UI.SIZE' } }, configFile.theme.View)
+  }
 
   base.Window = configFile.theme.Window
   base.ImageView = configFile.theme.ImageView
@@ -610,6 +623,22 @@ function checkDeletePlugins() {
   return Array.isArray(deletePlugins) ? deletePlugins : Object.keys(deletePlugins).map(key => key)
 }
 
+// Walk a color config value (possibly nested object of shades) and register
+// any leaf string that points to a semantic color name in
+// `semantic.colors.json` (e.g. `surface: 'surfaceColor'`,
+// `brand: { DEFAULT: 'brandColor' }`).
+const _semanticReservedValues = new Set(['transparent', 'currentColor', 'inherit'])
+function collectSemanticReferences(value) {
+  if (typeof value === 'string') {
+    if (value.startsWith('#') || _semanticReservedValues.has(value)) return
+    registerSemanticName(value)
+    return
+  }
+  if (value && typeof value === 'object') {
+    _.each(value, v => collectSemanticReferences(v))
+  }
+}
+
 // ! Helper Functions
 function removeDeprecatedColors(theObject) {
   delete theObject.blueGray
@@ -830,8 +859,8 @@ function generateCombinedClasses(key, data) {
 
 function saveAutoTSS(key, classes) {
   if (fs.existsSync(projectsConfigJS) && saveGlossary) {
-    makeSureFolderExists(cwd + '/purgetss/experimental/tailwind-classes/')
-    saveFile(cwd + `/purgetss/experimental/tailwind-classes/${key}.tss`, classes)
+    makeSureFolderExists(cwd + '/purgetss/glossary/tailwind-classes/')
+    saveFile(cwd + `/purgetss/glossary/tailwind-classes/${key}.tss`, classes)
   }
 }
 

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

@@ -8,10 +8,10 @@
 
 // Import functions from their new modular locations
 import * as helpers from '../../shared/helpers.js'
-import { autoBuildUtilitiesTSS } from '../../../experimental/completions2.js'
+import { autoBuildUtilitiesTSS } from './auto-utilities-builder.js'
 
 /**
- * Build Tailwind (AUTO mode using experimental completions engine)
+ * Build Tailwind (Auto-builds utilities.tss from config.cjs (active production path))
  * @param {Object} options - Build options
  */
 export function buildTailwind(options) {