purgetss 7.9.0 → 7.11.1

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/src/core/builders/auto-utilities-builder.js

@@ -199,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 ?? {}
@@ -837,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')
@@ -857,13 +869,6 @@ function generateCombinedClasses(key, data) {
   return false
 }
 
-function saveAutoTSS(key, classes) {
-  if (fs.existsSync(projectsConfigJS) && saveGlossary) {
-    makeSureFolderExists(cwd + '/purgetss/glossary/tailwind-classes/')
-    saveFile(cwd + `/purgetss/glossary/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/images/ensure-images-section.js

@@ -22,7 +22,9 @@ import { logger } from '../branding/branding-logger.js'
 const IMAGES_BLOCK = `  images: {
     quality: 85,             // JPEG/WebP/AVIF quality (0-100)
     format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
-    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+    autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
+    confirmOverwrites: true, // prompt before overwriting files (set false to skip)
+    files: []                // per-file overrides: [{ filename: 'images/<sub>/<name>.<ext>', width, height? }]
   },
 `
 
@@ -47,11 +49,11 @@ export function ensureImagesSection() {
     fs.writeFileSync(projectsConfigJS, patched, 'utf8')
     console.log()
     logger.success(`Added ${chalk.cyan('images:')} section to ${chalk.cyan('./purgetss/config.cjs')} with default values.`)
-    console.log(`  Edit that block to customize defaults (quality, format).`)
-    console.log(`  CLI flags always win over config values.`)
+    console.log('  Edit that block to customize defaults (quality, format).')
+    console.log('  CLI flags always win over config values.')
     console.log()
   } catch (err) {
     logger.warning(`Could not auto-add images: section to config.cjs (${err.message}).`)
-    logger.warning(`The command will still run using built-in defaults.`)
+    logger.warning('The command will still run using built-in defaults.')
   }
 }

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

@@ -78,21 +78,44 @@ export const IPHONE_SCALES = Object.freeze([
 // 1, 2, 3 for iPhone) only because every entry in *_SCALES is normalized to
 // n/4 with the largest scale (xxxhdpi/@4x) at 4/4. If a future density is
 // added beyond xxxhdpi, this conversion factor needs to be revisited.
-function computeScaleTarget(srcMeta, factor, baseWidth) {
-  if (baseWidth == null) {
+//
+// `baseHeight` pins the height explicitly (e.g. SVG pipeline resolved both
+// w-* and h-* to numbers); when omitted, height follows the source aspect.
+function computeScaleTarget(srcMeta, factor, baseWidth, baseHeight) {
+  // No pin in either direction → fall back to the source as the 4× master.
+  if (baseWidth == null && baseHeight == null) {
     return {
       targetWidth: Math.max(1, Math.round(srcMeta.width * factor)),
       targetHeight: Math.max(1, Math.round(srcMeta.height * factor))
     }
   }
   const multiplier = factor * 4
-  const aspect = srcMeta.width > 0 ? (srcMeta.height / srcMeta.width) : 1
-  return {
-    targetWidth: Math.max(1, Math.round(baseWidth * multiplier)),
-    targetHeight: Math.max(1, Math.round(baseWidth * multiplier * aspect))
+  const widthOverHeight = srcMeta.width > 0 && srcMeta.height > 0
+    ? srcMeta.width / srcMeta.height
+    : 1
+  const heightOverWidth = srcMeta.width > 0 && srcMeta.height > 0
+    ? srcMeta.height / srcMeta.width
+    : 1
+
+  if (baseWidth != null) {
+    const targetWidth = Math.max(1, Math.round(baseWidth * multiplier))
+    const targetHeight = baseHeight != null
+      ? Math.max(1, Math.round(baseHeight * multiplier))
+      : Math.max(1, Math.round(baseWidth * multiplier * heightOverWidth))
+    return { targetWidth, targetHeight }
   }
+
+  // Height pinned, width derived from inverse aspect.
+  const targetHeight = Math.max(1, Math.round(baseHeight * multiplier))
+  const targetWidth = Math.max(1, Math.round(baseHeight * multiplier * widthOverHeight))
+  return { targetWidth, targetHeight }
 }
 
+// Hard ceiling for any individual PNG output. Mirrors the constant exported
+// from the SVG pipeline; centralizing it here would create a cycle, so we keep
+// a local copy and rely on derive-dimensions to enforce the dp-side budget.
+const MAX_OUTPUT_PIXELS = 4096
+
 /**
  * Scale a source image into all Android density variants.
  *
@@ -105,18 +128,19 @@ function computeScaleTarget(srcMeta, factor, baseWidth) {
  * @returns {Promise<string[]>} Paths written
  */
 export async function genAndroidScales(sourceFile, relPath, androidBaseDir, opts = {}) {
-  const { format = null, quality = 85, baseWidth = null } = opts
+  const { format = null, quality = 85, baseWidth = null, baseHeight = null, opacity = null, padding = null } = opts
   const src = await readSource(sourceFile)
   const written = []
 
   for (const { name, factor } of ANDROID_SCALES) {
-    const { targetWidth, targetHeight } = computeScaleTarget(src.meta, factor, baseWidth)
+    const { targetWidth, targetHeight } = computeScaleTarget(src.meta, factor, baseWidth, baseHeight)
+    assertWithinCap(targetWidth, targetHeight, sourceFile, name)
 
     const outDir = path.join(androidBaseDir, name, path.dirname(relPath))
     fs.mkdirSync(outDir, { recursive: true })
 
     const outPath = path.join(outDir, renameWithFormat(path.basename(relPath), format, src.isSvg))
-    await writeScaled(src, outPath, targetWidth, targetHeight, format, quality)
+    await writeScaled(src, outPath, targetWidth, targetHeight, format, quality, opacity, padding)
     written.push(outPath)
   }
   return written
@@ -132,7 +156,7 @@ export async function genAndroidScales(sourceFile, relPath, androidBaseDir, opts
  * @returns {Promise<string[]>} Paths written
  */
 export async function genIphoneScales(sourceFile, relPath, iphoneBaseDir, opts = {}) {
-  const { format = null, quality = 85, baseWidth = null } = opts
+  const { format = null, quality = 85, baseWidth = null, baseHeight = null, opacity = null, padding = null } = opts
   const src = await readSource(sourceFile)
   const written = []
 
@@ -141,7 +165,8 @@ export async function genIphoneScales(sourceFile, relPath, iphoneBaseDir, opts =
   fs.mkdirSync(outDir, { recursive: true })
 
   for (const { suffix, factor } of IPHONE_SCALES) {
-    const { targetWidth, targetHeight } = computeScaleTarget(src.meta, factor, baseWidth)
+    const { targetWidth, targetHeight } = computeScaleTarget(src.meta, factor, baseWidth, baseHeight)
+    assertWithinCap(targetWidth, targetHeight, sourceFile, suffix || '@1x')
 
     // SVG sources can't be written as SVG by Sharp — fall back to PNG if the
     // user didn't specify an explicit output format.
@@ -149,12 +174,21 @@ export async function genIphoneScales(sourceFile, relPath, iphoneBaseDir, opts =
     const outName = `${parsed.name}${suffix}${ext}`
     const outPath = path.join(outDir, outName)
 
-    await writeScaled(src, outPath, targetWidth, targetHeight, format, quality)
+    await writeScaled(src, outPath, targetWidth, targetHeight, format, quality, opacity, padding)
     written.push(outPath)
   }
   return written
 }
 
+function assertWithinCap(width, height, sourceFile, label) {
+  if (width > MAX_OUTPUT_PIXELS || height > MAX_OUTPUT_PIXELS) {
+    throw new Error(
+      `${path.basename(sourceFile)} at ${label} would render ${width}×${height}px, ` +
+      `which exceeds the ${MAX_OUTPUT_PIXELS}px cap. Reduce the resolved width or override it manually in config.cjs > images.files.`
+    )
+  }
+}
+
 function renameWithFormat(filename, format, isSvg = false) {
   if (format) {
     const parsed = path.parse(filename)
@@ -168,15 +202,46 @@ function renameWithFormat(filename, format, isSvg = false) {
   return filename
 }
 
-async function writeScaled(src, outPath, width, height, format, quality) {
-  const targetMax = Math.max(width, height)
+async function writeScaled(src, outPath, width, height, format, quality, opacity, paddingPct) {
+  // Padding shrinks the rendered image inside the same canvas so each density
+  // gets symmetric transparent borders. Computed from the canvas dimensions so
+  // the visual ratio (e.g. 15%) is identical across every density variant.
+  const padX = paddingPct ? Math.floor(width * paddingPct / 100) : 0
+  const padY = paddingPct ? Math.floor(height * paddingPct / 100) : 0
+  const innerW = Math.max(1, width - 2 * padX)
+  const innerH = Math.max(1, height - 2 * padY)
+  const targetMax = Math.max(innerW, innerH)
+
   let pipeline = buildScalePipeline(src, targetMax).resize({
-    width,
-    height,
+    width: innerW,
+    height: innerH,
     fit: 'contain',
     background: { r: 0, g: 0, b: 0, alpha: 0 }
   })
 
+  if (padX > 0 || padY > 0) {
+    pipeline = pipeline.extend({
+      top: padY,
+      bottom: padY,
+      left: padX,
+      right: padX,
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+  }
+
+  // Apply opacity by multiplying the dest alpha against a uniform-alpha tile.
+  // `dest-in` keeps RGB and multiplies dest alpha by source alpha (opacity/100).
+  if (opacity != null && opacity < 100) {
+    pipeline = pipeline
+      .ensureAlpha()
+      .composite([{
+        input: Buffer.from([255, 255, 255, Math.round(255 * opacity / 100)]),
+        raw: { width: 1, height: 1, channels: 4 },
+        tile: true,
+        blend: 'dest-in'
+      }])
+  }
+
   // For SVG sources without an explicit format, coerce output to PNG
   // (Sharp cannot write SVG).
   const fallbackExt = src.isSvg ? 'png' : path.extname(src.path).slice(1).toLowerCase()
@@ -188,7 +253,7 @@ async function writeScaled(src, outPath, width, height, format, quality) {
 
 function applyFormat(pipeline, format, quality) {
   switch (format) {
-    case 'png':  return pipeline.png({ quality, compressionLevel: 9 })
+    case 'png':  return pipeline.png({ compressionLevel: 9 })
     case 'webp': return pipeline.webp({ quality })
     case 'avif': return pipeline.avif({ quality })
     case 'tiff': return pipeline.tiff({ quality, compression: 'lzw' })

package/src/core/images/index.js

@@ -17,6 +17,7 @@
 
 import fs from 'fs'
 import path from 'path'
+import sharp from 'sharp'
 import { logger } from '../branding/branding-logger.js'
 import { logger as mainLogger } from '../../shared/logger.js'
 import { confirmWithAlways } from '../../shared/prompt.js'
@@ -36,23 +37,46 @@ export async function runImages(opts) {
     format = null,
     quality = 85,
     baseWidth = null,
+    opacity = null,     // 0-100 or null
+    padding = null,     // 0-40 (per side, %) or null
+    outputRelpath = null, // basename + subfolder relative to images root, no extension
     dryRun = false,
     yes = false,
-    confirmOverwrites = true
+    confirmOverwrites = true,
+    filesOverrides = []  // [{ filename: 'images/<relpath>', width, height? }, …]
   } = opts
 
   if (!fs.existsSync(source)) {
     throw new Error(`Source not found: ${source}`)
   }
 
+  if (outputRelpath != null && fs.statSync(source).isDirectory()) {
+    throw new Error('--output is incompatible with directory sources (one basename cannot apply to multiple files). Pass a single file as the source, or drop --output.')
+  }
+
   const projectType = detectProjectType(projectRoot)
   const { androidBaseDir, iphoneBaseDir } = resolveOutputDirs(projectRoot, projectType)
 
   const files = collectImageFiles(source)
 
-  if (baseWidth == null && files.some(f => path.extname(f).toLowerCase() === '.svg')) {
-    logger.warning('⚠  SVG source detected without --width. Output sizes will be derived from each SVG\'s viewBox (treated as a 4× master).')
-    logger.warning('   For SVGs from vector editors with disproportionate viewBoxes, pass --width <n> (e.g. --width 256) to pin the @1x/mdpi width.')
+  // Build a lookup keyed by `images/<subpath>` so per-file `width`/`height`
+  // declared in `config.cjs > images.files` can override the directory scan's
+  // default sizing. CLI `--width` still wins over both.
+  const overrides = buildOverridesMap(filesOverrides)
+  const imagesFolderForKey = projectRoot === process.cwd()
+    ? projectsPurge_TSS_Images_Folder
+    : path.join(projectRoot, 'purgetss', 'images')
+
+  if (baseWidth == null) {
+    const uncoveredSvgs = files.filter(f => {
+      if (path.extname(f).toLowerCase() !== '.svg') return false
+      const key = overrideKeyFor(f, imagesFolderForKey)
+      return !overrides.has(key)
+    })
+    if (uncoveredSvgs.length > 0) {
+      logger.warning('⚠  SVG source detected without --width and no entry in config.cjs > images.files. Output sizes will be derived from each SVG\'s viewBox (treated as a 4× master).')
+      logger.warning('   For SVGs from vector editors with disproportionate viewBoxes, pass --width <n> (e.g. --width 256) or add an entry to images.files to pin the @1x/mdpi width.')
+    }
   }
 
   console.log()
@@ -67,6 +91,9 @@ export async function runImages(opts) {
   logger.property('Platforms:  ', platforms.join(' + '))
   if (format) logger.property('Format:     ', `convert all to ${format}`)
   if (baseWidth != null) logger.property('Width:      ', `${baseWidth} px @1x/mdpi`)
+  if (opacity != null) logger.property('Opacity:    ', `${opacity}%`)
+  if (padding != null) logger.property('Padding:    ', `${padding}% per side`)
+  if (outputRelpath != null) logger.property('Output:     ', `images/${outputRelpath}.<ext>`)
   if (dryRun) logger.warning('DRY RUN — no files will be written')
 
   if (files.length === 0) {
@@ -74,9 +101,9 @@ export async function runImages(opts) {
     return { written: [] }
   }
 
-  if (!dryRun && confirmOverwrites) {
+  if (!dryRun && confirmOverwrites && !yes) {
     logger.warning(`⚠  Scaled images will OVERWRITE existing variants under ${androidBaseDir} and ${iphoneBaseDir}.`)
-    logger.warning(`   Commit first if you want a rollback.`)
+    logger.warning('   Commit first if you want a rollback.')
     const choice = await confirmWithAlways('Continue? [y/N/a]', { yes })
     if (choice === 'no') {
       logger.info('Aborted.')
@@ -94,8 +121,8 @@ export async function runImages(opts) {
   }
 
   if (projectType === 'unknown') {
-    logger.warning(`Could not detect project layout. Expected 'app/' (Alloy) or 'Resources/' (Classic).`)
-    logger.warning(`Assets will still be written to the detected default paths — verify the output.`)
+    logger.warning('Could not detect project layout. Expected \'app/\' (Alloy) or \'Resources/\' (Classic).')
+    logger.warning('Assets will still be written to the detected default paths — verify the output.')
   }
 
   // Relative paths preserve the user's subdirectory structure inside purgetss/images/.
@@ -116,17 +143,70 @@ export async function runImages(opts) {
 
   logger.section('Scaling')
   for (const file of files) {
-    const relPath = path.relative(sourceRoot, file)
-    logger.bullet(relPath)
+    // When --output is set, override the computed relPath with the user's
+    // basename + subfolder. Append the source extension so downstream
+    // path.parse / renameWithFormat behave the same as for natural sources.
+    const relPath = outputRelpath != null
+      ? outputRelpath + path.extname(file)
+      : path.relative(sourceRoot, file)
+
+    // Per-file resolution: CLI --width wins; if absent, fall back to the
+    // entry in `images.files` (if any); else null (gen-scales reads viewBox).
+    const override = overrides.get(overrideKeyFor(file, imagesFolderForKey))
+    const effectiveBaseWidth = baseWidth ?? override?.width ?? null
+    const effectiveBaseHeight = baseWidth != null ? null : (override?.height ?? null)
+
+    // SVGs listed in `images.files` are almost always referenced from views/
+    // controllers as `image="/.../foo.svg"`, and Titanium's runtime only falls
+    // back from a `.svg` reference to `.png` (verified empirically — not to
+    // .webp, .jpeg, etc.). Forcing PNG here prevents the standalone command
+    // from quietly emitting a format Titanium can't load via that fallback.
+    // Raster files in `files` and SVGs NOT in `files` still honor `format`.
+    const ext = path.extname(file).toLowerCase()
+    const isSvg = ext === '.svg'
+    const isSvgInFiles = override != null && isSvg
+    const effectiveFormat = isSvgInFiles ? null : format
+
+    // Build an informative bullet so the user can see which decisions applied
+    // per file: source of width, where it came from, and the actual output
+    // format (especially when PNG is forced for SVGs in `files`).
+    const widthSource = baseWidth != null
+      ? `${baseWidth}dp (CLI --width)`
+      : override
+        ? `${override.width}dp (files)`
+        : isSvg ? 'viewBox' : 'source 4×'
+    const outFormat = effectiveFormat ?? (isSvg ? 'png' : ext.slice(1))
+    const formatTag = isSvgInFiles && format && format !== 'png'
+      ? `${outFormat} (forced; ignores format: ${format})`
+      : outFormat
+    logger.bullet(`${relPath} → ${widthSource} · ${formatTag}`)
 
     if (dryRun) continue
 
+    // Quality warning: if the user pinned a width (via CLI or `files`), the
+    // source must carry at least `width × 4` pixels — that's what xxxhdpi/@4x
+    // needs. Anything smaller forces Sharp to upscale, producing blurry output.
+    // SVG sources are vector and exempt from this check.
+    if (effectiveBaseWidth != null && !isSvg) {
+      const meta = await sharp(file).metadata()
+      const requiredXxxhdpi = effectiveBaseWidth * 4
+      if (Number.isFinite(meta.width) && meta.width < requiredXxxhdpi) {
+        logger.warning(
+          `⚠  ${relPath}: source is ${meta.width}px wide but xxxhdpi needs ${requiredXxxhdpi}px (4× of declared ${effectiveBaseWidth}dp @1x). Output will be upscaled and may look blurry — provide a source ≥ ${requiredXxxhdpi}px.`
+        )
+      }
+    }
+
     if (!iphoneOnly) {
-      const androidFiles = await genAndroidScales(file, relPath, androidBaseDir, { format, quality, baseWidth })
+      const androidFiles = await genAndroidScales(file, relPath, androidBaseDir, {
+        format: effectiveFormat, quality, baseWidth: effectiveBaseWidth, baseHeight: effectiveBaseHeight, opacity, padding
+      })
       written.push(...androidFiles)
     }
     if (!androidOnly) {
-      const iphoneFiles = await genIphoneScales(file, relPath, iphoneBaseDir, { format, quality, baseWidth })
+      const iphoneFiles = await genIphoneScales(file, relPath, iphoneBaseDir, {
+        format: effectiveFormat, quality, baseWidth: effectiveBaseWidth, baseHeight: effectiveBaseHeight, opacity, padding
+      })
       written.push(...iphoneFiles)
     }
   }
@@ -155,6 +235,31 @@ function resolveOutputDirs(projectRoot, projectType) {
   }
 }
 
+// Normalize a config `images.files` entry list into a Map keyed by filename.
+// Invalid entries (missing filename, non-numeric width) are silently skipped
+// so a typo in config doesn't crash the whole pipeline.
+function buildOverridesMap(entries) {
+  const map = new Map()
+  if (!Array.isArray(entries)) return map
+  for (const entry of entries) {
+    if (!entry || typeof entry.filename !== 'string') continue
+    if (typeof entry.width !== 'number' || !Number.isFinite(entry.width)) continue
+    const key = entry.filename.replace(/^\/+/, '')
+    map.set(key, {
+      width: entry.width,
+      height: typeof entry.height === 'number' && Number.isFinite(entry.height) ? entry.height : null
+    })
+  }
+  return map
+}
+
+// Match the key shape stored in `config.cjs > images.files`:
+// `images/<subpath>/<name>.<ext>` relative to `purgetss/images/`.
+function overrideKeyFor(file, imagesFolder) {
+  const rel = path.relative(imagesFolder, file).split(path.sep).join('/')
+  return rel.startsWith('..') ? null : `images/${rel}`
+}
+
 function collectImageFiles(source) {
   const stat = fs.statSync(source)
   if (stat.isFile()) {

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

@@ -49,7 +49,7 @@ export function purgeFontAwesome(uniqueClasses, cleanUniqueClasses, debug = fals
     if (fs.existsSync(projectsFA_TSS_File)) {
       sourceFolder = projectsFA_TSS_File
       purgedClasses = '\n// Pro/Beta Font Awesome\n'
-      purgingMessage = `Purging ${chalk.yellow('Pro/Beta Font Awesome')} styles...')`
+      purgingMessage = `Purging ${chalk.yellow('Pro/Beta Font Awesome')} styles...`
     } else {
       sourceFolder = srcFontAwesomeTSSFile
       purgedClasses = '\n// Default Font Awesome\n'
@@ -128,9 +128,13 @@ export function purgeFontIcons(sourceFolder, uniqueClasses, message, cleanUnique
 
   let purgedClasses = ''
   const sourceTSS = fs.readFileSync(sourceFolder, 'utf8')
+  const hasMatches = cleanUniqueClasses.some(element => sourceTSS.includes(`'.${element}'`))
 
-  if (cleanUniqueClasses.some(element => sourceTSS.includes(`'.${element}'`))) {
-    logger.info(message)
+  if (hasMatches) {
+    // In debug mode the label is emitted by localFinish inline with the timing.
+    // In non-debug mode this is the progress indicator (only shown when there's
+    // actual work for this font, matching pre-existing behavior).
+    if (!debug) logger.info(message)
     const sourceTSSFile = sourceTSS.split(/\r?\n/)
     uniqueClasses.forEach(className => {
       const cleanClassName = cleanClassNameFn(className)

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

@@ -48,7 +48,9 @@ function cleanClassNameFn(className) {
 export function purgeTailwind(uniqueClasses, debug = false) {
   if (debug) localStart()
 
-  logger.info('Purging', chalk.yellow('utilities.tss'), 'styles...')
+  // In debug mode, the section label is emitted by localFinish together with
+  // the timing (inline). In non-debug mode this line is the progress indicator.
+  if (!debug) logger.info('Purging', chalk.yellow('utilities.tss'), 'styles...')
 
   let purgedClasses = ''
   let tailwindClasses = fs.readFileSync(projectsTailwind_TSS, 'utf8').split(/\r?\n/)