purgetss 7.5.3 → 7.6.1

package/src/core/branding/branding-logger.js

@@ -0,0 +1,40 @@
+/**
+ * PurgeTSS - Branding Logger
+ *
+ * Chalk-based presentation helpers used exclusively by the branding pipeline.
+ * Separate from the main PurgeTSS logger because the branding output style
+ * (sections, bullets, property rows) is much richer than the one-line logging
+ * used elsewhere in the tool.
+ *
+ * @fileoverview Logger helpers for the branding pipeline
+ * @author César Estrada
+ */
+
+import chalk from 'chalk'
+
+let debugMode = false
+
+export const logger = {
+  setDebugMode(enabled) { debugMode = enabled },
+
+  info(message) { console.log(chalk.blue(message)) },
+
+  section(name) {
+    console.log()
+    console.log(chalk.cyan(`▸ ${name}`))
+  },
+
+  bullet(message) { console.log(`  ${chalk.cyan('•')} ${message}`) },
+
+  property(label, value) { console.log(`${chalk.blue(label)}${value}`) },
+
+  success(message) { console.log(chalk.green(message)) },
+
+  warning(message) { console.log(chalk.yellow(message)) },
+
+  error(message) { console.error(chalk.red(message)) },
+
+  debug(message) {
+    if (debugMode) console.log(chalk.cyan(message))
+  }
+}

package/src/core/branding/cleanup-legacy.js

