@maccesar/titools 2.5.1 → 2.6.0

package/skills/ti-branding/scripts/lib/cleanup-legacy.sh

@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+# cleanup-legacy.sh — context-aware removal of legacy branding artifacts.
+#
+# Reads tiapp.xml to decide what's safe to delete. Categorizes targets into:
+#
+#   SAFE          always deleted — universally obsolete (dead qualifiers etc.)
+#   CONDITIONAL   deleted only when project config guarantees they're unused
+#                 (e.g. iOS legacy launch images when storyboard is enabled)
+#   AGGRESSIVE    behind --aggressive flag — strongly defensible but some
+#                 edge cases remain (e.g. ldpi drawables on <1% of devices)
+#
+# Always prints the plan before acting. Respects --dry-run.
+
+# Append "path|reason" pair to a named array in a bash-3.2-compatible way.
+_add_target() {
+  local array_name="$1"
+  local path="$2"
+  local reason="$3"
+  eval "$array_name+=(\"\$path|\$reason\")"
+}
+
+cleanup_legacy() {
+  local project_root="$1"
+  local project_type="$2"
+  local aggressive="$3"
+  local dry_run="$4"
+
+  local tiapp="$project_root/tiapp.xml"
+  local storyboard_enabled=0
+  local portrait_only=0
+
+  if [[ -f "$tiapp" ]]; then
+    grep -q "<enable-launch-screen-storyboard>true" "$tiapp" && storyboard_enabled=1
+    # Portrait-only heuristic: <orientations> block contains UIInterfaceOrientationPortrait
+    # for iphone AND no Landscape entries.
+    if grep -q '<orientations' "$tiapp" && \
+       ! grep -iqE 'UIInterfaceOrientationLandscape' "$tiapp"; then
+      portrait_only=1
+    fi
+  fi
+
+  local android_images=""
+  local iphone_dir=""
+  local android_assets=""
+  case "$project_type" in
+    alloy)
+      android_images="$project_root/app/assets/android/images"
+      iphone_dir="$project_root/app/assets/iphone"
+      android_assets="$project_root/app/assets/android"
+      ;;
+    classic)
+      android_images="$project_root/Resources/android/images"
+      iphone_dir="$project_root/Resources/iphone"
+      android_assets="$project_root/Resources/android"
+      ;;
+  esac
+
+  local has_adaptive=0
+  [[ -d "$project_root/app/platform/android/res/mipmap-anydpi-v26" ]] && has_adaptive=1
+  [[ -d "$project_root/platform/android/res/mipmap-anydpi-v26" ]] && has_adaptive=1
+
+  local safe_targets=()
+  local cond_targets=()
+  local aggressive_targets=()
+
+  # -------------------------------------------------------------------------
+  # SAFE
+  # -------------------------------------------------------------------------
+
+  if [[ -n "$android_images" && -d "$android_images" ]]; then
+    local d
+    for d in "$android_images"/res-long-* "$android_images"/res-notlong-*; do
+      [[ -d "$d" ]] && _add_target safe_targets "$d" "Android long/notlong qualifier (dead since Android 3.0, 2011)"
+    done
+  fi
+
+  # -------------------------------------------------------------------------
+  # CONDITIONAL
+  # -------------------------------------------------------------------------
+
+  # iOS legacy launch images — only safe with storyboard enabled
+  if [[ $storyboard_enabled -eq 1 && -n "$iphone_dir" && -d "$iphone_dir" ]]; then
+    local f
+    for f in "$iphone_dir"/Default-*.png "$iphone_dir"/Default@2x.png; do
+      [[ -f "$f" ]] && _add_target cond_targets "$f" "iOS legacy launch image (storyboard enabled → not consulted)"
+    done
+  fi
+
+  # Android landscape-variant folders — safe when app is portrait-only
+  if [[ $portrait_only -eq 1 && -n "$android_images" && -d "$android_images" ]]; then
+    local d
+    for d in "$android_images"/res-*-land-* "$android_images"/res-land-*; do
+      [[ -d "$d" ]] && _add_target cond_targets "$d" "Landscape variant (app is portrait-only)"
+    done
+  fi
+
+  # Android legacy splash PNG — safe when adaptive icons are in place
+  if [[ $has_adaptive -eq 1 && -n "$android_assets" && -f "$android_assets/default.png" ]]; then
+    _add_target cond_targets "$android_assets/default.png" "Legacy Android splash PNG (adaptive launcher handles splash now)"
+  fi
+
+  # Android legacy appicon.png — redundant when adaptive icons are in place
+  if [[ $has_adaptive -eq 1 && -n "$android_assets" && -f "$android_assets/appicon.png" ]]; then
+    _add_target cond_targets "$android_assets/appicon.png" "Legacy appicon.png (adaptive launcher takes precedence)"
+  fi
+
+  # -------------------------------------------------------------------------
+  # AGGRESSIVE
+  # -------------------------------------------------------------------------
+
+  if [[ $aggressive -eq 1 ]]; then
+    # ldpi everywhere — <1% of active devices globally in 2026
+    local d
+    if [[ -n "$android_images" && -d "$android_images" ]]; then
+      for d in "$android_images"/res-ldpi "$android_images"/res-*-ldpi; do
+        [[ -d "$d" ]] && _add_target aggressive_targets "$d" "ldpi density (<1% global market)"
+      done
+    fi
+    for d in "$project_root/app/platform/android/res/drawable-ldpi" \
+             "$project_root/app/platform/android/res/values-ldpi" \
+             "$project_root/app/platform/android/res/mipmap-ldpi" \
+             "$project_root/platform/android/res/drawable-ldpi" \
+             "$project_root/platform/android/res/values-ldpi" \
+             "$project_root/platform/android/res/mipmap-ldpi"; do
+      [[ -d "$d" ]] && _add_target aggressive_targets "$d" "ldpi resource folder (<1% global market)"
+    done
+  fi
+
+  # -------------------------------------------------------------------------
+  # Print plan
+  # -------------------------------------------------------------------------
+
+  echo
+  echo "${C_YELLOW}⚠  WARNING${C_RESET} — --cleanup-legacy deletes files permanently."
+  echo "   Recommended: commit your project with git before running without --dry-run."
+  echo "   Provided AS IS under the MIT License. No warranty — use at your own risk."
+  echo
+  echo "${C_BOLD}Cleanup plan${C_RESET}"
+  echo "  ${C_DIM}Project:            $project_root ($project_type)${C_RESET}"
+  echo "  ${C_DIM}Storyboard:         $([[ $storyboard_enabled -eq 1 ]] && echo "enabled" || echo "disabled")${C_RESET}"
+  echo "  ${C_DIM}Orientation:        $([[ $portrait_only -eq 1 ]] && echo "portrait-only" || echo "landscape allowed")${C_RESET}"
+  echo "  ${C_DIM}Adaptive icons:     $([[ $has_adaptive -eq 1 ]] && echo "present" || echo "not detected")${C_RESET}"
+  echo "  ${C_DIM}Aggressive mode:    $([[ $aggressive -eq 1 ]] && echo "on (includes ldpi)" || echo "off")${C_RESET}"
+
+  local total=$(( ${#safe_targets[@]} + ${#cond_targets[@]} + ${#aggressive_targets[@]} ))
+
+  if [[ $total -eq 0 ]]; then
+    echo
+    log_ok "No legacy artifacts detected. Project is already clean."
+    return 0
+  fi
+
+  # bash 3.2 under `set -u` errors on "${empty_array[@]}" — iterate per-bucket
+  # with explicit length guards instead of expanding empty arrays into args.
+  _print_bucket_safe() {
+    local t path reason size
+    echo
+    echo "${C_GREEN}SAFE — universally obsolete${C_RESET}"
+    for t in "${safe_targets[@]}"; do
+      path="${t%%|*}"; reason="${t#*|}"
+      size=$(du -sk "$path" 2>/dev/null | awk '{print $1}')
+      [[ -z "$size" ]] && size=0
+      printf "    %-6sK  %s\n" "$size" "${path#$project_root/}"
+      printf "              ${C_DIM}%s${C_RESET}\n" "$reason"
+    done
+  }
+  _print_bucket_cond() {
+    local t path reason size
+    echo
+    echo "${C_YELLOW}CONDITIONAL — safe given your project config${C_RESET}"
+    for t in "${cond_targets[@]}"; do
+      path="${t%%|*}"; reason="${t#*|}"
+      size=$(du -sk "$path" 2>/dev/null | awk '{print $1}')
+      [[ -z "$size" ]] && size=0
+      printf "    %-6sK  %s\n" "$size" "${path#$project_root/}"
+      printf "              ${C_DIM}%s${C_RESET}\n" "$reason"
+    done
+  }
+  _print_bucket_aggr() {
+    local t path reason size
+    echo
+    echo "${C_RED}AGGRESSIVE — --aggressive enabled${C_RESET}"
+    for t in "${aggressive_targets[@]}"; do
+      path="${t%%|*}"; reason="${t#*|}"
+      size=$(du -sk "$path" 2>/dev/null | awk '{print $1}')
+      [[ -z "$size" ]] && size=0
+      printf "    %-6sK  %s\n" "$size" "${path#$project_root/}"
+      printf "              ${C_DIM}%s${C_RESET}\n" "$reason"
+    done
+  }
+
+  [[ ${#safe_targets[@]} -gt 0 ]] && _print_bucket_safe
+  [[ ${#cond_targets[@]} -gt 0 ]] && _print_bucket_cond
+  [[ ${#aggressive_targets[@]} -gt 0 ]] && _print_bucket_aggr
+
+  echo
+  echo "  ${C_BOLD}Total: $total item(s) to remove${C_RESET}"
+
+  if [[ $dry_run -eq 1 ]]; then
+    echo
+    log_info "Dry-run mode — nothing deleted. Re-run without --dry-run to apply."
+    return 0
+  fi
+
+  # -------------------------------------------------------------------------
+  # Apply
+  # -------------------------------------------------------------------------
+
+  echo
+  log_step "Applying cleanup"
+  local t path
+  if [[ ${#safe_targets[@]} -gt 0 ]]; then
+    for t in "${safe_targets[@]}"; do
+      path="${t%%|*}"; rm -rf "$path"
+      log_ok "Removed ${path#$project_root/}"
+    done
+  fi
+  if [[ ${#cond_targets[@]} -gt 0 ]]; then
+    for t in "${cond_targets[@]}"; do
+      path="${t%%|*}"; rm -rf "$path"
+      log_ok "Removed ${path#$project_root/}"
+    done
+  fi
+  if [[ ${#aggressive_targets[@]} -gt 0 ]]; then
+    for t in "${aggressive_targets[@]}"; do
+      path="${t%%|*}"; rm -rf "$path"
+      log_ok "Removed ${path#$project_root/}"
+    done
+  fi
+}

package/skills/ti-branding/scripts/lib/deps.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# deps.sh — detect required system tools and guide installation.
+
+check_deps() {
+  local master="$1"
+  local need_rsvg=0
+  local missing=()
+
+  local master_lower
+  master_lower=$(printf '%s' "$master" | tr '[:upper:]' '[:lower:]')
+  case "$master_lower" in
+    *.svg) need_rsvg=1 ;;
+  esac
+
+  if ! command -v magick >/dev/null 2>&1; then
+    missing+=("imagemagick")
+  fi
+
+  if [[ $need_rsvg -eq 1 ]] && ! command -v rsvg-convert >/dev/null 2>&1; then
+    missing+=("librsvg")
+  fi
+
+  if [[ ${#missing[@]} -eq 0 ]]; then
+    log_ok "All dependencies present: $(magick -version | head -1 | awk '{print $2,$3}')"
+    [[ $need_rsvg -eq 1 ]] && log_ok "librsvg: $(rsvg-convert --version | head -1)"
+    return 0
+  fi
+
+  log_err "Missing required tools: ${missing[*]}"
+  echo
+  echo "Install with one of:"
+  local os="$(uname -s)"
+  case "$os" in
+    Darwin)
+      echo "  macOS:      brew install ${missing[*]}"
+      ;;
+    Linux)
+      if command -v apt >/dev/null 2>&1; then
+        local apt_pkgs=()
+        for m in "${missing[@]}"; do
+          case "$m" in
+            imagemagick) apt_pkgs+=("imagemagick") ;;
+            librsvg)     apt_pkgs+=("librsvg2-bin") ;;
+          esac
+        done
+        echo "  Ubuntu:     sudo apt install ${apt_pkgs[*]}"
+      elif command -v pacman >/dev/null 2>&1; then
+        echo "  Arch:       sudo pacman -S ${missing[*]}"
+      elif command -v dnf >/dev/null 2>&1; then
+        echo "  Fedora:     sudo dnf install ${missing[*]}"
+      fi
+      ;;
+  esac
+  echo "  Windows:    choco install ${missing[*]}"
+  echo
+  echo "After installing, re-run this command."
+  exit 1
+}

package/skills/ti-branding/scripts/lib/gen-android-adaptive.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# gen-android-adaptive.sh — produce the adaptive icon triplet (foreground +
+# background + monochrome) at 5 densities.
+#
+# Android adaptive icon: 108×108dp canvas, 66×66dp safe-zone.
+# Densities: mdpi=108px, hdpi=162, xhdpi=216, xxhdpi=324, xxxhdpi=432.
+#
+# Foreground: logo centered inside safe-zone, transparent outside.
+# Background: solid color (or pattern) filling the full canvas.
+# Monochrome: foreground silhouette in pure white with preserved alpha — Android
+#             applies themed tint at runtime on API 31+.
+
+gen_android_adaptive() {
+  local master="$1"
+  local bg="$2"
+  local padding="$3"      # percent per side
+  local res_root="$4"     # e.g. /path/app/platform/android/res
+
+  local densities=(mdpi hdpi xhdpi xxhdpi xxxhdpi)
+  local sizes=(108 162 216 324 432)
+
+  for i in "${!densities[@]}"; do
+    local d="${densities[$i]}"
+    local size="${sizes[$i]}"
+    local inner=$(( size * (100 - 2 * padding) / 100 ))
+    local dir="$res_root/mipmap-$d"
+    mkdir -p "$dir"
+
+    # Foreground: logo centered, padded, transparent outside
+    magick "$master" \
+      -resize "${inner}x${inner}" \
+      -background none -gravity center -extent "${size}x${size}" \
+      -strip \
+      "$dir/ic_launcher_foreground.png"
+
+    # Background: solid color
+    magick -size "${size}x${size}" "xc:$bg" \
+      -strip \
+      "$dir/ic_launcher_background.png"
+
+    # Monochrome: foreground tinted to pure white, alpha preserved
+    magick "$dir/ic_launcher_foreground.png" \
+      -channel RGB -fill white -colorize 100 +channel \
+      -strip \
+      "$dir/ic_launcher_monochrome.png"
+  done
+
+  # anydpi-v26 binder directory (XML copied by caller from assets/ic_launcher.xml)
+  mkdir -p "$res_root/mipmap-anydpi-v26"
+
+  log_ok "Adaptive icons: foreground + background + monochrome × 5 densities"
+}

package/skills/ti-branding/scripts/lib/gen-android-legacy.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# gen-android-legacy.sh — produce the flat ic_launcher.png for pre-adaptive Android
+# (API 21–25, ~3% of users in 2026). Composites foreground over background and
+# scales down to the legacy density sizes.
+#
+# Legacy densities: mdpi=48px, hdpi=72, xhdpi=96, xxhdpi=144, xxxhdpi=192.
+
+gen_android_legacy() {
+  local master="$1"
+  local bg="$2"
+  local padding="$3"
+  local res_root="$4"
+
+  local densities=(mdpi hdpi xhdpi xxhdpi xxxhdpi)
+  local sizes=(48 72 96 144 192)
+
+  for i in "${!densities[@]}"; do
+    local d="${densities[$i]}"
+    local size="${sizes[$i]}"
+    # Legacy icons are displayed as-drawn (no adaptive mask), so we can fill more of
+    # the canvas. Reduce the padding by ~40% for the legacy composite.
+    local legacy_padding=$(( padding * 60 / 100 ))
+    local inner=$(( size * (100 - 2 * legacy_padding) / 100 ))
+    local dir="$res_root/mipmap-$d"
+    mkdir -p "$dir"
+
+    # Compose: solid bg + logo centered
+    magick -size "${size}x${size}" "xc:$bg" \
+      \( "$master" -resize "${inner}x${inner}" \) \
+      -gravity center -composite \
+      -strip \
+      "$dir/ic_launcher.png"
+  done
+
+  log_ok "Legacy ic_launcher.png × 5 densities (fallback for Android <8)"
+}

package/skills/ti-branding/scripts/lib/gen-ios.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# gen-ios.sh — produce DefaultIcon-ios.png (1024×1024, alpha flattened over bg-color).
+#
+# Unlike Android adaptive icons, iOS app icons have no "safe zone" — the launcher
+# doesn't mask them. What you see is what ships. So padding is purely visual
+# breathing room around the logo. Default 8% per side (logo fills 84% of the
+# canvas), which matches Apple's HIG aesthetic for branded wordmarks.
+#
+# iOS rejects icons with alpha, so the final output is flattened over bg-color.
+
+gen_ios() {
+  local tight="$1"        # tight master (aspect-preserved, transparent bg)
+  local bg="$2"
+  local padding="$3"      # iOS padding percent per side (default 8)
+  local out_root="$4"
+
+  mkdir -p "$out_root"
+
+  local size=1024
+  local inner=$(( size * (100 - 2 * padding) / 100 ))
+
+  magick "$tight" \
+    -resize "${inner}x${inner}" \
+    -background none -gravity center -extent "${size}x${size}" \
+    -background "$bg" -alpha remove -alpha off \
+    -strip \
+    "$out_root/DefaultIcon-ios.png"
+
+  log_ok "DefaultIcon-ios.png (1024×1024, ${padding}% padding, alpha flattened over $bg)"
+}

package/skills/ti-branding/scripts/lib/gen-marketplace.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# gen-marketplace.sh — store-submission artwork.
+#
+#   iTunesConnect.png:     1024×1024, no alpha (App Store)
+#   MarketplaceArtwork.png: 512×512, no alpha (Google Play)
+#
+# Uses the same --ios-padding as the iOS master (default 8%). Store assets are
+# scrutinized at large sizes and need visual breathing room — no safe-zone to
+# comply with, but aesthetically they should match the DefaultIcon-ios look.
+
+gen_marketplace() {
+  local tight="$1"
+  local bg="$2"
+  local padding="$3"      # ios-padding percent per side
+  local out_root="$4"
+
+  mkdir -p "$out_root"
+
+  # App Store (1024²)
+  local size_ios=1024
+  local inner_ios=$(( size_ios * (100 - 2 * padding) / 100 ))
+  magick "$tight" \
+    -resize "${inner_ios}x${inner_ios}" \
+    -background none -gravity center -extent "${size_ios}x${size_ios}" \
+    -background "$bg" -alpha remove -alpha off \
+    -strip \
+    "$out_root/iTunesConnect.png"
+
+  # Google Play (512²)
+  local size_play=512
+  local inner_play=$(( size_play * (100 - 2 * padding) / 100 ))
+  magick "$tight" \
+    -resize "${inner_play}x${inner_play}" \
+    -background none -gravity center -extent "${size_play}x${size_play}" \
+    -background "$bg" -alpha remove -alpha off \
+    -strip \
+    "$out_root/MarketplaceArtwork.png"
+
+  log_ok "Marketplace artwork: iTunesConnect.png (1024², ${padding}% padding), MarketplaceArtwork.png (512², ${padding}% padding)"
+}

package/skills/ti-branding/scripts/lib/gen-notification.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# gen-notification.sh — white-on-transparent notification icons at 5 densities.
+# Android applies a runtime tint based on the notification's color property, so
+# all non-transparent pixels become white and color information is discarded.
+#
+# Sizes per Android spec: mdpi=24px, hdpi=36, xhdpi=48, xxhdpi=72, xxxhdpi=96.
+
+gen_notification() {
+  local master="$1"
+  local padding="$2"
+  local res_root="$3"
+
+  local densities=(mdpi hdpi xhdpi xxhdpi xxxhdpi)
+  local sizes=(24 36 48 72 96)
+
+  for i in "${!densities[@]}"; do
+    local d="${densities[$i]}"
+    local size="${sizes[$i]}"
+    # Notification icons get pretty heavily masked in the status bar, so use
+    # slightly tighter padding than the full safe-zone.
+    local inner=$(( size * (100 - 2 * padding) / 100 ))
+    local dir="$res_root/drawable-$d"
+    mkdir -p "$dir"
+
+    magick "$master" \
+      -resize "${inner}x${inner}" \
+      -channel RGB -fill white -colorize 100 +channel \
+      -background none -gravity center -extent "${size}x${size}" \
+      -strip \
+      "$dir/ic_stat_notify.png"
+  done
+
+  log_ok "Notification icons (white+alpha) × 5 densities"
+}

package/skills/ti-branding/scripts/lib/gen-splash-icon.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# gen-splash-icon.sh — Android 12+ SplashScreen API icon.
+# The spec: 288dp canvas, icon occupies the central 192dp (~67% of canvas).
+# The OS renders a circular mask automatically, so keep the icon transparent
+# outside the 192dp safe-zone.
+#
+# Densities: mdpi=288px, hdpi=432, xhdpi=576, xxhdpi=864, xxxhdpi=1152.
+
+gen_splash_icon() {
+  local master="$1"
+  local res_root="$2"
+
+  local densities=(mdpi hdpi xhdpi xxhdpi xxxhdpi)
+  local sizes=(288 432 576 864 1152)
+
+  for i in "${!densities[@]}"; do
+    local d="${densities[$i]}"
+    local size="${sizes[$i]}"
+    local inner=$(( size * 192 / 288 ))
+    local dir="$res_root/drawable-$d"
+    mkdir -p "$dir"
+
+    magick "$master" \
+      -resize "${inner}x${inner}" \
+      -background none -gravity center -extent "${size}x${size}" \
+      -strip \
+      "$dir/splash_icon.png"
+  done
+
+  log_ok "Android 12+ splash_icon.png × 5 densities"
+}

package/skills/ti-branding/scripts/lib/prepare-master.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# prepare-master.sh — produces two normalized masters from the input:
+#
+#   1. <out>_square.png — 1024×1024 PNG with the logo centered in a square
+#      canvas and transparent padding added to sides (or top/bottom) to keep
+#      the logo's aspect intact. Used for iOS DefaultIcon and marketplace
+#      artwork — platforms that require square icons.
+#
+#   2. <out>_tight.png — logo rasterized at 1024-px max dimension with its
+#      native aspect preserved (no padding added). Used for Android adaptive
+#      icon generation so a horizontal wordmark can fill the safe-zone by
+#      width instead of being double-padded inside the square master.
+#
+# The skill's main script passes <out>_square.png to iOS generators and
+# <out>_tight.png to Android adaptive/legacy/notification/splash generators.
+
+prepare_master() {
+  local input="$1"
+  local base="$2"       # e.g. /path/.ti-branding/_master (no extension)
+  local square="${base}_square.png"
+  local tight="${base}_tight.png"
+  local ext="${input##*.}"
+  ext=$(printf '%s' "$ext" | tr '[:upper:]' '[:lower:]')
+
+  mkdir -p "$(dirname "$base")"
+
+  case "$ext" in
+    svg)
+      # Rasterize SVG at 2048-px max dimension preserving native aspect — this
+      # is the tight master. rsvg-convert's -a flag preserves aspect when both
+      # -w and -h are supplied, producing the larger of the two dimensions.
+      rsvg-convert -w 2048 -h 2048 -a "$input" -o "$tight.2x.png"
+      magick "$tight.2x.png" -resize "1024x1024>" -strip "$tight"
+      rm -f "$tight.2x.png"
+      ;;
+    png)
+      magick "$input" -resize "1024x1024>" -strip "$tight"
+      ;;
+  esac
+
+  # Build the square master by padding the tight master to 1024×1024 with
+  # transparency. magick's -gravity center + -extent centers the logo and
+  # distributes padding to whichever axis is shorter.
+  magick "$tight" \
+    -background none -gravity center -extent 1024x1024 \
+    -strip \
+    "$square"
+}

package/skills/ti-branding/scripts/lib/validate.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# validate.sh — sanity-check the master input.
+
+validate_master() {
+  local master="$1"
+  local ext="${master##*.}"
+  ext=$(printf '%s' "$ext" | tr '[:upper:]' '[:lower:]')
+
+  case "$ext" in
+    svg)
+      validate_svg "$master"
+      ;;
+    png)
+      validate_png "$master"
+      ;;
+    *)
+      log_err "Unsupported format: .$ext (expected .svg or .png)"
+      exit 2
+      ;;
+  esac
+}
+
+validate_svg() {
+  local master="$1"
+  if ! grep -q "<svg" "$master" 2>/dev/null; then
+    log_err "File does not appear to be valid SVG: $master"
+    exit 2
+  fi
+
+  if grep -qE '<(script|foreignObject)' "$master" 2>/dev/null; then
+    log_warn "SVG contains <script> or <foreignObject> — may not render correctly."
+  fi
+
+  log_ok "SVG input accepted (will rasterize to 1024×1024)"
+}
+
+validate_png() {
+  local master="$1"
+  local w h
+  w=$(magick identify -format "%w" "$master" 2>/dev/null || echo 0)
+  h=$(magick identify -format "%h" "$master" 2>/dev/null || echo 0)
+
+  if [[ -z "$w" || "$w" -eq 0 ]]; then
+    log_err "Could not read PNG dimensions: $master"
+    exit 2
+  fi
+
+  if [[ "$w" -lt 1024 || "$h" -lt 1024 ]]; then
+    log_err "PNG too small: ${w}×${h}. Need at least 1024×1024 for high-density output."
+    exit 2
+  fi
+
+  if [[ "$w" -ne "$h" ]]; then
+    log_warn "PNG is not square (${w}×${h}). Will be center-cropped to square."
+  fi
+
+  local has_alpha
+  has_alpha=$(magick identify -format "%A" "$master" 2>/dev/null)
+  case "$has_alpha" in
+    True|Blend)
+      log_ok "PNG ${w}×${h} with alpha — good for monochrome layer"
+      ;;
+    *)
+      log_warn "PNG ${w}×${h} has no alpha — monochrome layer will be a square silhouette"
+      ;;
+  esac
+}