v3.0.0

[3.0.0] - 2026-05-10

Breaking Changes

v2.x	v3.0
-h <n> (height)	--height <n>
-H, --help	-h, --help (standard)
-p ti-branding [--adaptive …]	imgconvert brand <master> --sdk android [--adaptive …]
-p alloy --modern	removed; use brand subcommand
-p alloy (legacy multi-scale)	imgconvert alloy <source>
imgconvert config	imgconvert config init
--replace-originals	--replace (old name kept as hidden alias)

• imgconvert brand requires --sdk <target> — no more default. Valid target: android (kotlin, react-native, flutter planned for a future release). For Titanium projects, use purgetss brand which has first-class support (master auto-discovery from ./purgetss/brand/, config file integration, etc.).
• DefaultIcon.png padding semantics changed — imgconvert brand no longer accepts --ios-padding. The universal DefaultIcon.png now uses --padding (the Android safe-zone) because Android falls back to it when adaptive icons aren't present, keeping the logo launcher-mask-safe.

New Features

• Commander.js subcommands: brand, alloy, config, help as first-class subcommands
• Per-subcommand --help: imgconvert brand --help shows only brand flags
• Topic-based help: imgconvert help <topic> for crop, resize, rename, presets, brand, alloy
• Shell completions (bash / zsh / fish) via imgconvert completions subcommand:
  • imgconvert completions — interactive install (auto-detects shell from $SHELL)
  • imgconvert completions <shell> — direct install for bash, zsh, or fish
  • imgconvert completions uninstall — removes every installed completion file and the rc-file block it added
  • imgconvert completions print <shell> — prints the script to stdout (for scripts / CI / custom install paths)
  • Installs are idempotent (no duplicate fpath block on re-runs), guarded by marker comments in ~/.zshrc.
  • zsh output uses _describe under the group header imgconvert commands, so subcommands render in column format with descriptions.
• Typo suggestions: Unknown commands suggest the closest match
• Update notifications: Notified when a newer version is available (respects IMGCONVERT_NO_UPDATE_CHECK=1)
• Standard -h for help: Follows CLI conventions (was height in v2)
• InvalidArgumentError: Clean error messages for invalid --width, --height, --quality
• --sdk <target> for brand: Target android emits the standard Android res/ tree at app/src/main/res/. More SDK targets (kotlin, react-native, flutter) planned for a future release.
• --canvas symmetric resize: pads when the target is larger AND crops when the target is smaller. --position controls the anchor in both directions — e.g. --canvas --height 2688 --position top keeps the top of the image and drops pixels from the bottom.

Other

• gen-ios() now accepts both androidPadding and iosPadding so DefaultIcon.png and DefaultIcon-ios.png can use different values (Android safe-zone vs iOS aesthetic).
• Default --padding lowered from 20 to 15 (matches real-world apps like Gmail/Chrome; range 12-20). Spec floor is 19.44% but modern launchers are permissive; 15% gives logos better visual presence while staying safe on circular-mask launchers (Pixel, Oppo).

Legacy-Compatibility Shims

To ease the v2 → v3 transition, two shims rewrite argv and emit a deprecation warning on stderr. Both will be removed in v4.

• -h <positive-int> is rewritten to --height <n>
• imgconvert config (no subcommand) is rewritten to imgconvert config init