@@ -0,0 +1,220 @@
+/**
+ * PurgeTSS - cleanup-legacy
+ *
+ * Context-aware removal of legacy branding artifacts.
+ *
+ * Reads tiapp.xml via tiapp-reader and categorizes targets into:
+ *
+ *   SAFE          always deleted — universally obsolete (dead qualifiers)
+ *   CONDITIONAL   deleted only when project config guarantees they're unused
+ *                 (e.g. iOS legacy launch images when storyboard is enabled)
+ *   AGGRESSIVE    behind --aggressive — strongly defensible but some edge
+ *                 cases (e.g. ldpi drawables on <1% of devices)
+ *
+ * Always prints the plan before acting. Respects dryRun.
+ *
+ * @fileoverview Legacy-artifact cleanup for Titanium branding
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { logger } from './branding-logger.js'
+import { readTiapp, hasAdaptiveIcons } from './tiapp-reader.js'
+
+export async function cleanupLegacy({ projectRoot, projectType, aggressive = false, dryRun = false }) {
+  const tiappPath = path.join(projectRoot, 'tiapp.xml')
+  const tiapp = readTiapp(tiappPath)
+  const adaptive = hasAdaptiveIcons(projectRoot)
+
+  const layout = getLayoutPaths(projectRoot, projectType)
+
+  const safe = []
+  const conditional = []
+  const aggressiveTargets = []
+
+  // ---- SAFE -----------------------------------------------------------
+  if (layout.androidImages && fs.existsSync(layout.androidImages)) {
+    const reason = 'Android long/notlong qualifier (dead since Android 3.0, 2011)'
+    for (const entry of listChildDirs(layout.androidImages, /^res-(long|notlong)-/)) {
+      safe.push({ path: entry, reason })
+    }
+  }
+
+  // ---- CONDITIONAL ----------------------------------------------------
+  if (tiapp.storyboardEnabled && layout.iphoneDir && fs.existsSync(layout.iphoneDir)) {
+    const reason = 'iOS legacy launch image (storyboard enabled → not consulted)'
+    for (const entry of listChildFiles(layout.iphoneDir, /^Default(-.+)?(@2x)?\.png$/)) {
+      conditional.push({ path: entry, reason })
+    }
+  }
+
+  if (tiapp.portraitOnly && layout.androidImages && fs.existsSync(layout.androidImages)) {
+    const reason = 'Landscape variant (app is portrait-only)'
+    for (const entry of listChildDirs(layout.androidImages, /(^res-.+-land-|^res-land-)/)) {
+      conditional.push({ path: entry, reason })
+    }
+  }
+
+  if (adaptive && layout.androidAssets) {
+    const defaultPng = path.join(layout.androidAssets, 'default.png')
+    if (fs.existsSync(defaultPng)) {
+      conditional.push({
+        path: defaultPng,
+        reason: 'Legacy Android splash PNG (adaptive launcher handles splash now)'
+      })
+    }
+    const appicon = path.join(layout.androidAssets, 'appicon.png')
+    if (fs.existsSync(appicon)) {
+      conditional.push({
+        path: appicon,
+        reason: 'Legacy appicon.png (adaptive launcher takes precedence)'
+      })
+    }
+  }
+
+  // ---- AGGRESSIVE -----------------------------------------------------
+  if (aggressive) {
+    const reason = 'ldpi density (<1% global market)'
+    if (layout.androidImages && fs.existsSync(layout.androidImages)) {
+      for (const entry of listChildDirs(layout.androidImages, /(^res-ldpi$|^res-.+-ldpi$)/)) {
+        aggressiveTargets.push({ path: entry, reason })
+      }
+    }
+    const ldpiDirs = [
+      path.join(projectRoot, 'app', 'platform', 'android', 'res', 'drawable-ldpi'),
+      path.join(projectRoot, 'app', 'platform', 'android', 'res', 'values-ldpi'),
+      path.join(projectRoot, 'app', 'platform', 'android', 'res', 'mipmap-ldpi'),
+      path.join(projectRoot, 'platform', 'android', 'res', 'drawable-ldpi'),
+      path.join(projectRoot, 'platform', 'android', 'res', 'values-ldpi'),
+      path.join(projectRoot, 'platform', 'android', 'res', 'mipmap-ldpi')
+    ]
+    for (const d of ldpiDirs) {
+      if (fs.existsSync(d)) {
+        aggressiveTargets.push({ path: d, reason: 'ldpi resource folder (<1% global market)' })
+      }
+    }
+  }
+
+  printPlan({
+    projectRoot, projectType, tiapp, adaptive, aggressive,
+    safe, conditional, aggressiveTargets
+  })
+
+  const total = safe.length + conditional.length + aggressiveTargets.length
+  if (total === 0) {
+    logger.success('No legacy artifacts detected. Project is already clean.')
+    return { removed: 0, bytes: 0 }
+  }
+
+  if (dryRun) {
+    logger.info('Dry-run mode — nothing deleted. Re-run without --dry-run to apply.')
+    return { removed: 0, bytes: 0 }
+  }
+
+  let removed = 0
+  let bytes = 0
+  for (const bucket of [safe, conditional, aggressiveTargets]) {
+    for (const { path: target } of bucket) {
+      const size = getSizeBytes(target)
+      fs.rmSync(target, { recursive: true, force: true })
+      bytes += size
+      removed += 1
+      logger.success(`Removed ${path.relative(projectRoot, target)}`)
+    }
+  }
+  return { removed, bytes }
+}
+
+function getLayoutPaths(projectRoot, projectType) {
+  if (projectType === 'alloy') {
+    return {
+      androidImages: path.join(projectRoot, 'app', 'assets', 'android', 'images'),
+      iphoneDir: path.join(projectRoot, 'app', 'assets', 'iphone'),
+      androidAssets: path.join(projectRoot, 'app', 'assets', 'android')
+    }
+  }
+  if (projectType === 'classic') {
+    return {
+      androidImages: path.join(projectRoot, 'Resources', 'android', 'images'),
+      iphoneDir: path.join(projectRoot, 'Resources', 'iphone'),
+      androidAssets: path.join(projectRoot, 'Resources', 'android')
+    }
+  }
+  return { androidImages: null, iphoneDir: null, androidAssets: null }
+}
+
+function listChildDirs(parent, regex) {
+  if (!fs.existsSync(parent)) return []
+  return fs.readdirSync(parent)
+    .filter((name) => regex.test(name))
+    .map((name) => path.join(parent, name))
+    .filter((p) => fs.statSync(p).isDirectory())
+}
+
+function listChildFiles(parent, regex) {
+  if (!fs.existsSync(parent)) return []
+  return fs.readdirSync(parent)
+    .filter((name) => regex.test(name))
+    .map((name) => path.join(parent, name))
+    .filter((p) => fs.statSync(p).isFile())
+}
+
+function getSizeBytes(target) {
+  try {
+    const stat = fs.statSync(target)
+    if (stat.isFile()) return stat.size
+    let total = 0
+    for (const name of fs.readdirSync(target)) {
+      total += getSizeBytes(path.join(target, name))
+    }
+    return total
+  } catch {
+    return 0
+  }
+}
+
+function formatKb(bytes) {
+  return `${Math.round(bytes / 1024)}K`
+}
+
+function printPlan({ projectRoot, projectType, tiapp, adaptive, aggressive, safe, conditional, aggressiveTargets }) {
+  console.log()
+  logger.warning('⚠  WARNING — --cleanup-legacy deletes files permanently.')
+  logger.warning('   Recommended: commit your project with git before running without --dry-run.')
+  console.log()
+  console.log('Cleanup plan')
+  console.log(`  Project:            ${projectRoot} (${projectType})`)
+  console.log(`  Storyboard:         ${tiapp.storyboardEnabled ? 'enabled' : 'disabled'}`)
+  console.log(`  Orientation:        ${tiapp.portraitOnly ? 'portrait-only' : 'landscape allowed'}`)
+  console.log(`  Adaptive icons:     ${adaptive ? 'present' : 'not detected'}`)
+  console.log(`  Aggressive mode:    ${aggressive ? 'on (includes ldpi)' : 'off'}`)
+
+  if (safe.length) {
+    console.log()
+    logger.success('SAFE — universally obsolete')
+    for (const { path: p, reason } of safe) {
+      console.log(`    ${formatKb(getSizeBytes(p)).padEnd(6)}  ${path.relative(projectRoot, p)}`)
+      console.log(`              ${reason}`)
+    }
+  }
+  if (conditional.length) {
+    console.log()
+    logger.warning('CONDITIONAL — safe given your project config')
+    for (const { path: p, reason } of conditional) {
+      console.log(`    ${formatKb(getSizeBytes(p)).padEnd(6)}  ${path.relative(projectRoot, p)}`)
+      console.log(`              ${reason}`)
+    }
+  }
+  if (aggressiveTargets.length) {
+    console.log()
+    logger.error('AGGRESSIVE — --aggressive enabled')
+    for (const { path: p, reason } of aggressiveTargets) {
+      console.log(`    ${formatKb(getSizeBytes(p)).padEnd(6)}  ${path.relative(projectRoot, p)}`)
+      console.log(`              ${reason}`)
+    }
+  }
+  const total = safe.length + conditional.length + aggressiveTargets.length
+  console.log()
+  console.log(`  Total: ${total} item(s) to remove`)
+}

package/src/core/branding/ensure-brand-section.js

@@ -0,0 +1,80 @@
+/**
+ * PurgeTSS - Ensure `brand:` section exists in purgetss/config.cjs
+ *
+ * When a project was initialized before `brand` was introduced, its
+ * config.cjs won't have a `brand:` section. On first invocation of
+ * `purgetss brand`, we patch the file to insert the default block
+ * between `purge:` and `theme:`. The user's existing keys are untouched.
+ *
+ * Rationale:
+ * - Keeps the config self-documenting — the user sees the defaults in
+ *   their own file rather than having to look them up in docs.
+ * - Mirrors how `ensureConfig()` creates the file from the template when
+ *   it's missing altogether.
+ * - Non-destructive: only adds if absent, never overwrites existing values.
+ *
+ * @fileoverview Auto-injects the `brand:` section on first brand run
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import chalk from 'chalk'
+import { projectsConfigJS, projectsPurge_TSS_Brand_Folder } from '../../shared/constants.js'
+import { logger } from './branding-logger.js'
+
+const BRAND_BLOCK = `  brand: {
+    splash: false,           // also generate splash_icon.png × 5
+    padding: '15%',          // Android safe-zone. Range: 12% tight (mature logos) — 20% conservative. Spec floor 19.44%.
+    iosPadding: '4%',        // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
+    darkBgColor: null,       // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
+    bgColor: '#FFFFFF',      // Android adaptive bg + iOS/marketplace flatten
+    notification: false,     // also generate ic_stat_notify.png × 5
+    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+  },
+`
+
+/**
+ * If the project's config.cjs exists but has no `brand:` key, inject the
+ * default block between `purge:` and `theme:`. Prints a notice when it does.
+ *
+ * Silently skips if:
+ *   - config.cjs doesn't exist (will be created by ensureConfig() elsewhere)
+ *   - `brand:` is already present
+ *   - file can't be patched safely (structure doesn't match expectation)
+ */
+export function ensureBrandSection() {
+  // Always make sure the logos folder exists — mirrors how init creates
+  // `purgetss/fonts/` empty so the user can see where assets go.
+  if (!fs.existsSync(projectsPurge_TSS_Brand_Folder)) {
+    fs.mkdirSync(projectsPurge_TSS_Brand_Folder, { recursive: true })
+  }
+
+  if (!fs.existsSync(projectsConfigJS)) return
+
+  const original = fs.readFileSync(projectsConfigJS, 'utf8')
+
+  // Already present — nothing to do.
+  if (/^\s*brand\s*:/m.test(original)) return
+
+  // Insert before the `theme:` key. Regex captures the indentation so we
+  // preserve whatever the user's style is (2-space, 4-space, etc.).
+  const match = original.match(/(^\s*)theme\s*:/m)
+  if (!match) {
+    // Non-standard layout — don't risk corrupting it. User can add manually.
+    return
+  }
+
+  const patched = original.replace(match[0], `${BRAND_BLOCK}${match[0]}`)
+
+  try {
+    fs.writeFileSync(projectsConfigJS, patched, 'utf8')
+    console.log()
+    logger.success(`Added ${chalk.cyan('brand:')} section to ${chalk.cyan('./purgetss/config.cjs')} with default values.`)
+    console.log('  Edit that block to customize brand defaults (bgColor, padding, etc.).')
+    console.log('  CLI flags always win over config values.')
+    console.log()
+  } catch (err) {
+    logger.warning(`Could not auto-add brand: section to config.cjs (${err.message}).`)
+    logger.warning('The command will still run using built-in defaults.')
+  }
+}

