purgetss 7.7.1 → 7.11.1

package/src/core/analyzers/class-extractor.js

@@ -71,6 +71,60 @@ export function extractClasses(currentText, currentFile) {
   }
 }
 
+/**
+ * Extract SVG image references from XML content.
+ *
+ * For each XML node whose `image` or `backgroundImage` attribute ends in `.svg`,
+ * capture the SVG src alongside the same node's `class` attribute (split into
+ * tokens). Powers the SVG image pipeline so it can pair each reference with the
+ * classes that determine its rendered size.
+ *
+ * Multiple references to the same SVG from different nodes are returned as
+ * separate entries — the caller is responsible for de-duplicating and reducing
+ * to a single resolved dimension.
+ *
+ * @param {string} currentText - XML content to parse.
+ * @param {string} currentFile - File path for error reporting.
+ * @returns {Array<{ src: string, classes: string[] }>} References found.
+ */
+export function extractSvgRefsFromXml(currentText, currentFile) {
+  try {
+    const jsontext = convert.xml2json(encodeHTML(currentText), { compact: true })
+    const json = JSON.parse(jsontext)
+    const refs = []
+    walkXmlForSvgRefs(json, refs)
+    return refs
+  } catch (error) {
+    throw chalk.red(`::PurgeTSS:: Error processing: "${currentFile}"\n`, error)
+  }
+}
+
+function walkXmlForSvgRefs(node, out) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const item of node) walkXmlForSvgRefs(item, out)
+    return
+  }
+
+  const attrs = node._attributes
+  if (attrs && typeof attrs === 'object') {
+    const candidates = []
+    if (typeof attrs.image === 'string') candidates.push(attrs.image)
+    if (typeof attrs.backgroundImage === 'string') candidates.push(attrs.backgroundImage)
+    for (const src of candidates) {
+      if (!src.toLowerCase().endsWith('.svg')) continue
+      const cls = typeof attrs.class === 'string' ? attrs.class : ''
+      const classes = cls.split(/\s+/).filter(Boolean)
+      out.push({ src, classes })
+    }
+  }
+
+  for (const key of Object.keys(node)) {
+    if (key === '_attributes') continue
+    walkXmlForSvgRefs(node[key], out)
+  }
+}
+
 /**
  * Extract only classes from XML content - COPIED exactly from original extractClassesOnly() function
  * NO CHANGES to logic, preserving 100% of original functionality

package/src/core/analyzers/controller-svg-refs.js

@@ -0,0 +1,154 @@
+/**
+ * PurgeTSS - SVG reference extractor for controllers
+ *
+ * Companion to class-extractor.js for the SVG image pipeline. Walks the AST of
+ * each controller file looking for ObjectExpressions that pair an image (or
+ * backgroundImage) property pointing to an .svg with a sibling `classes`
+ * property. Typical shape:
+ *
+ *   $.UI.create('ImageView', {
+ *     image: '/images/logos/logo.svg',
+ *     classes: 'w-32 h-auto'
+ *   })
+ *
+ * Only the in-place shape counts — references built from concatenated/dynamic
+ * strings cannot be detected statically and must be declared manually in
+ * config.cjs > images.files (per the plan).
+ *
+ * @fileoverview Extract SVG references from controller .js files
+ * @author César Estrada
+ */
+
+import * as acorn from 'acorn'
+
+const AST_META_KEYS = new Set(['type', 'loc', 'range', 'start', 'end', 'sourceType', 'comments'])
+
+/**
+ * Parse a controller's source and return SVG references paired with their
+ * `classes` siblings inside the same object literal.
+ *
+ * Falls back to a conservative regex scan if the parser rejects the source.
+ *
+ * @param {string} data - Controller file content.
+ * @returns {Array<{ src: string, classes: string[] }>}
+ */
+export function extractSvgRefsFromController(data) {
+  try {
+    const ast = acorn.parse(data, {
+      ecmaVersion: 'latest',
+      sourceType: 'script',
+      allowReturnOutsideFunction: true,
+      allowAwaitOutsideFunction: true,
+      allowImportExportEverywhere: true,
+      allowHashBang: true
+    })
+    const out = []
+    walkAST(ast, out)
+    return out
+  } catch {
+    return extractSvgRefsRegex(data)
+  }
+}
+
+function walkAST(node, out) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const child of node) walkAST(child, out)
+    return
+  }
+  if (!node.type) return
+
+  if (node.type === 'ObjectExpression') {
+    inspectObject(node, out)
+  }
+
+  for (const key of Object.keys(node)) {
+    if (AST_META_KEYS.has(key)) continue
+    walkAST(node[key], out)
+  }
+}
+
+function inspectObject(obj, out) {
+  let svgSrc = null
+  let classes = null
+
+  for (const prop of obj.properties) {
+    if (!prop || prop.type !== 'Property' || prop.computed || prop.shorthand) continue
+    const keyName = propKeyName(prop)
+    if (!keyName) continue
+
+    if (keyName === 'image' || keyName === 'backgroundImage') {
+      const literal = stringLiteralValue(prop.value)
+      if (literal && literal.toLowerCase().endsWith('.svg')) {
+        svgSrc = literal
+      }
+    } else if (keyName === 'classes') {
+      classes = collectClassTokens(prop.value)
+    }
+  }
+
+  if (svgSrc) {
+    out.push({ src: svgSrc, classes: classes || [] })
+  }
+}
+
+function propKeyName(prop) {
+  if (prop.key.type === 'Identifier') return prop.key.name
+  if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') return prop.key.value
+  return null
+}
+
+function stringLiteralValue(node) {
+  if (!node) return null
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length === 1) {
+    const cooked = node.quasis[0].value.cooked
+    return typeof cooked === 'string' ? cooked : null
+  }
+  return null
+}
+
+function collectClassTokens(node) {
+  if (!node) return []
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    return node.value.split(/\s+/).filter(Boolean)
+  }
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length === 1) {
+    const cooked = node.quasis[0].value.cooked
+    return typeof cooked === 'string' ? cooked.split(/\s+/).filter(Boolean) : []
+  }
+  if (node.type === 'ArrayExpression') {
+    const tokens = []
+    for (const el of node.elements) {
+      if (el && el.type === 'Literal' && typeof el.value === 'string') {
+        tokens.push(...el.value.split(/\s+/).filter(Boolean))
+      }
+    }
+    return tokens
+  }
+  return []
+}
+
+// Conservative regex fallback: look for objects that pair both keys on the
+// same {...} chunk. Misses anything spread across complex expressions, but the
+// AST path already covers the realistic cases — this is just a safety net.
+function extractSvgRefsRegex(data) {
+  const out = []
+  const objRegex = /\{[^{}]*\}/g
+  for (const match of data.matchAll(objRegex)) {
+    const chunk = match[0]
+    const imgMatch = chunk.match(/\b(?:image|backgroundImage)\s*:\s*['"`]([^'"`]+\.svg)['"`]/i)
+    if (!imgMatch) continue
+    const classesMatch = chunk.match(/\bclasses\s*:\s*(?:['"`]([^'"`]+)['"`]|\[([^\]]+)\])/)
+    let classes = []
+    if (classesMatch) {
+      const raw = classesMatch[1] || classesMatch[2] || ''
+      classes = raw
+        .split(/[,\s]+/)
+        .map(t => t.trim().replace(/^['"`]|['"`]$/g, ''))
+        .filter(Boolean)
+    }
+    out.push({ src: imgMatch[1], classes })
+  }
+  return out
+}

package/src/core/branding/brand-config.js

@@ -66,6 +66,7 @@ export function resolveBrandConfig(cliOptions, cliLogo, projectRoot) {
     ?? 19
 
   const androidLegacyPadding = cliOptions.androidLegacyPadding
+    ?? cliOptions.padding
     ?? padding.androidLegacy
     ?? 10
 
@@ -73,6 +74,10 @@ export function resolveBrandConfig(cliOptions, cliLogo, projectRoot) {
     ?? padding.ios
     ?? 4
 
+  const featureGraphicPadding = cliOptions.featureGraphicPadding
+    ?? padding.featureGraphic
+    ?? 12
+
   const bgColor = cliOptions.bgColor
     ?? colors.background
     ?? '#FFFFFF'
@@ -88,6 +93,7 @@ export function resolveBrandConfig(cliOptions, cliLogo, projectRoot) {
     darkLogo: pickLogo(cliOptions.darkLogo, logos.iosDark, brandDir, 'logo-dark', projectRoot),
     tintedLogo: pickLogo(cliOptions.tintedLogo, logos.iosTinted, brandDir, 'logo-tinted', projectRoot),
     splashLogo: pickLogo(cliOptions.splashLogo, logos.androidSplash, brandDir, 'logo-splash', projectRoot),
+    featureLogo: pickLogo(cliOptions.featureLogo, logos.featureGraphic, brandDir, 'logo-feature', projectRoot),
 
     bgColor,
     bgColorExplicit: Boolean(cliOptions.bgColor ?? colors.background),
@@ -95,6 +101,7 @@ export function resolveBrandConfig(cliOptions, cliLogo, projectRoot) {
     androidAdaptivePadding,
     androidLegacyPadding,
     iosPadding,
+    featureGraphicPadding,
 
     // Kitchen-sink defaults: adaptive + marketplace are always generated; only
     // notification and splash are opt-in. Config can pre-enable them.

package/src/core/branding/ensure-brand-section.js

@@ -25,9 +25,10 @@ import { logger } from './branding-logger.js'
 const BRAND_BLOCK = `  brand: {
     logos: {},               // empty = auto-discovers from purgetss/brand/
     padding: {
-      ios: '4%',             // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
-      androidLegacy: '10%',  // legacy ic_launcher.png padding
-      androidAdaptive: '19%' // adaptive foreground padding near the Android safe-zone
+      ios: '4%',              // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
+      androidLegacy: '10%',   // legacy ic_launcher.png padding
+      androidAdaptive: '19%', // adaptive foreground padding near the Android safe-zone
+      featureGraphic: '12%'   // Google Play Feature Graphic vertical padding (1024×500)
     },
     android: {
       splash: false,         // also generate splash_icon.png × 5

package/src/core/branding/gen-feature-graphic.js

@@ -0,0 +1,57 @@
+/**
+ * PurgeTSS - gen-feature-graphic
+ *
+ * Google Play Feature Graphic:
+ *   MarketplaceArtworkFeature.png  1024×500  (Play Store listing top banner)
+ *
+ * Always flattened on bgColor — Google Play requires opaque artwork.
+ *
+ * Layout: a square logo block centered both horizontally and vertically inside
+ * the 1024×500 canvas. Padding is vertical-driven (top/bottom) — the inner
+ * box becomes side = 500 - 2*pad. The logo is scaled with `fit: 'inside'`
+ * so wide/tall logos preserve aspect ratio inside that square.
+ *
+ * @fileoverview Google Play Feature Graphic for Titanium branding
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+const CANVAS_WIDTH = 1024
+const CANVAS_HEIGHT = 500
+
+export async function genFeatureGraphic(featureMaster, paddingPct, outRoot, opts = {}) {
+  const { bgColor = '#FFFFFF' } = opts
+  fs.mkdirSync(outRoot, { recursive: true })
+
+  const padPx = Math.floor((CANVAS_HEIGHT * paddingPct) / 100)
+  const inner = CANVAS_HEIGHT - 2 * padPx
+  const outPath = path.join(outRoot, 'MarketplaceArtworkFeature.png')
+
+  const resized = await sharp(featureMaster)
+    .resize({
+      width: inner,
+      height: inner,
+      fit: 'inside',
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .toBuffer()
+
+  await sharp({
+    create: {
+      width: CANVAS_WIDTH,
+      height: CANVAS_HEIGHT,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    }
+  })
+    .composite([{ input: resized, gravity: 'center' }])
+    .flatten({ background: bgColor })
+    .removeAlpha()
+    .png({ compressionLevel: 9 })
+    .toFile(outPath)
+
+  return outPath
+}

package/src/core/branding/index.js

@@ -48,6 +48,7 @@ import { genAndroidAdaptive } from './gen-android-adaptive.js'
 import { genAndroidLegacy } from './gen-android-legacy.js'
 import { genAndroidDefault } from './gen-android-default.js'
 import { genMarketplace } from './gen-marketplace.js'
+import { genFeatureGraphic } from './gen-feature-graphic.js'
 import { genNotification } from './gen-notification.js'
 import { genSplash } from './gen-splash.js'
 import { genIcLauncherXml } from './gen-ic-launcher-xml.js'
@@ -60,6 +61,7 @@ export async function runBranding(opts) {
     logo,
     iconLogo = null,
     splashLogo = null,
+    featureLogo = null,
     monochromeLogo = null,
     darkLogo = null,
     darkBgColor = null,
@@ -71,6 +73,7 @@ export async function runBranding(opts) {
     androidAdaptivePadding = 19,
     androidLegacyPadding = 10,
     iosPadding = 4,
+    featureGraphicPadding = 12,
     notification = false,
     splash = false,
     cleanupLegacy: runCleanup = false,
@@ -84,7 +87,7 @@ export async function runBranding(opts) {
     confirmOverwrites = true
   } = opts
 
-  validateOptions({ logo, bgColor, darkBgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, cleanupLegacy: runCleanup })
+  validateOptions({ logo, bgColor, darkBgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, featureGraphicPadding, cleanupLegacy: runCleanup })
 
   const projectType = detectProjectType(projectRoot)
   const isInPlace = inPlace && !output
@@ -97,7 +100,7 @@ export async function runBranding(opts) {
   if (logo) {
     logger.property('Logo:       ', logo)
     logger.property('Background: ', bgColor)
-    logger.property('Padding:    ', `Android adaptive ${androidAdaptivePadding}% / Android legacy ${androidLegacyPadding}% / iOS ${iosPadding}% per side`)
+    logger.property('Padding:    ', `Android adaptive ${androidAdaptivePadding}% / Android legacy ${androidLegacyPadding}% / iOS ${iosPadding}% per side / Feature Graphic ${featureGraphicPadding}% vertical`)
     console.log()
     logger.property(isInPlace ? 'Writing IN PLACE to: ' : 'Staging:    ', isInPlace ? projectRoot : stagingRoot)
   }
@@ -159,6 +162,8 @@ export async function runBranding(opts) {
       lines.push(`${stagingRoot}/DefaultIcon-Tinted.png (${tintedSrc})`)
     }
     lines.push(`${stagingRoot}/iTunesConnect.png + MarketplaceArtwork.png`)
+    const featureSrc = featureLogo ? `from ${featureLogo}` : 'from main logo'
+    lines.push(`${stagingRoot}/MarketplaceArtworkFeature.png (${featureSrc}, ${featureGraphicPadding}% vertical padding)`)
     lines.push(`${androidResStaging}/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/ic_launcher_{foreground,background,monochrome}.png`)
     lines.push(`${androidResStaging}/mipmap-{...}/ic_launcher.png (legacy)`)
     lines.push(`${androidResStaging}/mipmap-anydpi-v26/ic_launcher.xml`)
@@ -265,6 +270,20 @@ export async function runBranding(opts) {
   })
   generated.push(mkt.itunesConnect, mkt.marketplaceArtwork)
 
+  let featureMaster = tight
+  if (featureLogo) {
+    if (!fs.existsSync(featureLogo)) {
+      throw new Error(`Feature Graphic logo not found: ${featureLogo}`)
+    }
+    const featureBase = path.join(tempDir, '_logo_feature')
+    const featureResult = await prepareMaster(featureLogo, featureBase)
+    featureMaster = featureResult.tight
+  }
+  const featureSrcLabel = featureLogo ? 'from --feature-logo' : 'from main logo'
+  logger.bullet(`MarketplaceArtworkFeature.png (1024×500, ${featureSrcLabel}, ${featureGraphicPadding}% vertical padding, flattened on ${bgColor})`)
+  const featurePath = await genFeatureGraphic(featureMaster, featureGraphicPadding, stagingRoot, { bgColor })
+  generated.push(featurePath)
+
   // ---- Section: Android --------------------------------------------------
   logger.section('Android')
 
@@ -323,7 +342,9 @@ export async function runBranding(opts) {
         path.join(tempDir, '_logo_tinted_square.png'),
         path.join(tempDir, '_logo_tinted_tight.png'),
         path.join(tempDir, '_logo_splash_square.png'),
-        path.join(tempDir, '_logo_splash_tight.png')
+        path.join(tempDir, '_logo_splash_tight.png'),
+        path.join(tempDir, '_logo_feature_square.png'),
+        path.join(tempDir, '_logo_feature_tight.png')
       ]
       for (const tmp of tmpFiles) {
         if (fs.existsSync(tmp)) fs.unlinkSync(tmp)
@@ -385,7 +406,7 @@ function getStagingAndroidAssetsRoot(stagingRoot, projectType) {
   return null
 }
 
-function validateOptions({ logo, bgColor, darkBgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, cleanupLegacy }) {
+function validateOptions({ logo, bgColor, darkBgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, featureGraphicPadding, cleanupLegacy }) {
   if (!logo && !cleanupLegacy) {
     throw new Error('Logo image path is required (unless using --cleanup-legacy alone).')
   }
@@ -404,4 +425,7 @@ function validateOptions({ logo, bgColor, darkBgColor, androidAdaptivePadding, a
   if (iosPadding < 0 || iosPadding > 40) {
     throw new Error(`--ios-padding must be between 0 and 40 (got: ${iosPadding}).`)
   }
+  if (featureGraphicPadding < 0 || featureGraphicPadding > 40) {
+    throw new Error(`--feature-graphic-padding must be between 0 and 40 (got: ${featureGraphicPadding}).`)
+  }
 }

package/src/core/branding/post-gen-notes.js

@@ -37,12 +37,12 @@ function printCompactSummary(opts) {
     logger.bullet(`Rebuild: ${chalk.gray('ti clean && ti build -p android -T emulator')}`)
   } else if (projectType === 'alloy') {
     logger.bullet(`Preview in ${chalk.yellow('Preview.app')}, then copy to project:`)
-    console.log(chalk.gray(`      cp ${stagingRoot}/{DefaultIcon,DefaultIcon-ios,DefaultIcon-Dark,DefaultIcon-Tinted,iTunesConnect,MarketplaceArtwork}.png ${projectRoot}/`))
+    console.log(chalk.gray(`      cp ${stagingRoot}/{DefaultIcon,DefaultIcon-ios,DefaultIcon-Dark,DefaultIcon-Tinted,iTunesConnect,MarketplaceArtwork,MarketplaceArtworkFeature}.png ${projectRoot}/`))
     console.log(chalk.gray(`      cp -R ${stagingRoot}/app/platform/android/res/. ${projectRoot}/app/platform/android/res/`))
     logger.bullet(`Cleanup staging: ${chalk.gray('rm -rf ' + stagingRoot)}`)
   } else if (projectType === 'classic') {
     logger.bullet(`Preview in ${chalk.yellow('Preview.app')}, then copy to project:`)
-    console.log(chalk.gray(`      cp ${stagingRoot}/{DefaultIcon,DefaultIcon-ios,DefaultIcon-Dark,DefaultIcon-Tinted,iTunesConnect,MarketplaceArtwork}.png ${projectRoot}/`))
+    console.log(chalk.gray(`      cp ${stagingRoot}/{DefaultIcon,DefaultIcon-ios,DefaultIcon-Dark,DefaultIcon-Tinted,iTunesConnect,MarketplaceArtwork,MarketplaceArtworkFeature}.png ${projectRoot}/`))
     console.log(chalk.gray(`      cp -R ${stagingRoot}/platform/android/res/. ${projectRoot}/platform/android/res/`))
     logger.bullet(`Cleanup staging: ${chalk.gray('rm -rf ' + stagingRoot)}`)
   } else {

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 ''
 }
@@ -206,7 +199,20 @@ function scaffoldGlossary() {
   }
 }
 
-let configFile = getConfigFile()
+// getConfigFile() runs at module import time, before bin/purgetss's catch
+// handler is wired up. If the config validator throws a presentable error
+// (isSyntaxError), print it cleanly and exit instead of letting Node surface
+// the raw stack on top of an already-formatted report.
+let configFile
+try {
+  configFile = getConfigFile()
+} catch (err) {
+  if (err && err.isSyntaxError) {
+    console.error(err.message)
+    process.exit(1)
+  }
+  throw err
+}
 configFile.purge = configFile.purge ?? { mode: 'all' }
 configFile.theme = configFile.theme ?? {}
 configFile.theme.extend = configFile.theme.extend ?? {}
@@ -236,7 +242,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 +261,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 +317,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 +384,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 +540,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 +583,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 +603,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 +636,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
@@ -808,15 +850,14 @@ function generateCombinedClasses(key, data) {
   const comments = processComments(key, data)
 
   if (Object.entries(data.base).length) {
-    _.each(data.base, (value, _key) => {
-      if (typeof value === 'object') {
-        _.each(value, (_value, __key) => {
-          myClasses += `'.${setModifier(removeUneededVariablesFromPropertyName(camelCaseToDash(key + '-' + _key + '-' + __key)))}': { ${key}: ${helpers.parseValue(_value)} }\n`
-        })
+    const walk = (value, segments) => {
+      if (value && typeof value === 'object') {
+        _.each(value, (childValue, childKey) => walk(childValue, [...segments, childKey]))
       } else {
-        myClasses += `'.${setModifier(removeUneededVariablesFromPropertyName(camelCaseToDash(key + '-' + _key)))}': { ${key}: ${helpers.parseValue(value)} }\n`
+        myClasses += `'.${setModifier(removeUneededVariablesFromPropertyName(camelCaseToDash(segments.join('-'))))}': { ${key}: ${helpers.parseValue(value)} }\n`
       }
-    })
+    }
+    walk(data.base, [key])
   } else {
     _.each(data.values, (_value, _key) => {
       if (!_value.includes('deprecated')) myClasses += formatClass(key, _value, data.type === 'Array')
@@ -828,13 +869,6 @@ function generateCombinedClasses(key, data) {
   return false
 }
 
-function saveAutoTSS(key, classes) {
-  if (fs.existsSync(projectsConfigJS) && saveGlossary) {
-    makeSureFolderExists(cwd + '/purgetss/experimental/tailwind-classes/')
-    saveFile(cwd + `/purgetss/experimental/tailwind-classes/${key}.tss`, classes)
-  }
-}
-
 // inputType is marked as Array in completions but accepts a single value
 const nonArrayOverrides = new Set(['inputType'])
 

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) {