purgetss 7.7.1 → 7.11.1

package/src/core/svg/index.js

@@ -0,0 +1,215 @@
+/**
+ * PurgeTSS - SVG image pipeline (orchestrator)
+ *
+ * Post-step of the regular purge. Once `app.tss` is finalized, this module:
+ *
+ *   1. Parses app.tss into a class → props map.
+ *   2. Scans every view (.xml) and controller (.js) for SVG references paired
+ *      with their classes / `class=""` attribute.
+ *   3. Reduces each SVG to a single resolved `{ widthDp, heightDp }` (max of
+ *      every reference; falls back to viewBox aspect for height when `h-*` is
+ *      missing or non-numeric).
+ *   4. Upserts `images.files` in config.cjs (never decreases — manual overrides
+ *      always win).
+ *   5. Generates the iOS @1x/@2x/@3x and Android mdpi…xxxhdpi PNGs from the
+ *      same SVG master, using a hash-based cache to skip unchanged inputs.
+ *
+ * The pipeline never rewrites XML/Controller files. Titanium falls back to the
+ * generated PNGs at runtime when an `image="/.../foo.svg"` reference resolves
+ * against a `.png` with the same basename in the platform assets folder.
+ *
+ * @fileoverview Compile-time SVG → multi-density PNG pipeline for Titanium
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import {
+  cwd,
+  projectsPurge_TSS_Images_Folder  
+} from '../../shared/constants.js'
+import { detectProjectType } from '../branding/tiapp-reader.js'
+import { genAndroidScales, genIphoneScales, ANDROID_SCALES, IPHONE_SCALES } from '../images/gen-scales.js'
+import { parseTssMap } from './tss-reader.js'
+import { deriveDimensions } from './derive-dimensions.js'
+import { syncConfigImages } from './sync-images.js'
+import { loadCache, saveCache, hashFile, isCacheHit, makeCacheEntry } from './cache.js'
+import { extractSvgRefsFromXml } from '../analyzers/class-extractor.js'
+import { extractSvgRefsFromController } from '../analyzers/controller-svg-refs.js'
+import { getConfigFile } from '../../shared/config-manager.js'
+
+/**
+ * Run the SVG image pipeline as a post-step of `purgetss` (purge command).
+ *
+ * Silent (no-op) when no SVG references are found. Logs progress at each step
+ * so the user can trace cache hits, dimension changes, and skipped SVGs.
+ *
+ * @param {Object} args
+ * @param {string} args.tssContent - Final purged TSS string (in memory).
+ * @param {string[]} args.viewPaths - Absolute paths to view .xml files.
+ * @param {string[]} args.controllerPaths - Absolute paths to controller .js files.
+ * @param {Object} args.logger - Logger with `.info/.warning/.success/.file`.
+ * @returns {Promise<void>}
+ */
+export async function runSvgPipeline({ tssContent, viewPaths, controllerPaths, logger }) {
+   
+  const imagesFolder = projectsPurge_TSS_Images_Folder
+  if (!fs.existsSync(imagesFolder)) return
+
+  const refsBySvg = collectRefs({ viewPaths, controllerPaths })
+  if (refsBySvg.size === 0) return
+
+  logger.info('Resolving SVG dimensions from app.tss...')
+  const tssMap = parseTssMap(tssContent)
+  const derived = await deriveDimensions({ refsBySvg, tssMap, imagesFolder, logger })
+  if (derived.size === 0) return
+
+  // Sync config.cjs first so external runs (`purgetss images`) reflect the
+  // current resolution even if the cache short-circuits actual generation.
+  // The returned `effective` map merges derived values with any pre-existing
+  // manual overrides (config wins when its width is higher). The actual file
+  // write is gated by `images.autoSync` so devs who prefer hand-managed config
+  // can opt out.
+  const autoSync = readAutoSyncFlag()
+  const { stats, effective } = syncConfigImages(derived, { logger, write: autoSync })
+  if (autoSync && (stats.inserted || stats.updated)) {
+    logger.info(
+      `config.cjs > images.files: ${stats.inserted} inserted, ${stats.updated} updated, ${stats.untouched} untouched`
+    )
+  } else if (!autoSync && (stats.inserted || stats.updated)) {
+    logger.info(
+      `images.autoSync is off — would have ${stats.inserted ? `inserted ${stats.inserted}` : ''}${stats.inserted && stats.updated ? ', ' : ''}${stats.updated ? `updated ${stats.updated}` : ''} entry/entries in config.cjs > images.files`
+    )
+  }
+
+  await generatePngs({ derived: effective, imagesFolder, logger })
+}
+
+function collectRefs({ viewPaths, controllerPaths }) {
+  const refsBySvg = new Map()
+  const push = (src, classes) => {
+    const relPath = normalizeSvgSrc(src)
+    if (!relPath) return
+    if (!refsBySvg.has(relPath)) refsBySvg.set(relPath, [])
+    refsBySvg.get(relPath).push({ classes })
+  }
+
+  for (const file of viewPaths) {
+    const text = fs.readFileSync(file, 'utf8')
+    if (!text) continue
+    let refs
+    try {
+      refs = extractSvgRefsFromXml(text, file)
+    } catch {
+      // Malformed XML is reported by the regular purge path already; the SVG
+      // pipeline silently skips so we don't double-error on the same file.
+      continue
+    }
+    for (const ref of refs) push(ref.src, ref.classes)
+  }
+
+  for (const file of controllerPaths) {
+    const text = fs.readFileSync(file, 'utf8')
+    if (!text) continue
+    const refs = extractSvgRefsFromController(text)
+    for (const ref of refs) push(ref.src, ref.classes)
+  }
+
+  return refsBySvg
+}
+
+// Map `/images/logos/foo.svg` → `logos/foo.svg`. Anything outside the
+// `/images/` namespace is unknown to this pipeline and returns null.
+function normalizeSvgSrc(src) {
+  if (typeof src !== 'string') return null
+  const stripped = src.replace(/^\/+/, '')
+  if (!stripped.startsWith('images/')) return null
+  return stripped.slice('images/'.length)
+}
+
+async function generatePngs({ derived, imagesFolder, logger }) {
+  const projectType = detectProjectType(cwd)
+  const { androidBaseDir, iphoneBaseDir } = resolveOutputDirs(cwd, projectType)
+  const cache = loadCache()
+  let generated = 0
+  let cached = 0
+
+  // The SVG pipeline always emits PNG, even if `images.format` is set to
+  // 'webp' / 'jpeg' / etc. for the standalone `purgetss images` command.
+  // Verified empirically: Titanium's `image="/.../foo.svg"` runtime fallback
+  // resolves to `.png` only — `.webp` and other formats are not picked up.
+  // Honoring images.format here would silently generate files Titanium can't
+  // load. The standalone command keeps respecting format for raster sources
+  // (where the reference uses the actual extension).
+  for (const [relPath, { widthDp, heightDp }] of derived) {
+    const absSvg = path.join(imagesFolder, relPath)
+    const relForOutput = swapExt(relPath, '.png')
+    const targets = enumerateTargets({ relForOutput, androidBaseDir, iphoneBaseDir })
+
+    const svgHash = hashFile(absSvg)
+    if (isCacheHit(cache[relPath], svgHash, widthDp, heightDp, targets)) {
+      cached++
+      continue
+    }
+
+    try {
+      await genAndroidScales(absSvg, relPath, androidBaseDir, { baseWidth: widthDp, baseHeight: heightDp })
+      await genIphoneScales(absSvg, relPath, iphoneBaseDir, { baseWidth: widthDp, baseHeight: heightDp })
+    } catch (err) {
+      logger.warning(`✗ ${relPath}: ${err.message}`)
+      continue
+    }
+
+    cache[relPath] = makeCacheEntry(svgHash, widthDp, heightDp, targets)
+    generated++
+    logger.info(`✓ ${relPath} → ${widthDp}×${heightDp}dp`)
+  }
+
+  saveCache(cache)
+  if (generated || cached) {
+    logger.info(`SVG pipeline: ${generated} generated, ${cached} cached.`)
+  }
+}
+
+function resolveOutputDirs(projectRoot, projectType) {
+  if (projectType === 'classic') {
+    return {
+      androidBaseDir: path.join(projectRoot, 'Resources', 'android', 'images'),
+      iphoneBaseDir: path.join(projectRoot, 'Resources', 'iphone', 'images')
+    }
+  }
+  return {
+    androidBaseDir: path.join(projectRoot, 'app', 'assets', 'android', 'images'),
+    iphoneBaseDir: path.join(projectRoot, 'app', 'assets', 'iphone', 'images')
+  }
+}
+
+function enumerateTargets({ relForOutput, androidBaseDir, iphoneBaseDir }) {
+  const out = []
+  const parsed = path.parse(relForOutput)
+  for (const { name } of ANDROID_SCALES) {
+    out.push(path.join(androidBaseDir, name, relForOutput))
+  }
+  for (const { suffix } of IPHONE_SCALES) {
+    out.push(path.join(iphoneBaseDir, parsed.dir, `${parsed.name}${suffix}${parsed.ext}`))
+  }
+  return out
+}
+
+function swapExt(relPath, newExt) {
+  const parsed = path.parse(relPath)
+  return path.join(parsed.dir, parsed.name + newExt)
+}
+
+// Read `images.autoSync` from config; defaults to true. The SVG pipeline
+// ignores `images.format` / `images.quality` on purpose — see the comment in
+// generatePngs about Titanium's .svg → .png-only fallback.
+function readAutoSyncFlag() {
+  try {
+    const cfg = getConfigFile()
+    if (cfg && typeof cfg.images === 'object' && cfg.images.autoSync === false) {
+      return false
+    }
+  } catch { /* fall through to default */ }
+  return true
+}

