purgetss 7.9.0 → 7.11.1

package/README.md

@@ -377,10 +377,30 @@ Button: {
 
 ## Recent changes
 
+### v7.11.0
+
+- **SVG-aware compile-time image pipeline as a post-step of `purgetss`.** When views or controllers reference `image="/images/<sub>/<name>.svg"` (or `backgroundImage="..."`) alongside utility classes that resolve to numeric width/height (`w-32`, `w-(300)`, `h-auto`, …), purge now compiles those SVGs into the 8 Titanium density variants (5 Android + 3 iPhone PNGs) using dimensions resolved from `app.tss` after the regular purge finishes. Titanium loads the generated `.png` automatically at runtime when the XML/Controller references `.svg`. Cache lives at `purgetss/.cache/svg-images.json` (add to `.gitignore`). The SVG attribute stays untouched in your source — never rewritten.
+- **`images.files` array in `config.cjs` as per-file override.** Pin width/height for individual files in `purgetss/images/`: `[{ filename: 'images/logos/logo.png', width: 128, height: 52 }, ...]`. When `purgetss images` runs, entries override the source's natural dimensions; CLI `--width` still wins over both. For SVGs detected by the purge SVG pipeline, entries populate automatically (subject to `images.autoSync`). Raster entries you add by hand survive subsequent runs untouched.
+- **`images.autoSync` boolean (default `true`).** Opt-out for devs who manage `images.files` by hand — when `false`, purge still computes dimensions and generates PNGs, but never writes back to `config.cjs`.
+- **Quality warning when a raster source is too small for its declared width.** Sources smaller than `width × 4` (the xxxhdpi/@4x requirement) trigger a non-blocking warning with exact numbers. SVGs are exempt (vector, no upscale penalty).
+
+### The 4× source convention
+
+Both `purgetss images` and `purgetss brand` treat each source file as the **xxxhdpi/@4x master**: your file's pixel dimensions ARE the largest density, and smaller densities derive at 1/4, 1.5/4, 2/4, 3/4. A 256 px PNG produces a 64 px `@1x/mdpi`. If you want 64 dp at `@1x`, drop a 256 px source.
+
+Override per file via `images.files` in `config.cjs` (or the brand-specific fields under `brand.logos`/`brand.padding`). The convention is the default fallback — entries override it on a per-file basis. CLI flags like `--width` always win over both.
+
+### v7.10.0
+
+- **`MarketplaceArtworkFeature.png` (Google Play Feature Graphic) auto-generated by `purgetss brand`.** Every brand run now writes a 1024×500 banner to the project root alongside the existing `iTunesConnect.png` and `MarketplaceArtwork.png` submission assets. Master logo centered both axes inside the rectangular canvas with 12% vertical padding default, flattened on `brand.colors.background`. Override paths: CLI `--feature-graphic-padding <n>`, config `brand.padding.featureGraphic`, and optional `purgetss/brand/logo-feature.{svg,png}` (or CLI `--feature-logo` / `brand.logos.featureGraphic`) for a dedicated source. Submission artwork only — file goes to the project root for upload to the Play Console, not bundled into the APK.
+- **`--opacity <n>`, `--padding <n>`, and `--output <relpath>` flags for `purgetss images`.** Three CLI-only per-asset transformations. `--opacity` multiplies the alpha channel of every generated density (0–100, integer). `--padding` shrinks the rendered image inside each density canvas with symmetric transparent borders (0–40%). `--output` overrides basename + subpath relative to the images output root (single-file source only; no extension, no absolute paths, no `..`). All three preserve the multi-density plural-output convention. Combines naturally for placeholder images: `purgetss images purgetss/brand/logo.svg --opacity 30 --padding 15 --output 'logos/default' --format png`.
+- **`brand --padding <n>` shortcut bug fix.** Pre-existing bug: help text and docs described `--padding` as a shortcut that "sets BOTH Android paddings to the same value", but only `androidAdaptivePadding` read the shortcut from the fallback chain — `androidLegacyPadding` skipped it. `purgetss brand --padding 17` actually produced `androidAdaptive=17, androidLegacy=10` silently. Fix adds the missing fallback so `--padding` now sets both Android paddings to the same value as documented.
+- **`purgetss images --format png` now writes truecolor RGBA, not palette-quantized PNG-8.** Passing `quality` to Sharp's `.png()` was silently triggering palette mode, banding subtle gradients in logos, placeholders, and any image with smooth color transitions. Drop of one parameter (`quality` is meaningless for PNG anyway — only `compressionLevel` matters, and that stays at 9 lossless). Brand outputs (icons, splash, marketplace) were never affected because their generators don't pass `quality` to `.png()`.
+
 ### 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)`).
+- **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)`), square 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.

package/bin/purgetss

@@ -76,6 +76,7 @@ program
       }
     } catch (error) {
       console.error(chalk.red('Error running command:'), error.message)
+      if (process.env.PURGETSS_DEBUG) console.error(error.stack)
       process.exit(1)
     }
   })
@@ -267,6 +268,7 @@ Logos auto-discovered from ${chalk.cyan('purgetss/brand/')}:
   ${chalk.yellow('logo-dark.{svg,png}')}     optional — iOS 18+ dark variant
   ${chalk.yellow('logo-tinted.{svg,png}')}   optional — iOS 18+ tinted variant
   ${chalk.yellow('logo-splash.{svg,png}')}   optional — Android 12+ splash icon override
+  ${chalk.yellow('logo-feature.{svg,png}')}  optional — Google Play Feature Graphic override
 
 Defaults come from the ${chalk.cyan('brand:')} section in ${chalk.cyan('purgetss/config.cjs')}.
 The recommended workflow is: put files in ${chalk.cyan('purgetss/brand/')}, then only use config/CLI for overrides.
@@ -276,6 +278,7 @@ 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('MarketplaceArtworkFeature.png')}                              Google Play Feature Graphic (1024×500)
   ${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
@@ -298,6 +301,8 @@ Examples:
   ${chalk.cyan('purgetss brand')} --bg-color "#0B1326"                      # override config bg
   ${chalk.cyan('purgetss brand')} --android-adaptive-padding 22             # more breathing room for adaptive icons
   ${chalk.cyan('purgetss brand')} --icon-logo app-icon.svg                  # separate square Android icon
+  ${chalk.cyan('purgetss brand')} --feature-logo banner.svg                 # custom Feature Graphic logo
+  ${chalk.cyan('purgetss brand')} --feature-graphic-padding 15              # more breathing room on Feature Graphic
   ${chalk.cyan('purgetss brand')} --dark-bg-color "#1C1C1E" --no-tinted     # customize dark, skip tinted
   ${chalk.cyan('purgetss brand')} --dry-run                                 # preview without writing
   ${chalk.cyan('purgetss brand')} --cleanup-legacy --dry-run                # preview legacy cleanup
@@ -307,11 +312,13 @@ Examples:
   .option('--android-adaptive-padding <n>', 'Adaptive icon safe-zone % (default: 19)', (v) => parseInt(v, 10))
   .option('--android-legacy-padding <n>', 'Legacy ic_launcher.png padding % (default: 10)', (v) => parseInt(v, 10))
   .option('--ios-padding <n>', 'iOS aesthetic % (typical 2-6, default: 4)', (v) => parseInt(v, 10))
+  .option('--feature-graphic-padding <n>', 'Feature Graphic vertical % (default: 12)', (v) => parseInt(v, 10))
   .option('--notification', 'Also generate ic_stat_notify.png × 5 densities')
   .option('--splash', 'Also generate Android 12+ splash_icon.png × 5 densities')
   .option('--icon-logo <path>', 'Override the Android launcher icon logo (otherwise purgetss/brand/logo-icon.{svg,png})')
   .option('--monochrome-logo <path>', 'Override the monochrome logo (otherwise purgetss/brand/logo-mono.{svg,png})')
   .option('--splash-logo <path>', 'Override the Android 12+ splash icon logo (otherwise purgetss/brand/logo-splash.{svg,png})')
+  .option('--feature-logo <path>', 'Override the Feature Graphic logo (otherwise purgetss/brand/logo-feature.{svg,png})')
   .option('--dark-bg-color <hex>', 'Opt into opaque dark bg for DefaultIcon-Dark.png (default: transparent per Apple HIG)')
   .option('--dark-logo <path>', 'Override the dark logo (otherwise purgetss/brand/logo-dark.{svg,png})')
   .option('--tinted-logo <path>', 'Override the tinted logo (otherwise purgetss/brand/logo-tinted.{svg,png})')
@@ -370,6 +377,9 @@ Examples:
   ${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')} logo.svg --opacity 50 --format png  # semi-transparent placeholder, all densities
+  ${chalk.cyan('purgetss images')} purgetss/brand/logo.svg --opacity 40 --output 'logos/loading' --format png
+  ${chalk.cyan('purgetss images')} purgetss/brand/logo.png --opacity 30 --padding 15 --output 'logos/default' --format png
   ${chalk.cyan('purgetss images')} --dry-run
 `)
   .option('--android', 'Generate only Android density variants (skip iPhone)')
