purgetss 7.5.3 → 7.6.1

package/src/core/branding/gen-ios.js

@@ -0,0 +1,69 @@
+/**
+ * PurgeTSS - gen-ios
+ *
+ * Produces Titanium's two root-level iOS/Android icons:
+ *
+ *   DefaultIcon.png       1024×1024, alpha preserved (universal fallback)
+ *   DefaultIcon-ios.png   1024×1024, alpha flattened on bg-color (iOS)
+ *
+ * Two distinct paddings — `DefaultIcon.png` is the universal fallback (iOS +
+ * Android when no adaptive icons exist), so it uses the Android safe-zone
+ * padding to stay inside launcher masks. `DefaultIcon-ios.png` is iOS-only
+ * (no launcher mask), so it uses the looser aesthetic iOS padding.
+ *
+ * Apple rejects alpha on App Store icon uploads, so DefaultIcon-ios.png is
+ * always flattened onto the bg-color.
+ *
+ * @fileoverview Root iOS icons for Titanium projects
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+const CANVAS = 1024
+
+export async function genIos(tightMaster, bgColor, androidPadding, iosPadding, outRoot) {
+  fs.mkdirSync(outRoot, { recursive: true })
+
+  const defaultIconPath = path.join(outRoot, 'DefaultIcon.png')
+  const defaultIconIosPath = path.join(outRoot, 'DefaultIcon-ios.png')
+
+  // DefaultIcon.png — alpha preserved, Android safe-zone padding so it stays
+  // launcher-mask-safe when Android falls back to it.
+  await renderSquare(tightMaster, androidPadding, null, defaultIconPath)
+
+  // DefaultIcon-ios.png — flattened on bg-color, iOS aesthetic padding.
+  await renderSquare(tightMaster, iosPadding, bgColor, defaultIconIosPath)
+
+  return { defaultIcon: defaultIconPath, defaultIconIos: defaultIconIosPath }
+}
+
+async function renderSquare(tightMaster, paddingPct, flattenBg, outPath) {
+  const inner = Math.floor((CANVAS * (100 - 2 * paddingPct)) / 100)
+
+  const resized = await sharp(tightMaster)
+    .resize({
+      width: inner,
+      height: inner,
+      fit: 'inside',
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .toBuffer()
+
+  const pipeline = sharp({
+    create: {
+      width: CANVAS,
+      height: CANVAS,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    }
+  }).composite([{ input: resized, gravity: 'center' }])
+
+  if (flattenBg) {
+    await pipeline.flatten({ background: flattenBg }).removeAlpha().png({ compressionLevel: 9 }).toFile(outPath)
+  } else {
+    await pipeline.png({ compressionLevel: 9 }).toFile(outPath)
+  }
+}

package/src/core/branding/gen-marketplace.js

@@ -0,0 +1,71 @@
+/**
+ * PurgeTSS - gen-marketplace
+ *
+ * Store-submission artwork:
+ *
+ *   iTunesConnect.png      1024×1024 (App Store)
+ *   MarketplaceArtwork.png 512×512   (Google Play)
+ *
+ * Alpha handling depends on whether --bg-color was explicitly provided:
+ *   - not provided → alpha preserved (matches `ti create` default template)
+ *   - provided     → alpha flattened onto bg-color (safer for dark-mode stores)
+ *
+ * @fileoverview Marketplace artwork for Titanium branding
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+export async function genMarketplace(tightMaster, paddingPct, outRoot, opts = {}) {
+  const { flatten = false, bgColor = '#FFFFFF' } = opts
+  fs.mkdirSync(outRoot, { recursive: true })
+
+  const itunesConnect = await renderSquare(
+    tightMaster,
+    paddingPct,
+    1024,
+    path.join(outRoot, 'iTunesConnect.png'),
+    { flatten, bgColor }
+  )
+  const marketplaceArtwork = await renderSquare(
+    tightMaster,
+    paddingPct,
+    512,
+    path.join(outRoot, 'MarketplaceArtwork.png'),
+    { flatten, bgColor }
+  )
+
+  return { itunesConnect, marketplaceArtwork }
+}
+
+async function renderSquare(tight, paddingPct, canvasSize, outPath, { flatten, bgColor }) {
+  const inner = Math.floor((canvasSize * (100 - 2 * paddingPct)) / 100)
+
+  const resized = await sharp(tight)
+    .resize({
+      width: inner,
+      height: inner,
+      fit: 'inside',
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .toBuffer()
+
+  let pipeline = sharp({
+    create: {
+      width: canvasSize,
+      height: canvasSize,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    }
+  })
+    .composite([{ input: resized, gravity: 'center' }])
+
+  if (flatten) {
+    pipeline = pipeline.flatten({ background: bgColor }).removeAlpha()
+  }
+
+  await pipeline.png({ compressionLevel: 9 }).toFile(outPath)
+  return outPath
+}

package/src/core/branding/gen-notification.js

@@ -0,0 +1,76 @@
+/**
+ * PurgeTSS - gen-notification
+ *
+ * White-on-transparent notification icons × 5 densities.
+ *
+ * Android status bar applies runtime tint based on the notification's color
+ * property, so all non-transparent pixels become white. Color info is discarded.
+ *
+ * Sizes: mdpi=24, hdpi=36, xhdpi=48, xxhdpi=72, xxxhdpi=96.
+ * Output path: drawable-<density>/ic_stat_notify.png
+ *
+ * Notification icons are NOT masked by the launcher, so they render as drawn.
+ * Trim any transparent padding in the master first, then scale the logo to
+ * fill the canvas edge-to-edge with a 1px anti-aliasing margin per side.
+ *
+ * @fileoverview Status-bar notification icons × 5 densities
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+export const NOTIFICATION_DENSITIES = [
+  { name: 'mdpi', size: 24 },
+  { name: 'hdpi', size: 36 },
+  { name: 'xhdpi', size: 48 },
+  { name: 'xxhdpi', size: 72 },
+  { name: 'xxxhdpi', size: 96 }
+]
+
+const EDGE_MARGIN = 2
+
+export async function genNotification(tightMaster, resRoot) {
+  const generated = []
+
+  const trimmedMaster = await sharp(tightMaster)
+    .trim()
+    .png()
+    .toBuffer()
+
+  for (const { name, size } of NOTIFICATION_DENSITIES) {
+    const inner = Math.max(1, size - EDGE_MARGIN)
+    const dir = path.join(resRoot, `drawable-${name}`)
+    fs.mkdirSync(dir, { recursive: true })
+
+    const outPath = path.join(dir, 'ic_stat_notify.png')
+
+    const whitened = await sharp(trimmedMaster)
+      .resize({
+        width: inner,
+        height: inner,
+        fit: 'inside',
+        background: { r: 0, g: 0, b: 0, alpha: 0 }
+      })
+      .ensureAlpha()
+      .linear([0, 0, 0, 1], [255, 255, 255, 0])
+      .toBuffer()
+
+    await sharp({
+      create: {
+        width: size,
+        height: size,
+        channels: 4,
+        background: { r: 0, g: 0, b: 0, alpha: 0 }
+      }
+    })
+      .composite([{ input: whitened, gravity: 'center' }])
+      .png({ compressionLevel: 9 })
+      .toFile(outPath)
+
+    generated.push(outPath)
+  }
+
+  return generated
+}

package/src/core/branding/gen-splash.js

@@ -0,0 +1,64 @@
+/**
+ * PurgeTSS - gen-splash
+ *
+ * Android 12+ SplashScreen API icon × 5 densities.
+ *
+ * Spec: 288dp canvas, icon occupies central 192dp (~67% of canvas).
+ * The OS applies a circular mask automatically — keep pixels transparent
+ * outside the 192dp safe-zone.
+ *
+ * Densities: mdpi=288, hdpi=432, xhdpi=576, xxhdpi=864, xxxhdpi=1152.
+ * Output path: drawable-<density>/splash_icon.png
+ *
+ * @fileoverview Android 12+ splash icons × 5 densities
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+export const SPLASH_DENSITIES = [
+  { name: 'mdpi', size: 288 },
+  { name: 'hdpi', size: 432 },
+  { name: 'xhdpi', size: 576 },
+  { name: 'xxhdpi', size: 864 },
+  { name: 'xxxhdpi', size: 1152 }
+]
+
+export async function genSplash(tightMaster, resRoot) {
+  const generated = []
+
+  for (const { name, size } of SPLASH_DENSITIES) {
+    const inner = Math.floor((size * 192) / 288)
+    const dir = path.join(resRoot, `drawable-${name}`)
+    fs.mkdirSync(dir, { recursive: true })
+
+    const outPath = path.join(dir, 'splash_icon.png')
+
+    const innerLogo = await sharp(tightMaster)
+      .resize({
+        width: inner,
+        height: inner,
+        fit: 'inside',
+        background: { r: 0, g: 0, b: 0, alpha: 0 }
+      })
+      .toBuffer()
+
+    await sharp({
+      create: {
+        width: size,
+        height: size,
+        channels: 4,
+        background: { r: 0, g: 0, b: 0, alpha: 0 }
+      }
+    })
+      .composite([{ input: innerLogo, gravity: 'center' }])
+      .png({ compressionLevel: 9 })
+      .toFile(outPath)
+
+    generated.push(outPath)
+  }
+
+  return generated
+}

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}).`)
+  }
+}