package/src/core/svg/resolve-classes.js

@@ -0,0 +1,46 @@
+/**
+ * PurgeTSS - Class cascade resolver for the SVG pipeline
+ *
+ * Given an ordered list of classes (as they appear in `class=""` / `classes:`)
+ * and the class→props map produced by tss-reader, apply later-wins cascading
+ * to return the final width and height.
+ *
+ * V1 limitations (out of scope, see plan):
+ *   - Tag selectors (`'View': { ... }`) not applied
+ *   - ID selectors (`'#foo': { ... }`) not applied
+ *   - Platform/device modifiers (`'[platform=ios]'`) not applied
+ *
+ * If a project needs any of these, add the SVG to `images.files` manually.
+ *
+ * @fileoverview Cascade resolver: classes[] + tssMap → { width, height }
+ * @author César Estrada
+ */
+
+/**
+ * Resolve width/height for a list of classes by applying later-wins cascading.
+ * Classes that don't exist in the map are skipped silently — they may be
+ * unknown utilities, typos, or classes registered via tag/ID selectors that
+ * V1 doesn't see.
+ *
+ * Returned value shape per dimension:
+ *   - number    → resolved to a finite dp value
+ *   - 'auto'    → resolved to Ti.UI.SIZE
+ *   - 'fill'    → resolved to Ti.UI.FILL
+ *   - 'percent' → resolved to a percentage / non-numeric (can't size a PNG)
+ *   - null      → no class in the list set this dimension
+ *
+ * @param {string[]} classes - Class tokens in source order.
+ * @param {Map} tssMap - Output of parseTssMap().
+ * @returns {{ width: number|'auto'|'fill'|'percent'|null, height: number|'auto'|'fill'|'percent'|null }}
+ */
+export function resolveDimensions(classes, tssMap) {
+  let width = null
+  let height = null
+  for (const cls of classes) {
+    const entry = tssMap.get(cls)
+    if (!entry) continue
+    if (entry.width !== undefined) width = entry.width
+    if (entry.height !== undefined) height = entry.height
+  }
+  return { width, height }
+}