@@ -377,6 +387,9 @@ Examples:
   .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('--opacity <n>', 'Apply alpha 0-100 to all generated densities (e.g. 50 = 50% transparent)', (v) => parseInt(v, 10))
+  .option('--padding <n>', 'Symmetric padding 0-40% inside each density canvas (shrinks the logo, adds transparent borders)', (v) => parseInt(v, 10))
+  .option('--output <relpath>', 'Override basename + subfolder relative to images/ (single source only, no extension; --format decides ext)')
   .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.8.0
+// PurgeTSS v7.11.1
 // Created by César Estrada
 // https://purgetss.com
 

package/lib/templates/create/index.xml

@@ -3,7 +3,7 @@
     <ScrollView class="vertical mx-4">
       <!-- Header -->
       <Label class="text-center text-3xl font-bold text-white">Welcome to PurgeTSS</Label>
-      <Label class="text-center text-sm text-white">Tailwind-inspired utility classes for Titanium/Alloy</Label>
+      <Label class="text-center text-sm text-white">Utility-first styling for Titanium/Alloy</Label>
 
       <!-- Typography Examples -->
       <Label class="mt-4 text-center text-xl font-semibold text-white">Typography</Label>

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

@@ -36,7 +36,9 @@ module.exports = {
   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? }]
   },
   theme: {
     extend: {}

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "purgetss",
-  "version": "7.9.0",
+  "version": "7.11.1",
   "main": "src/index.js",
   "bin": {
     "purgetss": "bin/purgetss"

package/src/cli/commands/images.js

@@ -44,6 +44,41 @@ export async function images(cliSource, options = {}) {
     }
   }
 
+  let opacity = null
+  if (options.opacity !== undefined) {
+    if (!Number.isFinite(options.opacity) || !Number.isInteger(options.opacity) || options.opacity < 0 || options.opacity > 100) {
+      logger.error(`Invalid --opacity '${options.opacity}'. Must be an integer between 0 and 100.`)
+      process.exit(1)
+    }
+    opacity = options.opacity
+  }
+
+  let padding = null
+  if (options.padding !== undefined) {
+    if (!Number.isFinite(options.padding) || !Number.isInteger(options.padding) || options.padding < 0 || options.padding > 40) {
+      logger.error(`Invalid --padding '${options.padding}'. Must be an integer between 0 and 40.`)
+      process.exit(1)
+    }
+    padding = options.padding
+  }
+
+  let outputRelpath = null
+  if (options.output !== undefined && options.output !== null && options.output !== '') {
+    const raw = String(options.output)
+    if (path.isAbsolute(raw)) {
+      logger.error(`Invalid --output '${raw}'. Must be a relative path inside the project images folder, not absolute.`)
+      process.exit(1)
+    }
+    const segments = raw.split(/[\\/]/)
+    if (segments.includes('..')) {
+      logger.error(`Invalid --output '${raw}'. '..' segments are not allowed (must stay inside the project images folder).`)
+      process.exit(1)
+    }
+    // Strip any trailing extension — --format (or source ext) decides actual extension.
+    const parsed = path.parse(raw)
+    outputRelpath = parsed.dir ? path.join(parsed.dir, parsed.name) : parsed.name
+  }
+
   const format = options.format ?? cfg.format ?? null
   if (format && !VALID_FORMATS.has(format.toLowerCase())) {
     logger.error(`Invalid --format '${format}'. Valid: ${[...VALID_FORMATS].join(', ')}`)
@@ -65,9 +100,13 @@ export async function images(cliSource, options = {}) {
       format: format ? format.toLowerCase() : null,
       quality: options.quality ?? cfg.quality ?? 85,
       baseWidth: options.width ?? null,
+      opacity,
+      padding,
+      outputRelpath,
       dryRun: Boolean(options.dryRun),
       yes: Boolean(options.yes),
-      confirmOverwrites: cfg.confirmOverwrites !== false
+      confirmOverwrites: cfg.confirmOverwrites !== false,
+      filesOverrides: Array.isArray(cfg.files) ? cfg.files : []
     })
   } catch (err) {
     logger.error(err.message)
@@ -113,7 +152,7 @@ function printMissingSourceHelp(projectRoot) {
   logger.error('No source images found.')
   console.log()
   console.log(`  Expected images inside ${chalk.cyan(rel(imagesDir) + '/')}.`)
-  console.log(`  The folder already exists — drop your images into it (subdirectories are preserved):`)
+  console.log('  The folder already exists — drop your images into it (subdirectories are preserved):')
   console.log(`     ${chalk.cyan('cp my-ui-asset.png ' + rel(imagesDir) + '/')}`)
   console.log()
   console.log('  Alternatives:')

package/src/cli/commands/purge.js

@@ -32,6 +32,7 @@ import { getConfigOptions, getConfigFile, ensureConfig } from '../../shared/conf
 
 // Import purger functions from core modules
 import { processControllers } from '../../core/analyzers/class-extractor.js'
+import { runSvgPipeline } from '../../core/svg/index.js'
 import { purgeTailwind } from '../../core/purger/tailwind-purger.js'
 import { flushSemanticColors } from '../../shared/semantic-helpers.js'
 import {
@@ -667,7 +668,7 @@ function saveFile(file, data) {
  * @param {Object} options - Command options
  * @returns {boolean} - Success status
  */
-export function purgeClasses(options) {
+export async function purgeClasses(options) {
   // Initialize configOptions first (includes auto-migration)
   configOptions = getConfigOptions()
 
@@ -676,6 +677,9 @@ export function purgeClasses(options) {
   }
 
   purgingDebug = options.debug
+  // Propagate to the logger module so localFinish (cli-helpers.js) sees it.
+  // The local `purgingDebug` is still needed for the purger callees below.
+  setDebugMode(options.debug)
 
   const recentlyCreated = makeSureFileExists(projectsAppTSS)
 
@@ -696,7 +700,7 @@ export function purgeClasses(options) {
       try {
         uniqueClasses = getUniqueClasses()
 
-        // Pre-validate class syntax. Halts on inverted negatives, Tailwind
+        // Pre-validate class syntax. Halts on inverted negatives, square
         // brackets, empty parens, etc. — but NOT on generic unknown classes
         // (those fall through silently to "// Unused or unsupported classes").
         validateClassSyntax({
@@ -739,6 +743,15 @@ export function purgeClasses(options) {
 
       logger.file('app.tss')
 
+      // Post-step: compile SVG references found in views/controllers into
+      // multi-density PNGs sized from the just-resolved app.tss classes.
+      await runSvgPipeline({
+        tssContent: tempPurged,
+        viewPaths: getViewPaths(),
+        controllerPaths: getControllerPaths(),
+        logger
+      })
+
       finish()
     } finally {
       flushSemanticColors()

package/src/cli/utils/cli-helpers.js

@@ -45,15 +45,25 @@ export function localStart() {
 }
 
 /**
- * Finish local timer and log execution time (only in debug mode)
- * Maintains exact same logic as original localFinish() function
+ * Finish local timer and log execution time (only in debug mode).
  *
- * @param {string} customMessage - Custom message to display
+ * Pass an empty string to print only the timing (without re-emitting the
+ * label) — useful when the caller already showed the section title via
+ * `logger.info` before calling `localStart()`. Anything else is printed
+ * verbatim with the timing appended.
+ *
+ * @param {string} customMessage - Label to print alongside the timing, or
+ *   `''` for timing-only mode.
  */
 export function localFinish(customMessage = 'Finished purging in') {
   const localEndTime = new Date(new Date() - localStartTime)
-  if (getDebugMode()) {
-    logger.info(customMessage, chalk.green(`${localEndTime.getSeconds()}s ${localEndTime.getMilliseconds()}ms`))
+  if (!getDebugMode()) return
+  const timing = chalk.green(`${localEndTime.getSeconds()}s ${localEndTime.getMilliseconds()}ms`)
+  if (customMessage === '') {
+    // Timing-only mode: caller already printed the label.
+    logger.info(timing)
+  } else {
+    logger.info(customMessage, timing)
   }
 }
 

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

@@ -6,7 +6,7 @@
  * authoring mistakes:
  *
  *   - Inverted negative sign:  top-(-10)   → -top-(10)
- *   - Tailwind-style brackets: top-[10px]  → top-(10px)
+ *   - Square brackets:         top-[10px]  → top-(10px)
  *   - Empty parentheses:       wh-()       → wh-(<value>)
  *   - Whitespace in parens:    wh-( 200 )  → wh-(200)
  *   - Redundant px units:      top-(10px)  → top-(10)
@@ -47,11 +47,11 @@ const detectors = [
   },
 
   // top-[10px] → top-(10)
-  function detectTailwindBrackets(className) {
+  function detectSquareBrackets(className) {
     if (!className.includes('[') && !className.includes(']')) return null
     const fixed = className.replace(/\[/g, '(').replace(/\]/g, ')')
     return {
-      issue: 'Tailwind-style brackets "[ ]" are not supported',
+      issue: 'Square brackets "[ ]" are not supported',
       suggestion: `Use parentheses instead: ${chalk.green(`"${fixed}"`)}`
     }
   },

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
+}