purgetss 7.5.3 → 7.6.1

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

@@ -0,0 +1,145 @@
+/**
+ * PurgeTSS - post-gen-notes
+ *
+ * Prints guidance after a successful branding run. Two modes:
+ *   - default (compact): one-line per category + "Next steps" block
+ *   - `--notes` (full):  adds brand color reminder, padding tips, and all
+ *                         tiapp.xml snippets (iOS launch, Android launcher,
+ *                         Android 12+ splash theme, FCM notification tint)
+ *
+ * @fileoverview Post-generation guidance output
+ * @author César Estrada
+ */
+
+import chalk from 'chalk'
+import { logger } from './branding-logger.js'
+
+export function printPostGenNotes(opts) {
+  if (opts.fullNotes) {
+    printFullNotes(opts)
+  } else {
+    printCompactSummary(opts)
+  }
+}
+
+function printCompactSummary(opts) {
+  const { projectType, projectRoot, stagingRoot, bgColor, padding, iosPadding, inPlace } = opts
+
+  logger.section('Summary')
+  logger.bullet(`Background: ${chalk.cyan(bgColor)}`)
+  logger.bullet(`Padding: Android ${chalk.cyan(padding + '%')} / iOS ${chalk.cyan(iosPadding + '%')}`)
+  logger.bullet(`${inPlace ? 'Written in place to' : 'Staged at'}: ${chalk.cyan(inPlace ? projectRoot : stagingRoot)}`)
+
+  logger.section('Next steps')
+  if (inPlace) {
+    logger.bullet(`Preview the new icons in ${chalk.yellow('Preview.app')}.`)
+    logger.bullet(`If something looks wrong: ${chalk.gray('git checkout -- .')}`)
+    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 -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 -R ${stagingRoot}/platform/android/res/. ${projectRoot}/platform/android/res/`))
+    logger.bullet(`Cleanup staging: ${chalk.gray('rm -rf ' + stagingRoot)}`)
+  } else {
+    logger.bullet(`Review ${chalk.cyan(stagingRoot + '/')} and copy files to their final paths manually.`)
+  }
+  console.log()
+  console.log(`Pass ${chalk.yellow('--notes')} to print tiapp.xml snippets + padding tuning guide.`)
+  console.log()
+}
+
+function printFullNotes(opts) {
+  const {
+    projectType, projectRoot, stagingRoot,
+    bgColor, padding, iosPadding, withSplash, withNotification, inPlace
+  } = opts
+
+  const code = (s) => chalk.gray(s)
+  const flag = (s) => chalk.yellow(s)
+  const num = (n) => chalk.cyan(n)
+
+  logger.section('Notes on what was generated')
+  logger.bullet(`Brand color ${chalk.cyan(bgColor)} was baked into Android adaptive background layer`)
+  console.log('    and iOS/marketplace flattened masters (Apple rejects alpha).')
+  logger.bullet(`Android padding:  ${chalk.cyan(padding + '%')}  (logo fills ${100 - 2 * padding}% of each mipmap canvas)`)
+  logger.bullet(`iOS padding:      ${chalk.cyan(iosPadding + '%')}  (logo fills ${100 - 2 * iosPadding}% of DefaultIcon-ios and marketplace art)`)
+
+  console.log()
+  console.log('  If the logo looks cramped: re-run with higher padding')
+  console.log(`      ${flag('--padding 25-30')}       (Android)`)
+  console.log(`      ${flag('--ios-padding 10-14')}   (iOS)`)
+  console.log()
+  console.log('  If the logo looks too small: re-run with lower padding')
+  console.log(`      ${flag('--padding 19')}          (Android spec floor)`)
+  console.log(`      ${flag('--ios-padding 2-3')}     (matches first-party apps like Mail, Safari)`)
+
+  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()
+  console.log(`  ${chalk.yellow('⚠')}  ${chalk.yellow('tiapp.xml <application> tag may be self-closing')}`)
+  console.log('     If yours looks like:')
+  console.log(code('         <application android:icon="@mipmap/ic_launcher" .../>'))
+  console.log('     You must expand it BEFORE adding children:')
+  console.log(code('         <application android:icon="@mipmap/ic_launcher" ...>'))
+  console.log(code('         </application>'))
+
+  console.log()
+  console.log(`  ${num('1.')} ${chalk.cyan('iOS launch background')} — under ${flag('<ios>')} in tiapp.xml:`)
+  console.log(code('      <ios>'))
+  console.log(code('        <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>'))
+  console.log(code(`        <default-background-color>${bgColor}</default-background-color>`))
+  console.log(code('      </ios>'))
+
+  console.log()
+  console.log(`  ${num('2.')} ${chalk.cyan('Android launcher icon')} — under ${flag('<android><manifest><application>')}:`)
+  console.log(code('      <application android:icon="@mipmap/ic_launcher"'))
+  console.log(code('                   android:usesCleartextTraffic="false"/>'))
+
+  if (withSplash) {
+    console.log()
+    console.log(`  ${num('3.')} ${chalk.cyan('Android 12+ splash screen')} — ${chalk.yellow('OPTIONAL, advanced')}`)
+    console.log()
+    console.log('     Titanium SDK 13.x shows a system splash automatically using your')
+    console.log('     launcher icon. For most apps THE DEFAULT IS ENOUGH — do nothing.')
+  }
+
+  if (withNotification) {
+    const colorsDir = projectType === 'classic'
+      ? 'platform/android/res/values'
+      : 'app/platform/android/res/values'
+
+    console.log()
+    console.log(`  ${num('4.')} ${chalk.cyan('FCM notification icon + tint')}`)
+    console.log('     Only needed if you use firebase.cloudmessaging for push.')
+    console.log()
+    console.log(`     Create ${flag(colorsDir + '/colors.xml')} (or merge):`)
+    console.log(code('       <?xml version="1.0" encoding="utf-8"?>'))
+    console.log(code('       <resources>'))
+    console.log(code(`         <color name="notification_tint">${bgColor}</color>`))
+    console.log(code('       </resources>'))
+    console.log()
+    console.log('     Then under <application> in tiapp.xml:')
+    console.log(code('       <meta-data android:name="com.google.firebase.messaging.default_notification_icon"'))
+    console.log(code('                  android:resource="@drawable/ic_stat_notify"/>'))
+    console.log(code('       <meta-data android:name="com.google.firebase.messaging.default_notification_color"'))
+    console.log(code('                  android:resource="@color/notification_tint"/>'))
+  }
+
+  logger.section('Next steps')
+  if (inPlace) {
+    console.log(`  ${num('1.')} Preview in ${flag('Preview.app')} — files were overwritten directly.`)
+    console.log(`  ${num('2.')} If something looks wrong: ${code('git checkout -- .')}`)
+    console.log(`  ${num('3.')} Rebuild: ${code('ti clean && ti build -p android -T emulator')}`)
+  } else {
+    console.log(`  ${num('1.')} Preview the generated icons, then copy to project (see Summary).`)
+    console.log(`  ${num('2.')} Cleanup staging: ${code('rm -rf ' + stagingRoot)}`)
+    console.log(`  ${num('3.')} Rebuild: ${code('ti clean && ti build -p android -T emulator')}`)
+  }
+  console.log()
+}

package/src/core/branding/prepare-master.js

@@ -0,0 +1,108 @@
+/**
+ * PurgeTSS - prepare-master
+ *
+ * Produces two normalized masters from a single input:
+ *
+ *   1. <base>_square.png — 1024×1024 PNG, logo centered in a transparent square
+ *      canvas. Used for iOS DefaultIcon + marketplace artwork.
+ *
+ *   2. <base>_tight.png — logo rasterized at 1024-px max dimension with native
+ *      aspect preserved (no padding). Used for Android adaptive icons so a
+ *      horizontal wordmark fills the safe-zone by width instead of being
+ *      double-padded inside a square.
+ *
+ * Accepts SVG or PNG/JPG/WebP. SVG is rasterized by Sharp at high density,
+ * then downsampled to 1024 for clean high-DPI output.
+ *
+ * @fileoverview Master-image preparation for the branding pipeline
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+import { logger } from './branding-logger.js'
+import { computeSvgDensity, readSvgSafely } from '../../shared/svg-utils.js'
+
+const MAX_DIMENSION = 1024
+
+/**
+ * Prepare dual masters (square + tight) from a single input.
+ * @param {string} inputPath - Path to SVG or PNG master
+ * @param {string} basePath - Output base path (no extension, e.g. /tmp/foo/_master)
+ * @returns {Promise<{square: string, tight: string}>} Paths to both outputs
+ */
+export async function prepareMaster(inputPath, basePath) {
+  const ext = path.extname(inputPath).toLowerCase().slice(1)
+  const squarePath = `${basePath}_square.png`
+  const tightPath = `${basePath}_tight.png`
+
+  fs.mkdirSync(path.dirname(basePath), { recursive: true })
+
+  if (ext === 'svg') {
+    await rasterizeSvgToTight(inputPath, tightPath)
+  } else if (ext === 'png' || ext === 'jpg' || ext === 'jpeg' || ext === 'webp') {
+    await downsamplePngToTight(inputPath, tightPath)
+  } else {
+    throw new Error(`Unsupported master format: .${ext} (expected .svg or .png)`)
+  }
+
+  await padTightToSquare(tightPath, squarePath)
+
+  return { square: squarePath, tight: tightPath }
+}
+
+async function rasterizeSvgToTight(svgPath, outPath) {
+  const { buffer: svgBuffer, naturalMax } = await readSvgSafely(svgPath, {
+    logger,
+    withAdvice: true
+  })
+
+  // Supersample to ~4× MAX_DIMENSION so the final downsample yields clean edges.
+  const density = computeSvgDensity(naturalMax, MAX_DIMENSION * 4)
+  const hiRes = await sharp(svgBuffer, { density, limitInputPixels: false })
+    .png()
+    .toBuffer()
+
+  const meta = await sharp(hiRes).metadata()
+  const { width: w, height: h } = meta
+
+  await sharp(hiRes)
+    .resize({
+      width: w >= h ? MAX_DIMENSION : null,
+      height: h > w ? MAX_DIMENSION : null,
+      fit: 'inside',
+      withoutEnlargement: false
+    })
+    .png({ compressionLevel: 9 })
+    .toFile(outPath)
+}
+
+async function downsamplePngToTight(inputPath, outPath) {
+  const meta = await sharp(inputPath).metadata()
+  const { width: w, height: h } = meta
+
+  await sharp(inputPath)
+    .resize({
+      width: w >= h ? MAX_DIMENSION : null,
+      height: h > w ? MAX_DIMENSION : null,
+      fit: 'inside',
+      withoutEnlargement: true
+    })
+    .png({ compressionLevel: 9 })
+    .toFile(outPath)
+}
+
+async function padTightToSquare(tightPath, squarePath) {
+  await sharp(tightPath)
+    .resize({
+      width: MAX_DIMENSION,
+      height: MAX_DIMENSION,
+      fit: 'contain',
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .png({ compressionLevel: 9 })
+    .toFile(squarePath)
+}
+
+export { MAX_DIMENSION }

package/src/core/branding/tiapp-reader.js

@@ -0,0 +1,110 @@
+/**
+ * PurgeTSS - tiapp-reader
+ *
+ * Parses tiapp.xml and exposes just enough config for context-aware cleanup
+ * decisions. Uses fast-xml-parser under the hood when available, falls back
+ * to regex when the dep is unavailable.
+ *
+ * @fileoverview tiapp.xml parser for branding cleanup
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+
+let XMLParser = null
+try {
+  const mod = await import('fast-xml-parser')
+  XMLParser = mod.XMLParser
+} catch {
+  XMLParser = null
+}
+
+export function readTiapp(tiappPath) {
+  const result = {
+    exists: false,
+    storyboardEnabled: false,
+    portraitOnly: false,
+    defaultBgColor: null
+  }
+
+  if (!fs.existsSync(tiappPath)) return result
+
+  result.exists = true
+  const xml = fs.readFileSync(tiappPath, 'utf8')
+
+  if (XMLParser) return parseWithFastXml(xml, result)
+  return parseWithRegex(xml, result)
+}
+
+function parseWithFastXml(xml, result) {
+  try {
+    const parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@_',
+      parseAttributeValue: false,
+      parseTagValue: false,
+      trimValues: true
+    })
+    const doc = parser.parse(xml)
+
+    const ios = doc?.['ti:app']?.ios || doc?.ti?.app?.ios
+    if (ios) {
+      const sb = ios['enable-launch-screen-storyboard']
+      if (typeof sb === 'string' && sb.trim().toLowerCase() === 'true') {
+        result.storyboardEnabled = true
+      }
+      const bg = ios['default-background-color']
+      if (typeof bg === 'string' && bg.trim()) {
+        result.defaultBgColor = bg.trim()
+      }
+
+      const orientations = ios.orientations
+      if (orientations) {
+        const iphoneBlock = orientations.iphone
+        if (iphoneBlock !== undefined) {
+          const flat = JSON.stringify(iphoneBlock)
+          result.portraitOnly = !/Landscape/i.test(flat)
+        }
+      }
+    }
+    return result
+  } catch {
+    return parseWithRegex(xml, result)
+  }
+}
+
+function parseWithRegex(xml, result) {
+  if (/<enable-launch-screen-storyboard>\s*true\s*</i.test(xml)) {
+    result.storyboardEnabled = true
+  }
+
+  const bgMatch = xml.match(/<default-background-color>\s*(#[0-9A-Fa-f]{6,8})\s*</)
+  if (bgMatch) result.defaultBgColor = bgMatch[1]
+
+  if (/<orientations\b/i.test(xml) && !/UIInterfaceOrientationLandscape/i.test(xml)) {
+    result.portraitOnly = true
+  }
+
+  return result
+}
+
+export function detectProjectType(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'app'))) return 'alloy'
+  if (fs.existsSync(path.join(projectRoot, 'Resources'))) return 'classic'
+  return 'unknown'
+}
+
+export function resolveAndroidResRoot(projectRoot, projectType) {
+  if (projectType === 'alloy') return path.join(projectRoot, 'app', 'platform', 'android', 'res')
+  if (projectType === 'classic') return path.join(projectRoot, 'platform', 'android', 'res')
+  return null
+}
+
+export function hasAdaptiveIcons(projectRoot) {
+  const candidates = [
+    path.join(projectRoot, 'app', 'platform', 'android', 'res', 'mipmap-anydpi-v26'),
+    path.join(projectRoot, 'platform', 'android', 'res', 'mipmap-anydpi-v26')
+  ]
+  return candidates.some((c) => fs.existsSync(c))
+}

package/src/core/images/ensure-images-section.js

@@ -0,0 +1,57 @@
+/**
+ * PurgeTSS - Ensure `images:` section exists in purgetss/config.cjs
+ *
+ * Parallel to ensure-brand-section.js. When a project was initialized before
+ * the `images` command was introduced, its config.cjs won't have an `images:`
+ * key. On first invocation of `purgetss images`, we patch the file to insert
+ * the default block between `brand:` and `theme:` (or before `theme:` if
+ * `brand:` is not present yet). The user's existing keys are untouched.
+ *
+ * Also ensures `purgetss/images/` exists so the user can see where sources go,
+ * mirroring the `purgetss/fonts/` and `purgetss/brand/` conventions.
+ *
+ * @fileoverview Auto-injects the `images:` section on first `images` run
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import chalk from 'chalk'
+import { projectsConfigJS, projectsPurge_TSS_Images_Folder } from '../../shared/constants.js'
+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)
+  },
+`
+
+export function ensureImagesSection() {
+  if (!fs.existsSync(projectsPurge_TSS_Images_Folder)) {
+    fs.mkdirSync(projectsPurge_TSS_Images_Folder, { recursive: true })
+  }
+
+  if (!fs.existsSync(projectsConfigJS)) return
+
+  const original = fs.readFileSync(projectsConfigJS, 'utf8')
+
+  if (/^\s*images\s*:/m.test(original)) return
+
+  // Insert before the `theme:` key so the order stays purge → brand → images → theme.
+  const match = original.match(/(^\s*)theme\s*:/m)
+  if (!match) return
+
+  const patched = original.replace(match[0], `${IMAGES_BLOCK}${match[0]}`)
+
+  try {
+    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()
+  } 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.`)
+  }
+}

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

@@ -0,0 +1,181 @@
+/**
+ * PurgeTSS - gen-scales
+ *
+ * For a single source image, generate the 8 Titanium multi-density variants:
+ *
+ *   Android (5 densities, each in its own mipmap/drawable folder):
+ *     res-mdpi    = 1/4 of source  (1× baseline)
+ *     res-hdpi    = 1.5/4 of source
+ *     res-xhdpi   = 2/4 of source  (2×)
+ *     res-xxhdpi  = 3/4 of source  (3×)
+ *     res-xxxhdpi = full source    (4×, maximum density)
+ *
+ *   iPhone (3 scales in one folder, suffix in filename):
+ *     @1x = 1/4 of source
+ *     @2x = 2/4 of source
+ *     @3x = 3/4 of source
+ *
+ * Convention inherited from Titanium Alloy: source images are treated as
+ * 4× (xxxhdpi/@4x) masters, and all other scales are derived from them.
+ *
+ * @fileoverview Scale a source image into the 8 Titanium density variants
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+import { logger } from '../branding/branding-logger.js'
+import { computeSvgDensity, readSvgSafely } from '../../shared/svg-utils.js'
+
+/**
+ * Read source image: for SVGs, uses readSvgSafely (buffer + metadata + viewBox
+ * warning); for raster images, reads metadata directly from the file path.
+ *
+ * @returns {Promise<{path: string, meta: Object, isSvg: boolean, buffer: Buffer|null}>}
+ */
+async function readSource(sourceFile) {
+  const isSvg = path.extname(sourceFile).toLowerCase() === '.svg'
+  if (isSvg) {
+    const { buffer, meta } = await readSvgSafely(sourceFile, { logger })
+    return { path: sourceFile, meta, isSvg: true, buffer }
+  }
+  const meta = await sharp(sourceFile).metadata()
+  return { path: sourceFile, meta, isSvg: false, buffer: null }
+}
+
+/**
+ * Build a Sharp pipeline for the requested scale. For SVG sources, density is
+ * computed so the rasterization lands at ~2× target — avoiding the pixel limit
+ * regardless of viewBox size.
+ */
+function buildScalePipeline(src, targetMax) {
+  if (src.isSvg) {
+    const naturalMax = Math.max(src.meta.width, src.meta.height)
+    // 2× target for antialiasing headroom before Sharp's downsample.
+    const density = computeSvgDensity(naturalMax, targetMax * 2)
+    return sharp(src.buffer, { density, limitInputPixels: false })
+  }
+  return sharp(src.path)
+}
+
+export const ANDROID_SCALES = Object.freeze([
+  { name: 'res-mdpi',    factor: 1 / 4 },
+  { name: 'res-hdpi',    factor: 1.5 / 4 },
+  { name: 'res-xhdpi',   factor: 2 / 4 },
+  { name: 'res-xxhdpi',  factor: 3 / 4 },
+  { name: 'res-xxxhdpi', factor: 4 / 4 }
+])
+
+export const IPHONE_SCALES = Object.freeze([
+  { suffix: '',    factor: 1 / 4 },
+  { suffix: '@2x', factor: 2 / 4 },
+  { suffix: '@3x', factor: 3 / 4 }
+])
+
+/**
+ * Scale a source image into all Android density variants.
+ *
+ * @param {string} sourceFile - Absolute path to source image
+ * @param {string} relPath - Path inside the source root (e.g. 'buttons/btn.png')
+ * @param {string} androidBaseDir - e.g. <project>/app/assets/android/images
+ * @param {Object} opts
+ * @param {string|null} [opts.format] - 'webp'|'jpeg'|'png'|null (null = keep original)
+ * @param {number} [opts.quality=85]
+ * @returns {Promise<string[]>} Paths written
+ */
+export async function genAndroidScales(sourceFile, relPath, androidBaseDir, opts = {}) {
+  const { format = null, quality = 85 } = opts
+  const src = await readSource(sourceFile)
+  const written = []
+
+  for (const { name, factor } of ANDROID_SCALES) {
+    const targetWidth = Math.max(1, Math.round(src.meta.width * factor))
+    const targetHeight = Math.max(1, Math.round(src.meta.height * factor))
+
+    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)
+    written.push(outPath)
+  }
+  return written
+}
+
+/**
+ * Scale a source image into all iPhone scale variants.
+ *
+ * @param {string} sourceFile - Absolute path to source image
+ * @param {string} relPath - Path inside the source root (e.g. 'buttons/btn.png')
+ * @param {string} iphoneBaseDir - e.g. <project>/app/assets/iphone/images
+ * @param {Object} opts - Same shape as genAndroidScales
+ * @returns {Promise<string[]>} Paths written
+ */
+export async function genIphoneScales(sourceFile, relPath, iphoneBaseDir, opts = {}) {
+  const { format = null, quality = 85 } = opts
+  const src = await readSource(sourceFile)
+  const written = []
+
+  const parsed = path.parse(relPath)
+  const outDir = path.join(iphoneBaseDir, parsed.dir)
+  fs.mkdirSync(outDir, { recursive: true })
+
+  for (const { suffix, factor } of IPHONE_SCALES) {
+    const targetWidth = Math.max(1, Math.round(src.meta.width * factor))
+    const targetHeight = Math.max(1, Math.round(src.meta.height * factor))
+
+    // SVG sources can't be written as SVG by Sharp — fall back to PNG if the
+    // user didn't specify an explicit output format.
+    const ext = format ? `.${format}` : (src.isSvg ? '.png' : parsed.ext)
+    const outName = `${parsed.name}${suffix}${ext}`
+    const outPath = path.join(outDir, outName)
+
+    await writeScaled(src, outPath, targetWidth, targetHeight, format, quality)
+    written.push(outPath)
+  }
+  return written
+}
+
+function renameWithFormat(filename, format, isSvg = false) {
+  if (format) {
+    const parsed = path.parse(filename)
+    return `${parsed.name}.${format}`
+  }
+  // SVG masters can't be written back as SVG by Sharp — coerce to PNG.
+  if (isSvg) {
+    const parsed = path.parse(filename)
+    return `${parsed.name}.png`
+  }
+  return filename
+}
+
+async function writeScaled(src, outPath, width, height, format, quality) {
+  const targetMax = Math.max(width, height)
+  let pipeline = buildScalePipeline(src, targetMax).resize({
+    width,
+    height,
+    fit: 'contain',
+    background: { r: 0, g: 0, b: 0, alpha: 0 }
+  })
+
+  // 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()
+  const fmt = format || fallbackExt
+  pipeline = applyFormat(pipeline, fmt === 'jpg' ? 'jpeg' : fmt, quality)
+
+  await pipeline.toFile(outPath)
+}
+
+function applyFormat(pipeline, format, quality) {
+  switch (format) {
+    case 'png':  return pipeline.png({ quality, compressionLevel: 9 })
+    case 'webp': return pipeline.webp({ quality })
+    case 'avif': return pipeline.avif({ quality })
+    case 'tiff': return pipeline.tiff({ quality, compression: 'lzw' })
+    case 'gif':  return pipeline.gif()
+    case 'jpeg': return pipeline.flatten({ background: '#ffffff' }).jpeg({ quality })
+    default:     return pipeline
+  }
+}