purgetss 7.7.0 → 7.9.0

package/README.md

@@ -17,7 +17,7 @@
 - 23,300+ utility classes for styling Titanium views
 - Parses XML files to generate a clean `app.tss` with only the classes your project uses
 - Customizable defaults via `config.cjs`, with JIT classes for arbitrary values
-- `brand` command for Titanium icons and branding assets, including Android launcher variants, optional Android 12+ splash artwork, and legacy `default.png` fallback generation
+- `brand` command for Titanium icons and branding assets, focused on the modern Titanium icon pipeline: Android adaptive icons, iOS icon variants, optional Android 12+ splash artwork, and a minimal `default.png` compatibility fallback
 - Icon font support: Font Awesome, Material Icons, Material Symbols, Framework7-Icons
 - `build-fonts` command generates `fonts.tss` with class definitions and fontFamily selectors
 - `shades` command generates color shades from any hex color
@@ -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`.
@@ -384,6 +392,8 @@ Button: {
 - `brand` regenerates `app/assets/android/default.png` in Alloy projects, or `Resources/android/default.png` in Classic projects, so older Android splash paths still have a fallback.
 - `cleanup-legacy` no longer removes `default.png`.
 - Branding help and docs now spell out the difference between Android launcher icons, Android 12+ `splash_icon.png`, and legacy Android splash assets.
+- `--notes` is explicit that `tiapp.xml` is not auto-edited and that apps with an existing custom Android theme should merge splash snippets into that theme instead of replacing it.
+- `brand` does not try to manage older Android splash theme assets such as `background.png` or `background.9.png`; if a project still depends on them, that remains manual by design.
 
 See the full release notes in [CHANGELOG.md](./CHANGELOG.md).
 

package/bin/purgetss

@@ -273,18 +273,25 @@ The recommended workflow is: put files in ${chalk.cyan('purgetss/brand/')}, then
 CLI flags always win over config values.
 
 Generates:
-  ${chalk.yellow('DefaultIcon.png')} / ${chalk.yellow('DefaultIcon-ios.png')}              Root icons (alpha + flattened)
-  ${chalk.yellow('DefaultIcon-Dark.png')} / ${chalk.yellow('DefaultIcon-Tinted.png')}     iOS 18+ variants (Apple HIG specs)
-  ${chalk.yellow('iTunesConnect.png')} / ${chalk.yellow('MarketplaceArtwork.png')}       App Store + Play Store artwork
+  ${chalk.yellow('DefaultIcon.png')}/${chalk.yellow('DefaultIcon-ios.png')}                          Root icons (alpha + flattened)
+  ${chalk.yellow('DefaultIcon-Dark.png')}/${chalk.yellow('DefaultIcon-Tinted.png')}                  iOS 18+ variants (Apple HIG specs)
+  ${chalk.yellow('iTunesConnect.png')}/${chalk.yellow('MarketplaceArtwork.png')}                     App Store + Play Store artwork
   ${chalk.yellow('mipmap-*/ic_launcher_{foreground,background,monochrome}.png')}  Android adaptive × 5
-  ${chalk.yellow('mipmap-*/ic_launcher.png')}                           Android legacy × 5
-  ${chalk.yellow('mipmap-anydpi-v26/ic_launcher.xml')}                  Adaptive icon binder
-  ${chalk.yellow('drawable-*/splash_icon.png')}                         Android 12+ splash icon (with ${chalk.cyan('--splash')})
-  ${chalk.yellow('app/assets/android/default.png')}                     Android <12 legacy splash fallback
+  ${chalk.yellow('mipmap-*/ic_launcher.png')}                                     Android legacy × 5
+  ${chalk.yellow('mipmap-anydpi-v26/ic_launcher.xml')}                            Adaptive icon binder
+  ${chalk.yellow('drawable-*/splash_icon.png')}                                   Android 12+ splash icon (with ${chalk.cyan('--splash')})
+  ${chalk.yellow('app/assets/android/default.png')}                               Android <12 compatibility fallback
 
 Android dark/light mode is handled by the ${chalk.yellow('monochrome')} adaptive layer
 (Android 13+ tints it from the wallpaper + theme). No separate dark file exists.
 
+Scope:
+  ${chalk.green('brand')} targets the modern Titanium icon pipeline: iOS app icons,
+  Android adaptive icons, and optional Android 12+ splash artwork.
+  Older Android splash themes such as ${chalk.yellow('background.png')} / ${chalk.yellow('background.9.png')}
+  are outside the normal scope of this command and should be managed manually
+  if a project still depends on them.
+
 Examples:
   ${chalk.cyan('purgetss brand')}                                           # uses purgetss/brand/logo.svg + config
   ${chalk.cyan('purgetss brand')} logo.svg                                  # explicit logo path
@@ -346,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
@@ -354,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.0
+// PurgeTSS v7.8.0
 // Created by César Estrada
 // https://purgetss.com
 

package/lib/templates/purgetss.config.js.cjs

@@ -13,15 +13,7 @@ module.exports = {
     }
   },
   brand: {
-    logos: {
-      // Optional overrides. If omitted, PurgeTSS auto-discovers files from purgetss/brand/:
-      // primary: './docs/logo.svg',
-      // androidLauncher: './docs/app-icon.svg',
-      // androidSplash: './docs/splash.svg',
-      // monochrome: './docs/logo-mono.svg',
-      // iosDark: './docs/logo-dark.svg',
-      // iosTinted: './docs/logo-tinted.svg'
-    },
+    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
@@ -31,15 +23,14 @@ module.exports = {
       splash: false,         // also generate splash_icon.png × 5
       notification: false    // also generate ic_stat_notify.png × 5
     },
+    ios: {
+      dark: true,            // generate iOS 18+ Dark appearance icon
+      tinted: true,          // generate iOS 18+ Tinted appearance icon
+      darkBackground: null   // null = transparent per Apple HIG
+    },
     colors: {
       background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
     },
-    // Optional iOS overrides:
-    // ios: {
-    //   dark: false,
-    //   tinted: false,
-    //   darkBackground: '#111111'
-    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "purgetss",
-  "version": "7.7.0",
+  "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/src/core/branding/ensure-brand-section.js

@@ -23,15 +23,7 @@ import { projectsConfigJS, projectsPurge_TSS_Brand_Folder } from '../../shared/c
 import { logger } from './branding-logger.js'
 
 const BRAND_BLOCK = `  brand: {
-    logos: {
-      // Optional overrides. If omitted, PurgeTSS auto-discovers files from purgetss/brand/:
-      // primary: './docs/logo.svg',
-      // androidLauncher: './docs/app-icon.svg',
-      // androidSplash: './docs/splash.svg',
-      // monochrome: './docs/logo-mono.svg',
-      // iosDark: './docs/logo-dark.svg',
-      // iosTinted: './docs/logo-tinted.svg'
-    },
+    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
@@ -41,15 +33,14 @@ const BRAND_BLOCK = `  brand: {
       splash: false,         // also generate splash_icon.png × 5
       notification: false    // also generate ic_stat_notify.png × 5
     },
+    ios: {
+      dark: true,            // generate iOS 18+ Dark appearance icon
+      tinted: true,          // generate iOS 18+ Tinted appearance icon
+      darkBackground: null   // null = transparent per Apple HIG
+    },
     colors: {
       background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
     },
-    // Optional iOS overrides:
-    // ios: {
-    //   dark: false,
-    //   tinted: false,
-    //   darkBackground: '#111111'
-    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
 `

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

@@ -84,6 +84,10 @@ function printFullNotes(opts) {
   logger.section('Configuration reminders')
   console.log('  The tool does NOT auto-edit tiapp.xml. Snippets below are optional —')
   console.log('  paste only what you need, after reviewing.')
+  console.log('  If your app already uses a custom Android theme, merge these changes')
+  console.log('  into that theme instead of replacing it blindly.')
+  console.log('  brand is designed around the modern Titanium icon pipeline, not around')
+  console.log('  older Android splash themes such as background.png / background.9.png.')
   console.log()
   console.log(`  ${chalk.yellow('⚠')}  ${chalk.yellow('tiapp.xml <application> tag may be self-closing')}`)
   console.log('     If yours looks like:')
@@ -114,14 +118,18 @@ function printFullNotes(opts) {
     console.log('     If you want the Android 12+ splash to use splash_icon instead of')
     console.log('     ic_launcher, add a custom theme and point')
     console.log(code('       <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>'))
+    console.log('     If you still see a brief flash during splash exit, the artifact may')
+    console.log('     come from Titanium or the system splash transition rather than from')
+    console.log('     the generated PNG assets themselves.')
   }
 
   console.log()
   console.log(`  ${num(withSplash ? '4.' : '3.')} ${chalk.cyan('Android <12 legacy splash')}`)
-  console.log('     PurgeTSS brand now regenerates app/assets/android/default.png as')
-  console.log('     a legacy fallback splash for Titanium projects.')
-  console.log('     If your app uses a custom windowBackground / background.9.png theme,')
-  console.log('     that custom theme still takes precedence.')
+  console.log('     PurgeTSS brand still regenerates app/assets/android/default.png as')
+  console.log('     a compatibility fallback while Titanium continues to recognize it.')
+  console.log('     It is not the primary modern path. If your app uses a custom')
+  console.log('     windowBackground / background.9.png theme, that custom theme still')
+  console.log('     takes precedence and should be managed manually.')
 
   if (withNotification) {
     const colorsDir = projectType === 'classic'