package/src/core/branding/gen-android-adaptive.js

@@ -0,0 +1,116 @@
+/**
+ * PurgeTSS - gen-android-adaptive
+ *
+ * Adaptive icon triplet (foreground + background + monochrome) at 5 densities.
+ *
+ * Android adaptive icon: 108×108dp canvas, 66×66dp safe-zone.
+ * Densities: mdpi=108, hdpi=162, xhdpi=216, xxhdpi=324, xxxhdpi=432.
+ *
+ *   foreground:  logo centered inside safe-zone, transparent outside
+ *   background:  solid color filling the full canvas
+ *   monochrome:  foreground silhouette in white, alpha preserved
+ *                (Android applies themed tint at runtime on API 31+ — this
+ *                 layer is Android's dark/light mode mechanism for app icons)
+ *
+ * @fileoverview Android adaptive icons × 5 densities
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+export const DENSITIES = [
+  { name: 'mdpi', size: 108 },
+  { name: 'hdpi', size: 162 },
+  { name: 'xhdpi', size: 216 },
+  { name: 'xxhdpi', size: 324 },
+  { name: 'xxxhdpi', size: 432 }
+]
+
+export async function genAndroidAdaptive(tightMaster, bgColor, paddingPct, resRoot, opts = {}) {
+  const { monoTight = null } = opts
+  const generated = []
+
+  for (const { name, size } of DENSITIES) {
+    const inner = Math.floor((size * (100 - 2 * paddingPct)) / 100)
+    const dir = path.join(resRoot, `mipmap-${name}`)
+    fs.mkdirSync(dir, { recursive: true })
+
+    const foregroundPath = path.join(dir, 'ic_launcher_foreground.png')
+    const backgroundPath = path.join(dir, 'ic_launcher_background.png')
+    const monochromePath = path.join(dir, 'ic_launcher_monochrome.png')
+
+    // Foreground: logo sized to inner, centered on transparent canvas
+    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(foregroundPath)
+
+    // Background: solid color
+    await sharp({
+      create: {
+        width: size,
+        height: size,
+        channels: 4,
+        background: bgColor
+      }
+    })
+      .png({ compressionLevel: 9 })
+      .toFile(backgroundPath)
+
+    // Monochrome: white silhouette with preserved alpha.
+    if (monoTight) {
+      const innerMono = await sharp(monoTight)
+        .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: innerMono, gravity: 'center' }])
+        .ensureAlpha()
+        .linear([0, 0, 0, 1], [255, 255, 255, 0])
+        .png({ compressionLevel: 9 })
+        .toFile(monochromePath)
+    } else {
+      await sharp(foregroundPath)
+        .ensureAlpha()
+        .linear([0, 0, 0, 1], [255, 255, 255, 0])
+        .png({ compressionLevel: 9 })
+        .toFile(monochromePath)
+    }
+
+    generated.push(foregroundPath, backgroundPath, monochromePath)
+  }
+
+  fs.mkdirSync(path.join(resRoot, 'mipmap-anydpi-v26'), { recursive: true })
+
+  return generated
+}

package/src/core/branding/gen-android-legacy.js

@@ -0,0 +1,63 @@
+/**
+ * PurgeTSS - gen-android-legacy
+ *
+ * Flat ic_launcher.png for pre-adaptive Android (API 21–25, ~3% of users in 2026).
+ * Composites foreground over background, scaled to legacy launcher sizes.
+ *
+ * Legacy densities: mdpi=48, hdpi=72, xhdpi=96, xxhdpi=144, xxxhdpi=192.
+ *
+ * @fileoverview Legacy ic_launcher.png × 5 densities
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+export const LEGACY_DENSITIES = [
+  { name: 'mdpi', size: 48 },
+  { name: 'hdpi', size: 72 },
+  { name: 'xhdpi', size: 96 },
+  { name: 'xxhdpi', size: 144 },
+  { name: 'xxxhdpi', size: 192 }
+]
+
+export async function genAndroidLegacy(tightMaster, bgColor, paddingPct, resRoot) {
+  const generated = []
+  // Legacy icons have no adaptive mask — they render as drawn. Use ~60% of
+  // the adaptive padding so the logo fills more of the canvas.
+  const legacyPadding = Math.floor((paddingPct * 60) / 100)
+
+  for (const { name, size } of LEGACY_DENSITIES) {
+    const inner = Math.floor((size * (100 - 2 * legacyPadding)) / 100)
+    const dir = path.join(resRoot, `mipmap-${name}`)
+    fs.mkdirSync(dir, { recursive: true })
+
+    const outPath = path.join(dir, 'ic_launcher.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: bgColor
+      }
+    })
+      .composite([{ input: innerLogo, gravity: 'center' }])
+      .png({ compressionLevel: 9 })
+      .toFile(outPath)
+
+    generated.push(outPath)
+  }
+
+  return generated
+}

package/src/core/branding/gen-ic-launcher-xml.js

@@ -0,0 +1,29 @@
+/**
+ * PurgeTSS - gen-ic-launcher-xml
+ *
+ * Writes the adaptive-icon XML binder to mipmap-anydpi-v26/ic_launcher.xml.
+ * Titanium/Android loads this file on API 26+ to pick up the adaptive icon triplet
+ * (foreground + background + monochrome).
+ *
+ * @fileoverview Adaptive-icon XML binder
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+
+export const IC_LAUNCHER_XML = `<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@mipmap/ic_launcher_background"/>
+  <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
+  <monochrome android:drawable="@mipmap/ic_launcher_monochrome"/>
+</adaptive-icon>
+`
+
+export function genIcLauncherXml(resRoot) {
+  const dir = path.join(resRoot, 'mipmap-anydpi-v26')
+  fs.mkdirSync(dir, { recursive: true })
+  const outPath = path.join(dir, 'ic_launcher.xml')
+  fs.writeFileSync(outPath, IC_LAUNCHER_XML, 'utf8')
+  return outPath
+}

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

@@ -0,0 +1,70 @@
+/**
+ * PurgeTSS - gen-ios-dark
+ *
+ * Produces Titanium's iOS 18+ dark-mode root icon:
+ *
+ *   DefaultIcon-Dark.png   1024×1024, transparent (default) or flattened on dark bg
+ *
+ * Per Apple HIG (iOS 18+): the dark variant may either (a) omit the background
+ * so the system applies its own dark gradient, or (b) use an opaque dark tint.
+ * Default here is (a) — transparent — per Apple's recommended approach.
+ *
+ * Titanium SDK 13.1+ is expected to read this file from the project root, but
+ * upstream issue tidev/titanium-sdk#14122 is not yet merged — until then, the
+ * user may need to manually place the PNG inside Assets.xcassets/AppIcon.appiconset.
+ *
+ * @fileoverview iOS 18+ dark icon variant
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+const CANVAS = 1024
+
+/**
+ * @param {string} tightMaster - Main tight master, or --dark-master output
+ * @param {string|null} bgColor - Hex color for opaque flatten, or null for transparent
+ * @param {number} paddingPct - Padding per side (0-40)
+ * @param {string} outRoot - Output directory
+ * @returns {Promise<string>} Path to DefaultIcon-Dark.png
+ */
+export async function genIosDark(tightMaster, bgColor, paddingPct, outRoot) {
+  fs.mkdirSync(outRoot, { recursive: true })
+
+  const inner = Math.floor((CANVAS * (100 - 2 * paddingPct)) / 100)
+  const outPath = path.join(outRoot, 'DefaultIcon-Dark.png')
+
+  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 (bgColor) {
+    // Opaque variant: flatten on dark tint, strip alpha entirely.
+    await pipeline
+      .flatten({ background: bgColor })
+      .removeAlpha()
+      .png({ compressionLevel: 9 })
+      .toFile(outPath)
+  } else {
+    // Apple-recommended default: preserve alpha. System paints its own dark gradient.
+    await pipeline.png({ compressionLevel: 9 }).toFile(outPath)
+  }
+
+  return outPath
+}

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

