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

v2.0.2 — splash guidance reframed as opt-in, not prescriptive

Reframes the Android splash guidance in `--notes` after real-world feedback. v2.0.1 was too prescriptive and recommended a parent theme (`Theme.Titanium.Light.NoTitle`) that doesn't exist in all Titanium SDK versions — users got build failures when copy-pasting the snippet.

What changed

The splash section in `--notes` is now marked "OPTIONAL, advanced" instead of "RECOMMENDED", leads with "for most apps the default is enough — do nothing", and the template uses a placeholder `@style/YOUR_APP_PARENT_THEME` with explicit instructions to verify the parent theme exists in the user's SDK before using it. Lists `Theme.Titanium.Light.Fullscreen` as known-working in SDK 13.2.0 but tells the user to double-check for their own SDK.

Also adds a pre-flight checklist before modifying tiapp.xml:

• Verify parent theme exists
• Check whether your project already has a custom theme (extend, don't override)
• Test the build succeeds before committing

The `--ios-padding` 4% default from v2.0.1 is preserved.

Impact

If you were following the v2.0.1 guidance and your build failed with `resource style/Theme.Titanium.Light.NoTitle not found`, revert your tiapp.xml change and either:

1. Skip the custom theme (Titanium default works for most apps, visible flicker is cosmetic)
2. Use `Theme.Titanium.Light.Fullscreen` as parent (verified in SDK 13.2.0)
3. Extend your app's existing theme if you already have one

v2.0.1 — splash theme guidance fix + --ios-padding default lowered to 4%

Two corrections based on real-world testing against production reference app (LM - La Baraja).

Fixed — Android splash theme guidance

Previously said never set android:theme on <application>. Too absolute — steered users away from the correct fix for the end-of-splash flicker. The narrower rule: don't inherit from @android:style/Theme.DeviceDefault.NoActionBar. Inheriting from a Titanium parent theme preserves the ActionBar and is the proven working pattern.

--notes output now recommends:

```xml

<style name="Theme.App.Splash" parent="@style/Theme.Titanium.Light.NoTitle"> #YOUR_BG @mipmap/ic_launcher </style>

```

```xml

\`\`\`

Changed — --ios-padding default: 8% → 4%

Apple's HIG + measurements of production apps (La Baraja uses 1.6-2.7% per side, Mail/Safari/WhatsApp 3-6%) show iOS icons typically fill 92-97% of canvas. Old default at 84% fill was too conservative. New 4% default = 92% fill, matching Apple's own apps.

Override: --ios-padding 2 (aggressive La Baraja style), --ios-padding 8 (previous default). Android --padding stays at 20%.

v2.0.0 — Modern Titanium SDK 13.x branding pipeline

New preset -p ti-branding generates a complete modern Titanium branding asset set from a single master in one command. Works on both Alloy and Classic project layouts.

What's new

• New preset: -p ti-branding — modern pipeline; auto-detects Alloy (app/) vs Classic (Resources/) layouts
• Backward-compat alias: -p alloy --modern — deprecated, will be removed in v3.0.0
• Output set: DefaultIcon.png (alpha) + DefaultIcon-ios.png (flat), Android adaptive triplet × 5, legacy ic_launcher.png × 5, ic_launcher.xml binder, marketplace artwork, optional notification + splash icons

New flags

Flag	Default	Purpose
--modern, --adaptive, --marketplace, --notification, --splash	off	Select outputs (kitchen-sink with just -p ti-branding)
--bg-color <hex>	#FFFFFF	Also auto-flattens marketplace artwork when explicitly provided
--padding <pct>	20	Android safe-zone per side (Material spec floor: 19.44%)
--ios-padding <pct>	8	iOS / marketplace aesthetic padding
--cleanup-legacy	off	Context-aware cleanup driven by tiapp.xml
--aggressive	off	Cleanup also removes ldpi density folders
--in-place	off	Overwrite project directly, skip .ti-branding/ staging
--notes	off	Print full tiapp.xml snippets (default: compact summary)
--monochrome-master <path>	—	Dedicated silhouette master for Android 13+ themed icons and notification
--project, --output, --dry-run	—	Standard project/output/preview controls

Backward compatibility

-p alloy without modern flags keeps v1.x multi-scale pipeline unchanged. Not deprecated — different feature with no modern replacement.

Dependency

fast-xml-parser (~18KB, no native bindings) added for tiapp.xml parsing. Regex fallback if unavailable.

Tests

36 new tests (generators, tiapp-reader, cleanup-legacy buckets, CLI integration) + 60 existing passing.

Full changelog: CHANGELOG.md

v1.7.8

What's new

• Running imgconvert without arguments now shows the help message

Fixes

• Alloy preset output directory was relative to the current working directory, causing files to end up in unexpected locations. Now it follows this precedence:
  1. -o flag (explicit output directory)
  2. Titanium project root (auto-detected via tiapp.xml in CWD)
  3. Input file's directory (fallback)
• Alloy preset now respects the -o flag for custom output

Docs

• README, CHANGELOG, and CUSTOM_PRESETS humanized (removed AI writing patterns, sentence case headings)
• Alloy output directory precedence documented with examples