purgetss 7.5.2 → 7.6.1

package/src/core/branding/index.js

@@ -0,0 +1,336 @@
+/**
+ * PurgeTSS - Branding pipeline orchestrator
+ *
+ * Composes the branding pipeline for Titanium projects.
+ *
+ * Every invocation (kitchen-sink) generates:
+ *
+ *   iOS & marketplace:
+ *     - DefaultIcon.png              (alpha preserved)
+ *     - DefaultIcon-ios.png          (flattened on bg-color)
+ *     - DefaultIcon-Dark.png         (iOS 18+, transparent by default)
+ *     - DefaultIcon-Tinted.png       (iOS 18+, grayscale on black)
+ *     - iTunesConnect.png            (1024²)
+ *     - MarketplaceArtwork.png       (512²)
+ *
+ *   Android:
+ *     - ic_launcher_foreground.png   × 5 densities
+ *     - ic_launcher_background.png   × 5 densities
+ *     - ic_launcher_monochrome.png   × 5 densities  (themed icons / dark mode)
+ *     - ic_launcher.png              × 5 densities  (legacy pre-adaptive)
+ *     - mipmap-anydpi-v26/ic_launcher.xml
+ *
+ *   Optional (opt-in):
+ *     - ic_stat_notify.png × 5       (--notification)
+ *     - splash_icon.png × 5          (--splash)
+ *
+ *   Opt-out:
+ *     - DefaultIcon-Dark.png         (--no-dark)
+ *     - DefaultIcon-Tinted.png       (--no-tinted)
+ *
+ * @fileoverview Titanium branding pipeline orchestrator
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { logger } from './branding-logger.js'
+import { logger as mainLogger } from '../../shared/logger.js'
+import { confirmWithAlways } from '../../shared/prompt.js'
+import { setConfigProperty } from '../../shared/config-writer.js'
+import { prepareMaster } from './prepare-master.js'
+import { genIos } from './gen-ios.js'
+import { genIosDark } from './gen-ios-dark.js'
+import { genIosTinted } from './gen-ios-tinted.js'
+import { genAndroidAdaptive } from './gen-android-adaptive.js'
+import { genAndroidLegacy } from './gen-android-legacy.js'
+import { genMarketplace } from './gen-marketplace.js'
+import { genNotification } from './gen-notification.js'
+import { genSplash } from './gen-splash.js'
+import { genIcLauncherXml } from './gen-ic-launcher-xml.js'
+import { detectProjectType } from './tiapp-reader.js'
+import { cleanupLegacy } from './cleanup-legacy.js'
+import { printPostGenNotes } from './post-gen-notes.js'
+
+export async function runBranding(opts) {
+  const {
+    logo,
+    monochromeLogo = null,
+    darkLogo = null,
+    darkBgColor = null,
+    withDark = true,
+    withTinted = true,
+    tintedLogo = null,
+    bgColor = '#FFFFFF',
+    bgColorExplicit = false,
+    padding = 15,
+    iosPadding = 4,
+    notification = false,
+    splash = false,
+    cleanupLegacy: runCleanup = false,
+    aggressive = false,
+    projectRoot = process.cwd(),
+    output,
+    dryRun = false,
+    inPlace = false,
+    notes = false,
+    yes = false,
+    confirmOverwrites = true
+  } = opts
+
+  validateOptions({ logo, bgColor, darkBgColor, padding, iosPadding, cleanupLegacy: runCleanup })
+
+  const projectType = detectProjectType(projectRoot)
+  const isInPlace = inPlace && !output
+  const stagingRoot = output || (isInPlace ? projectRoot : path.join(projectRoot, '.ti-branding'))
+
+  console.log()
+  mainLogger.info('Generating branding assets...')
+  console.log()
+  logger.property('Project:    ', `${projectRoot} (${projectType})`)
+  if (logo) {
+    logger.property('Logo:       ', logo)
+    logger.property('Background: ', bgColor)
+    logger.property('Padding:    ', `Android ${padding}% / iOS ${iosPadding}% per side`)
+    console.log()
+    logger.property(isInPlace ? 'Writing IN PLACE to: ' : 'Staging:    ', isInPlace ? projectRoot : stagingRoot)
+  }
+  if (isInPlace && !dryRun && confirmOverwrites) {
+    logger.warning(`⚠  In-place mode will OVERWRITE files in ${projectRoot}.`)
+    logger.warning(`   Commit first if you want a rollback.`)
+    const choice = await confirmWithAlways('Continue? [y/N/a]', { yes })
+    if (choice === 'no') {
+      logger.info('Aborted.')
+      // eslint-disable-next-line n/no-process-exit
+      process.exit(0)
+    }
+    if (choice === 'always') {
+      const saved = setConfigProperty('brand', 'confirmOverwrites', false)
+      if (saved) {
+        logger.success('Saved brand.confirmOverwrites = false to purgetss/config.cjs — you won\'t be asked again.')
+      } else {
+        logger.warning('Could not persist preference (config.cjs missing or unreadable). Proceeding anyway.')
+      }
+    }
+  }
+  if (dryRun) logger.warning('DRY RUN — no files will be written')
+
+  const generated = []
+
+  // Cleanup-only mode
+  if (!logo && runCleanup) {
+    logger.info('Cleanup-only mode')
+    await cleanupLegacy({ projectRoot, projectType, aggressive, dryRun })
+    return { stagingRoot, generated }
+  }
+
+  if (!logo) {
+    throw new Error('Logo image is required (unless running --cleanup-legacy alone).')
+  }
+  if (!fs.existsSync(logo)) {
+    throw new Error(`Logo image not found: ${logo}`)
+  }
+
+  if (projectType === 'unknown') {
+    logger.warning(`Could not detect project layout. Expected 'app/' (Alloy) or 'Resources/' (Classic).`)
+    logger.warning(`Assets will be staged under ${stagingRoot}/standalone/ — copy manually.`)
+  }
+
+  const androidResStaging = getStagingAndroidResRoot(stagingRoot, projectType)
+
+  if (dryRun) {
+    const lines = [
+      `${stagingRoot}/DefaultIcon.png + DefaultIcon-ios.png`
+    ]
+    if (withDark) {
+      const darkSrc = darkLogo
+        ? `from ${darkLogo}`
+        : (darkBgColor ? `opaque bg ${darkBgColor}` : 'transparent per Apple HIG')
+      lines.push(`${stagingRoot}/DefaultIcon-Dark.png (${darkSrc})`)
+    }
+    if (withTinted) {
+      const tintedSrc = tintedLogo ? `from ${tintedLogo}` : 'grayscale of logo, flattened on black'
+      lines.push(`${stagingRoot}/DefaultIcon-Tinted.png (${tintedSrc})`)
+    }
+    lines.push(`${stagingRoot}/iTunesConnect.png + MarketplaceArtwork.png`)
+    lines.push(`${androidResStaging}/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/ic_launcher_{foreground,background,monochrome}.png`)
+    lines.push(`${androidResStaging}/mipmap-{...}/ic_launcher.png (legacy)`)
+    lines.push(`${androidResStaging}/mipmap-anydpi-v26/ic_launcher.xml`)
+    if (notification) lines.push(`${androidResStaging}/drawable-*/ic_stat_notify.png × 5`)
+    if (splash) lines.push(`${androidResStaging}/drawable-*/splash_icon.png × 5`)
+    mainLogger.block('[dry-run] Would generate:', ...lines)
+    if (runCleanup) {
+      await cleanupLegacy({ projectRoot, projectType, aggressive, dryRun })
+    }
+    return { stagingRoot, generated }
+  }
+
+  // Route temp logos through the OS temp dir in --in-place mode so the
+  // project tree (and VSCode's file explorer) stays clean. Using a unique
+  // subdir per run avoids clashes between parallel invocations.
+  const tempDir = isInPlace
+    ? path.join(os.tmpdir(), `pt-branding-${process.pid}-${Date.now()}`)
+    : stagingRoot
+  const weCreatedTempDir = isInPlace && !fs.existsSync(tempDir)
+  if (weCreatedTempDir) fs.mkdirSync(tempDir, { recursive: true })
+
+  // ---- Section: Logos ---------------------------------------------------
+  logger.section('Logos')
+  logger.bullet('Dual logos (square + tight)')
+  const logoBase = path.join(tempDir, '_logo')
+  const { tight } = await prepareMaster(logo, logoBase)
+
+  let monoTight = null
+  if (monochromeLogo) {
+    if (!fs.existsSync(monochromeLogo)) {
+      throw new Error(`Monochrome logo not found: ${monochromeLogo}`)
+    }
+    logger.bullet(`Monochrome logo: ${monochromeLogo}`)
+    const monoBase = path.join(tempDir, '_logo_mono')
+    const monoResult = await prepareMaster(monochromeLogo, monoBase)
+    monoTight = monoResult.tight
+  }
+
+  // ---- Section: iOS & marketplace ----------------------------------------
+  logger.section('iOS & marketplace')
+  logger.bullet(`DefaultIcon.png (Android-safe padding ${padding}%) + DefaultIcon-ios.png (iOS padding ${iosPadding}%)`)
+  const ios = await genIos(tight, bgColor, padding, iosPadding, stagingRoot)
+  generated.push(ios.defaultIcon, ios.defaultIconIos)
+
+  if (withDark) {
+    let darkSource = tight
+    if (darkLogo) {
+      if (!fs.existsSync(darkLogo)) throw new Error(`Dark logo not found: ${darkLogo}`)
+      const darkBase = path.join(tempDir, '_logo_dark')
+      const darkResult = await prepareMaster(darkLogo, darkBase)
+      darkSource = darkResult.tight
+    }
+    const darkSrcLabel = darkLogo ? 'from --dark-logo, ' : ''
+    const darkBgLabel = darkBgColor ? `opaque bg ${darkBgColor}` : 'transparent per Apple HIG'
+    logger.bullet(`DefaultIcon-Dark.png (${darkSrcLabel}${darkBgLabel})`)
+    const darkPath = await genIosDark(darkSource, darkBgColor, iosPadding, stagingRoot)
+    generated.push(darkPath)
+  }
+
+  if (withTinted) {
+    let tintedSource = tight
+    if (tintedLogo) {
+      if (!fs.existsSync(tintedLogo)) throw new Error(`Tinted logo not found: ${tintedLogo}`)
+      const tintedBase = path.join(tempDir, '_logo_tinted')
+      const tintedResult = await prepareMaster(tintedLogo, tintedBase)
+      tintedSource = tintedResult.tight
+    }
+    const tintedSrcLabel = tintedLogo ? 'from --tinted-logo' : 'grayscale of logo'
+    logger.bullet(`DefaultIcon-Tinted.png (${tintedSrcLabel}, flattened on black)`)
+    const tintedPath = await genIosTinted(tintedSource, iosPadding, stagingRoot)
+    generated.push(tintedPath)
+  }
+
+  const alphaMode = bgColorExplicit ? `flattened on ${bgColor}` : 'alpha preserved'
+  logger.bullet(`iTunesConnect.png + MarketplaceArtwork.png (${alphaMode})`)
+  const mkt = await genMarketplace(tight, iosPadding, stagingRoot, {
+    flatten: bgColorExplicit,
+    bgColor
+  })
+  generated.push(mkt.itunesConnect, mkt.marketplaceArtwork)
+
+  // ---- Section: Android --------------------------------------------------
+  logger.section('Android')
+
+  const monoLabel = monoTight ? ', monochrome from --monochrome-logo' : ''
+  logger.bullet(`Adaptive icons (foreground + background + monochrome${monoLabel}) × 5`)
+  const adaptiveFiles = await genAndroidAdaptive(tight, bgColor, padding, androidResStaging, { monoTight })
+  generated.push(...adaptiveFiles)
+
+  logger.bullet('Legacy ic_launcher.png × 5')
+  const legacyFiles = await genAndroidLegacy(tight, bgColor, padding, androidResStaging)
+  generated.push(...legacyFiles)
+
+  const xmlPath = genIcLauncherXml(androidResStaging)
+  generated.push(xmlPath)
+  logger.bullet(`Adaptive icon XML: ${xmlPath}`)
+
+  if (notification) {
+    const monoLabelNotif = monoTight ? ' from --monochrome-logo' : ' whitened from logo'
+    logger.bullet(`Notification icons (white+alpha, edge-to-edge${monoLabelNotif}) × 5`)
+    const notifFiles = await genNotification(monoTight || tight, androidResStaging)
+    generated.push(...notifFiles)
+  }
+
+  if (splash) {
+    logger.bullet('Splash icons × 5')
+    const splashFiles = await genSplash(tight, androidResStaging)
+    generated.push(...splashFiles)
+  }
+
+  if (runCleanup) {
+    logger.info('Cleanup legacy artifacts')
+    await cleanupLegacy({ projectRoot, projectType, aggressive, dryRun })
+  }
+
+  // Clean up temp _logo_* files in --in-place mode
+  if (isInPlace) {
+    if (weCreatedTempDir) {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    } else {
+      const tmpFiles = [
+        path.join(tempDir, '_logo_square.png'),
+        path.join(tempDir, '_logo_tight.png'),
+        path.join(tempDir, '_logo_mono_square.png'),
+        path.join(tempDir, '_logo_mono_tight.png'),
+        path.join(tempDir, '_logo_dark_square.png'),
+        path.join(tempDir, '_logo_dark_tight.png'),
+        path.join(tempDir, '_logo_tinted_square.png'),
+        path.join(tempDir, '_logo_tinted_tight.png')
+      ]
+      for (const tmp of tmpFiles) {
+        if (fs.existsSync(tmp)) fs.unlinkSync(tmp)
+      }
+    }
+    logger.info('')
+    logger.success(`All assets written IN PLACE at: ${projectRoot}`)
+  } else {
+    logger.info('')
+    logger.success(`All assets staged at: ${stagingRoot}`)
+  }
+
+  printPostGenNotes({
+    projectType,
+    projectRoot,
+    stagingRoot,
+    bgColor,
+    padding,
+    iosPadding,
+    withSplash: splash,
+    withNotification: notification,
+    inPlace: isInPlace,
+    fullNotes: notes
+  })
+
+  return { stagingRoot, generated }
+}
+
+function getStagingAndroidResRoot(stagingRoot, projectType) {
+  if (projectType === 'alloy') return path.join(stagingRoot, 'app', 'platform', 'android', 'res')
+  if (projectType === 'classic') return path.join(stagingRoot, 'platform', 'android', 'res')
+  return path.join(stagingRoot, 'standalone', 'platform', 'android', 'res')
+}
+
+function validateOptions({ logo, bgColor, darkBgColor, padding, iosPadding, cleanupLegacy }) {
+  if (!logo && !cleanupLegacy) {
+    throw new Error('Logo image path is required (unless using --cleanup-legacy alone).')
+  }
+  if (!/^#[0-9A-Fa-f]{6}$/.test(bgColor)) {
+    throw new Error(`--bg-color must be a 6-digit hex like #0B1326 (got: ${bgColor}).`)
+  }
+  if (darkBgColor && !/^#[0-9A-Fa-f]{6}$/.test(darkBgColor)) {
+    throw new Error(`--dark-bg-color must be a 6-digit hex like #1C1C1E (got: ${darkBgColor}).`)
+  }
+  if (padding < 0 || padding > 40) {
+    throw new Error(`--padding must be between 0 and 40 (got: ${padding}).`)
+  }
+  if (iosPadding < 0 || iosPadding > 40) {
+    throw new Error(`--ios-padding must be between 0 and 40 (got: ${iosPadding}).`)
+  }
+}

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 }