@@ -0,0 +1,55 @@
+/**
+ * PurgeTSS - gen-ios-tinted
+ *
+ * Produces Titanium's iOS 18+ tinted root icon:
+ *
+ *   DefaultIcon-Tinted.png   1024×1024, grayscale flattened on black
+ *
+ * Per Apple HIG (iOS 18+): the tinted variant must be a fully opaque grayscale
+ * image over a BLACK (#000000) background. iOS composites its own gradient
+ * background and accent color on top of the grayscale luminance at runtime.
+ *
+ * @fileoverview iOS 18+ tinted icon variant
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+const CANVAS = 1024
+
+export async function genIosTinted(tightMaster, paddingPct, outRoot) {
+  fs.mkdirSync(outRoot, { recursive: true })
+
+  const inner = Math.floor((CANVAS * (100 - 2 * paddingPct)) / 100)
+  const outPath = path.join(outRoot, 'DefaultIcon-Tinted.png')
+
+  // Grayscale the master while keeping alpha — iOS needs luminance info,
+  // not color, to apply the system accent tint at runtime.
+  const resized = await sharp(tightMaster)
+    .grayscale()
+    .resize({
+      width: inner,
+      height: inner,
+      fit: 'inside',
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .toBuffer()
+
+  await sharp({
+    create: {
+      width: CANVAS,
+      height: CANVAS,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    }
+  })
+    .composite([{ input: resized, gravity: 'center' }])
+    .flatten({ background: '#000000' })
+    .removeAlpha()
+    .png({ compressionLevel: 9 })
+    .toFile(outPath)
+
+  return outPath
+}