package/src/core/svg/sync-images.js

@@ -0,0 +1,278 @@
+/**
+ * PurgeTSS - config.cjs sync for SVG-derived dimensions
+ *
+ * Updates `images.files` inside the user's purgetss/config.cjs to reflect the
+ * dimensions resolved from app.tss. Companion to setConfigProperty (which only
+ * handles primitives) — this one knows how to upsert into an array of objects
+ * while preserving the user's formatting, comments, and any manual overrides.
+ *
+ * Policy (see plan):
+ *   - Entry missing      → insert `{ filename, width [, height] }`.
+ *   - Entry present, width < derived → bump width (and height) to derived.
+ *   - Entry present, width >= derived → leave alone. Manual overrides win.
+ *
+ * String-based mutation chosen over `recast` to avoid adding a heavy dep —
+ * config.cjs has a controlled shape since `purgetss init` writes it. If we
+ * can't safely locate the section we no-op and warn, mirroring setConfigProperty.
+ *
+ * @fileoverview Upsert image entries in config.cjs while preserving formatting
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import { projectsConfigJS } from '../../shared/constants.js'
+
+/**
+ * Apply the derived dimensions to `images.files` in the user's config.cjs and
+ * return the effective per-SVG dimensions after the sync (i.e. the max of the
+ * derived value and any pre-existing manual override). Callers should drive
+ * PNG generation from the returned `effective` map so manual overrides — like
+ * pinning a width above what the class cascade resolves — produce PNGs at the
+ * higher resolution.
+ *
+ * @param {Map<string, { widthDp: number, heightDp: number }>} derived
+ *   Keyed by SVG relpath (matches the `filename` field stored in config).
+ * @param {Object} [opts]
+ * @param {Object} [opts.logger] - Logger with `.warning(msg)` / `.info(msg)`.
+ * @param {boolean} [opts.write=true] - When false, computes the effective map
+ *   without mutating config.cjs (for users who keep `images.autoSync: false`
+ *   and prefer to manage `images.files` by hand).
+ * @returns {{
+ *   stats: { updated: number, inserted: number, untouched: number },
+ *   effective: Map<string, { widthDp: number, heightDp: number }>
+ * }}
+ */
+export function syncConfigImages(derived, { logger, write = true } = {}) {
+  const stats = { updated: 0, inserted: 0, untouched: 0 }
+  const effective = new Map()
+  if (!fs.existsSync(projectsConfigJS)) {
+    logger?.warning('config.cjs not found — skipping SVG dimensions sync.')
+    // Without config we still want PNGs generated at the derived size — copy
+    // the derived map through verbatim.
+    for (const [k, v] of derived) effective.set(k, { ...v })
+    return { stats, effective }
+  }
+
+  let source = fs.readFileSync(projectsConfigJS, 'utf8')
+
+  for (const [relPath, { widthDp, heightDp }] of derived) {
+    const filename = toFilename(relPath)
+    const existing = findEntry(source, filename)
+    if (existing) {
+      // autoSync ON (this code path): config mirrors the current run. The
+      // derived numbers already reflect max() across every reference to this
+      // SVG in this run (see derive-dimensions.js) — sync just writes them
+      // through. No second max against the previous run, which would freeze
+      // shrunk classes at their old larger size. Users who want to pin a
+      // value by hand should set images.autoSync: false (write=false), which
+      // skips this file write entirely.
+      const desired = {}
+      if (widthDp != null) desired.width = widthDp
+      if (heightDp != null) desired.height = heightDp
+
+      const widthSame = (existing.width ?? null) === (desired.width ?? null)
+      const heightSame = (existing.height ?? null) === (desired.height ?? null)
+      if (widthSame && heightSame) {
+        stats.untouched++
+      } else {
+        source = replaceEntry(source, existing, filename, desired)
+        stats.updated++
+      }
+      effective.set(relPath, { widthDp: desired.width ?? null, heightDp: desired.height ?? null })
+    } else {
+      const entry = {}
+      if (widthDp != null) entry.width = widthDp
+      if (heightDp != null) entry.height = heightDp
+      const next = insertEntry(source, filename, entry)
+      if (next === null) {
+        logger?.warning(`Could not insert ${filename} into images.files (section missing or unreadable).`)
+        effective.set(relPath, { widthDp, heightDp })
+        continue
+      }
+      source = next
+      stats.inserted++
+      effective.set(relPath, { widthDp, heightDp })
+    }
+  }
+
+  // Only write when we actually mutated `source`. The loop above only mutates
+  // it inside the inserted/updated branches; `untouched` leaves it byte-identical
+  // to disk. Skipping the write avoids touching the mtime, which other parts of
+  // PurgeTSS use to invalidate utilities.tss — gratuitous mtime bumps would
+  // trigger needless rebuilds. Derive + effective + the SVG cache still run
+  // either way, so generation/validation is unaffected.
+  if (write && (stats.inserted > 0 || stats.updated > 0)) {
+    fs.writeFileSync(projectsConfigJS, source, 'utf8')
+  }
+  return { stats, effective }
+}
+
+function toFilename(relPath) {
+  // Stored form mirrors the `purgetss images` convention: `images/<subpath>/<name>.svg`
+  return `images/${relPath.replace(/^\/+/, '')}`
+}
+
+// Locate an entry like `{ filename: 'images/foo.svg', width: 128 }`. Tolerates
+// keys in any order and either quoting style.
+function findEntry(source, filename) {
+  const escaped = filename.replace(/[/.[\]()*+?^$|\\]/g, '\\$&')
+  const re = new RegExp(
+    `\\{[^{}]*?\\bfilename\\s*:\\s*['"\`]${escaped}['"\`][^{}]*?\\}`,
+    'g'
+  )
+  const matches = [...source.matchAll(re)]
+  if (matches.length === 0) return null
+  const match = matches[0]
+  const body = match[0]
+  const width = readNumber(body, 'width')
+  const height = readNumber(body, 'height')
+  return { match: body, index: match.index, width, height }
+}
+
+function readNumber(body, key) {
+  const m = body.match(new RegExp(`\\b${key}\\s*:\\s*(\\d+)`))
+  return m ? Number(m[1]) : null
+}
+
+function replaceEntry(source, existing, filename, desired) {
+  const newEntry = renderEntry(filename, desired)
+  return source.slice(0, existing.index) + newEntry + source.slice(existing.index + existing.match.length)
+}
+
+function renderEntry(filename, { width, height }) {
+  const parts = [`filename: '${filename}'`]
+  if (width != null) parts.push(`width: ${width}`)
+  if (height != null) parts.push(`height: ${height}`)
+  return `{ ${parts.join(', ')} }`
+}
+
+// Insert a new entry into the images.files array. Returns the mutated source
+// string, or null if the array can't be located/created safely.
+function insertEntry(source, filename, entry) {
+  // First pass: make sure the array exists; this may mutate `source` to inject
+  // `files: []` into the `images` section when missing.
+  const ensured = ensureFilesArray(source)
+  if (ensured === null) return null
+  source = ensured
+
+  const filesArr = locateFilesArray(source)
+  if (!filesArr) return null
+
+  const { openIdx, closeIdx, indent } = filesArr
+  const inner = source.slice(openIdx + 1, closeIdx)
+  const newEntry = renderEntry(filename, entry)
+
+  const innerTrimmed = inner.replace(/\s+$/, '')
+  if (innerTrimmed.trim().length === 0) {
+    // Empty array: rewrite as multi-line with one entry.
+    const replacement = `[\n${indent}  ${newEntry}\n${indent}]`
+    return source.slice(0, openIdx) + replacement + source.slice(closeIdx + 1)
+  }
+
+  // Non-empty: ensure the previous entry has a trailing comma and append a
+  // new line with the same indent as siblings (heuristic: 2-space extra).
+  const lines = innerTrimmed.split('\n')
+  const lastIdx = lines.length - 1
+  const lastLine = lines[lastIdx]
+  const stripped = lastLine.replace(/\s+$/, '')
+  if (!stripped.endsWith(',') && !stripped.endsWith('[')) {
+    lines[lastIdx] = stripped + ','
+  }
+  const newInner = lines.join('\n') + `\n${indent}  ${newEntry}\n${indent}`
+  return source.slice(0, openIdx + 1) + newInner + source.slice(closeIdx)
+}
+
+// If `images.files` is missing, inject an empty `files: []` immediately before
+// the section's closing brace, preserving the user's indentation.
+function ensureFilesArray(source) {
+  const section = matchImagesSection(source)
+  if (!section) return null
+  if (/(\n\s*)files\s*:\s*\[/.test(section.body)) return source
+
+  const insertion = `\n${section.indent}  files: []`
+  const closingIdx = section.end - 1 // position of '}'
+  const before = source.slice(0, closingIdx)
+  const after = source.slice(closingIdx)
+  // Drop trailing horizontal whitespace + newlines so the new line lands flush
+  // against the previous sibling line.
+  const trimmed = before.replace(/[ \t]+$/, '').replace(/\n+$/, '')
+  return appendTrailingCommaIfNeeded(trimmed) + insertion + '\n' + section.indent + after
+}
+
+// Ensure the previous property line is followed by a comma so the appended
+// line parses. Honors trailing `// comments` by placing the comma between the
+// value and the comment, never inside the comment itself.
+function appendTrailingCommaIfNeeded(text) {
+  const lastLineStart = text.lastIndexOf('\n') + 1
+  const head = text.slice(0, lastLineStart)
+  const lastLine = text.slice(lastLineStart)
+  // Split off a trailing `// comment` (with optional leading whitespace).
+  const commentMatch = lastLine.match(/^(.*?)(\s*\/\/.*)$/)
+  const valuePart = (commentMatch ? commentMatch[1] : lastLine).replace(/[ \t]+$/, '')
+  const commentPart = commentMatch ? commentMatch[2] : ''
+  if (!valuePart || valuePart.endsWith(',') || valuePart.endsWith('{')) return text
+  return head + valuePart + ',' + commentPart
+}
+
+function matchImagesSection(source) {
+  // Locate the `images:` key, then bracket-balance to its matching `}`.
+  // The previous lazy-regex approach mis-identified the closing brace whenever
+  // `images: { ... }` was written on a single line (no `\n indent }` to anchor
+  // on) — it swallowed sibling sections and dropped `files: []` into whichever
+  // nested block happened to close first. Bracket-balancing works regardless
+  // of formatting, matching what the rest of PurgeTSS expects from config.cjs.
+  const m = source.match(/^([ \t]*)images\s*:\s*\{/m)
+  if (!m) return null
+
+  const openIdx = m.index + m[0].length - 1
+  const closeIdx = matchBracket(source, openIdx, '{', '}')
+  if (closeIdx === -1) return null
+
+  return {
+    start: m.index,
+    end: closeIdx + 1,
+    indent: m[1],
+    body: source.slice(openIdx + 1, closeIdx)
+  }
+}
+
+// Find the `files: [ ... ]` array inside the `images: { ... }` section.
+function locateFilesArray(source) {
+  const section = matchImagesSection(source)
+  if (!section) return null
+
+  const filesMatch = section.body.match(/(\n\s*)files\s*:\s*\[/)
+  if (!filesMatch) return null
+
+  const arrayKeyStart = section.start + section.body.indexOf(filesMatch[0]) + filesMatch[1].length
+  const openIdx = source.indexOf('[', arrayKeyStart)
+  if (openIdx === -1) return null
+  const closeIdx = matchBracket(source, openIdx, '[', ']')
+  if (closeIdx === -1) return null
+
+  const lineStart = source.lastIndexOf('\n', arrayKeyStart) + 1
+  const indent = source.slice(lineStart, arrayKeyStart).match(/^[ \t]*/)[0]
+
+  return { openIdx, closeIdx, indent }
+}
+
+function matchBracket(source, startIdx, open, close) {
+  let depth = 0
+  let inSingle = false
+  let inDouble = false
+  let inBacktick = false
+  for (let i = startIdx; i < source.length; i++) {
+    const c = source[i]
+    if (c === '\'' && !inDouble && !inBacktick) inSingle = !inSingle
+    else if (c === '"' && !inSingle && !inBacktick) inDouble = !inDouble
+    else if (c === '`' && !inSingle && !inDouble) inBacktick = !inBacktick
+    else if (!inSingle && !inDouble && !inBacktick) {
+      if (c === open) depth++
+      else if (c === close) {
+        depth--
+        if (depth === 0) return i
+      }
+    }
+  }
+  return -1
+}

package/src/core/svg/tss-reader.js

@@ -0,0 +1,134 @@
+/**
+ * PurgeTSS - TSS reader for the SVG pipeline
+ *
+ * Lightweight parser for the controlled TSS output PurgeTSS generates. Used by
+ * the SVG image pipeline to resolve final width/height per class after a
+ * regular purge run. NOT a general-purpose TSS parser — only the shapes the
+ * purger emits are recognized.
+ *
+ * Recognized line shape:
+ *   '.classname': { prop: value, prop: value }
+ *
+ * Tag selectors (e.g. 'View': { ... }, 'ImageView[platform=ios]': { ... }) and
+ * '#id': { ... } selectors are skipped — the SVG pipeline resolves only by
+ * class cascade in V1.
+ *
+ * @fileoverview Class → properties map extracted from purged app.tss
+ * @author César Estrada
+ */
+
+const CLASS_LINE = /^\s*'\.([^']+)'\s*:\s*\{([^}]*)\}\s*$/
+
+/**
+ * Parse the controlled TSS string emitted by the purger into a class → props
+ * map. Values are returned in a normalized form:
+ *
+ *   - number             → finite numeric value (e.g. 128)
+ *   - 'auto'             → Ti.UI.SIZE
+ *   - 'fill'             → Ti.UI.FILL
+ *   - 'percent'          → percentage or any other non-resolvable value
+ *
+ * Only the `width` and `height` properties are normalized; other props are
+ * captured verbatim as the raw RHS string (callers don't currently need them).
+ *
+ * @param {string} tssContent - The full purged TSS (in-memory string).
+ * @returns {Map<string, { width?: number|'auto'|'fill'|'percent', height?: number|'auto'|'fill'|'percent', _raw: string }>}
+ */
+export function parseTssMap(tssContent) {
+  const map = new Map()
+  if (typeof tssContent !== 'string' || !tssContent) return map
+
+  const lines = tssContent.split(/\r?\n/)
+  for (const line of lines) {
+    const stripped = stripLineComment(line)
+    const match = stripped.match(CLASS_LINE)
+    if (!match) continue
+
+    const className = match[1]
+    const body = match[2]
+    const props = parsePropBody(body)
+    map.set(className, { ...props, _raw: body.trim() })
+  }
+  return map
+}
+
+// Drop trailing `// comment` so it doesn't break the brace-matching regex.
+function stripLineComment(line) {
+  let inSingle = false
+  let inDouble = false
+  for (let i = 0; i < line.length - 1; i++) {
+    const c = line[i]
+    if (c === '\'' && !inDouble) inSingle = !inSingle
+    else if (c === '"' && !inSingle) inDouble = !inDouble
+    else if (c === '/' && line[i + 1] === '/' && !inSingle && !inDouble) {
+      return line.slice(0, i)
+    }
+  }
+  return line
+}
+
+function parsePropBody(body) {
+  const out = {}
+  for (const pair of splitTopLevelCommas(body)) {
+    const colon = findTopLevelColon(pair)
+    if (colon === -1) continue
+    const key = pair.slice(0, colon).trim()
+    const value = pair.slice(colon + 1).trim()
+    if (key === 'width' || key === 'height') {
+      out[key] = normalizeDimensionValue(value)
+    }
+  }
+  return out
+}
+
+function splitTopLevelCommas(body) {
+  const out = []
+  let depth = 0
+  let inSingle = false
+  let inDouble = false
+  let last = 0
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i]
+    if (c === '\'' && !inDouble) inSingle = !inSingle
+    else if (c === '"' && !inSingle) inDouble = !inDouble
+    else if (!inSingle && !inDouble) {
+      if (c === '(' || c === '[' || c === '{') depth++
+      else if (c === ')' || c === ']' || c === '}') depth--
+      else if (c === ',' && depth === 0) {
+        out.push(body.slice(last, i))
+        last = i + 1
+      }
+    }
+  }
+  out.push(body.slice(last))
+  return out.filter(s => s.trim().length > 0)
+}
+
+function findTopLevelColon(pair) {
+  let inSingle = false
+  let inDouble = false
+  let depth = 0
+  for (let i = 0; i < pair.length; i++) {
+    const c = pair[i]
+    if (c === '\'' && !inDouble) inSingle = !inSingle
+    else if (c === '"' && !inSingle) inDouble = !inDouble
+    else if (!inSingle && !inDouble) {
+      if (c === '(' || c === '[' || c === '{') depth++
+      else if (c === ')' || c === ']' || c === '}') depth--
+      else if (c === ':' && depth === 0) return i
+    }
+  }
+  return -1
+}
+
+// Recognize: numeric literals, Ti.UI.SIZE/FILL, quoted percentages or other
+// non-numeric strings. Anything else falls into 'percent' (the catch-all for
+// "this can't be turned into a dp number"). The label is historic — it
+// originally only meant "string with %" — keeping it avoids ripple changes.
+function normalizeDimensionValue(raw) {
+  const trimmed = raw.trim()
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed)
+  if (/^Ti\.UI\.SIZE$/i.test(trimmed)) return 'auto'
+  if (/^Ti\.UI\.FILL$/i.test(trimmed)) return 'fill'
+  return 'percent'
+}