@maccesar/titools 2.5.0 → 2.6.0

package/skills/ti-branding/references/ios-appiconset.md

@@ -0,0 +1,62 @@
+# iOS appiconset (Xcode 14+)
+
+## One master, all sizes
+
+Since Xcode 14 (2022), Apple no longer requires the full matrix of 20+ icon sizes. A single 1024×1024 source is sufficient — Xcode generates the rest at build time.
+
+Titanium SDK 13.x embraces this:
+
+- Place `DefaultIcon-ios.png` (1024×1024, no alpha) at the project root
+- On `ti build`, Titanium writes the generated appiconset to `build/iphone/Assets.xcassets/AppIcon.appiconset/`
+- `build/` is regenerated on every build — you never commit the full set to the source tree
+
+If you manually place `app/assets/iphone/appicon-*.png` files, Titanium respects them and only fills in the missing sizes. This skill ignores that path — it only writes the single `DefaultIcon-ios.png` master.
+
+## Why no alpha channel
+
+Apple's review pipeline rejects icons with transparency:
+
+> Apps with app icons that include transparency will be rejected during app review.
+
+The skill flattens alpha by compositing the master over the `--bg-color` before writing `DefaultIcon-ios.png`. Same for `iTunesConnect.png` (App Store submission).
+
+## Relevant file paths
+
+At the project root:
+
+| File | Size | Purpose |
+|------|------|---------|
+| `DefaultIcon-ios.png` | 1024×1024 | Master for appiconset generation |
+| `DefaultIcon.png` | 1024×1024 | Fallback if `DefaultIcon-ios.png` missing (Android uses this too) |
+| `iTunesConnect.png` | 1024×1024 | Uploaded to App Store Connect |
+
+The skill generates the first and third; the second can be a copy of the first if the user wants a shared master.
+
+## Dark and tinted variants (iOS 18+)
+
+iOS 18 added dark-mode and tinted versions of app icons, configured via:
+
+- `DefaultIcon-Dark.png` — dark theme variant
+- `DefaultIcon-Tinted.png` — tinted grayscale variant for iOS's theme engine
+
+These are **out of scope** for this skill's v1. Users who want them can drop the files into the project root manually; Titanium SDK 13.1+ picks them up automatically.
+
+## Launch images — deliberately not generated
+
+The 30+ `Default-*@3x.png` launch image variants from Titanium documentation are legacy. Modern Titanium uses `LaunchScreen.storyboard`, configured in `tiapp.xml`:
+
+```xml
+<ios>
+  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+  <default-background-color>#0B1326</default-background-color>
+</ios>
+```
+
+The storyboard adapts to any device resolution dynamically. Legacy PNG launch images were needed before iOS 14 — they are now dead weight in any app submitted to the App Store (Apple mandates storyboard-based launch as of 2020).
+
+If a user genuinely needs legacy launch images (maintaining a pre-2020 app), that's a separate tool job — this skill explicitly does not generate them.
+
+## References
+
+- Apple HIG: [App icons](https://developer.apple.com/design/human-interface-guidelines/app-icons)
+- Apple: [Configuring your project to use asset catalogs](https://developer.apple.com/documentation/xcode/configuring-your-project-to-use-asset-catalogs)

package/skills/ti-branding/references/master-input-guidelines.md

@@ -0,0 +1,84 @@
+# Master input guidelines
+
+## Preferred: SVG
+
+SVG is the best source because:
+
+- Vector: re-renders cleanly at any density, no upscaling artifacts
+- Preserves transparency natively
+- Small file size (~5–50 KB for typical logos vs 100+ KB for 1024² PNG)
+- Easy to edit by designers in Illustrator / Affinity / Figma / Inkscape
+
+**SVG requirements**:
+
+- Square viewBox (or content that's square within a rectangular viewBox)
+- Paths only — avoid `<script>`, `<foreignObject>`, web fonts
+- Solid fills or simple gradients — very complex gradients may rasterize inconsistently across densities
+- No external references (embedded images, fonts loaded by URL)
+
+The skill uses `rsvg-convert` to rasterize to 1024×1024 PNG before any further processing.
+
+## Acceptable: PNG ≥ 1024×1024 with transparency
+
+A PNG master works when SVG isn't available:
+
+- Minimum size: 1024×1024 (smaller input produces visibly soft xxxhdpi icons)
+- Square preferred — non-square inputs get center-cropped with a warning
+- Transparent background for best monochrome layer results
+
+## Accepted with warning: PNG with solid background
+
+PNGs that already have a non-transparent background still work, but:
+
+- The monochrome layer will be a solid square silhouette (every pixel is non-transparent, so "everything" becomes white)
+- You cannot change the adaptive background color — it's baked in
+- Recommend re-exporting from the source with transparency if possible
+
+## Padding and the "pegado" problem
+
+If the icon's content already fills the full canvas (logo touching the edges), every generated asset will show the same cramped look. The skill cannot add space that isn't there.
+
+Two ways to fix:
+
+1. **Prepare the master with transparent padding** — export the logo so there's ~15% empty space around it in the source
+2. **Increase the `--padding` flag** — the skill re-centers the logo inside the target canvas. Higher padding pushes the logo inward
+
+Recommended padding values:
+
+| Padding | Logo fill | When to use |
+|---------|-----------|-------------|
+| 19 (spec floor) | 62% | Intricate logos needing maximum detail; risky with aggressive launcher masks |
+| 22 (default) | 56% | Balanced, compliant with Android safe-zone spec + 3% buffer |
+| 25 | 50% | Logos with fine strokes or details near the edge |
+| 28–32 | 44–36% | Bold simple shapes, single-letter monograms |
+
+If the user sees the logo pegado after running the skill once, re-run with a higher `--padding`.
+
+## Alpha channel handling
+
+PNG inputs commonly have one of three alpha configurations:
+
+- **Straight alpha** (most common): `rgba(r, g, b, a)` — R/G/B hold true color, A holds coverage
+- **Premultiplied alpha**: `rgba(r × a, g × a, b × a, a)` — R/G/B are scaled by A
+- **No alpha channel**: opaque only
+
+ImageMagick handles straight alpha transparently. Premultiplied inputs may show dark halos at the edges when composited — if this happens, re-export from the source app with straight alpha.
+
+## Checking the master before running
+
+Quick sanity check:
+
+```bash
+# Dimensions and alpha info
+magick identify -format "%wx%h  alpha=%A\n" /path/to/logo.png
+
+# Visualize the alpha channel (useful for debugging halos)
+magick /path/to/logo.png -alpha extract /tmp/alpha.png && open /tmp/alpha.png
+```
+
+For SVG:
+
+```bash
+# Preview at output size
+rsvg-convert -w 1024 -h 1024 /path/to/logo.svg -o /tmp/preview.png && open /tmp/preview.png
+```

package/skills/ti-branding/references/notification-icons.md

@@ -0,0 +1,63 @@
+# Notification icons
+
+## The white-only rule
+
+Android notification icons, since API 21 (Lollipop), must be **white pixels on a transparent background**. The system applies a runtime tint based on the notification's `color` property — color in the source image is discarded.
+
+If the icon is not white+alpha, it renders as a blank white square on API 21+ (a common bug symptom when developers reuse their launcher icon as the notification icon).
+
+## Generation
+
+The skill's `gen-notification.sh`:
+
+1. Scales the foreground logo down to the notification size
+2. Runs ImageMagick's `-channel RGB -fill white -colorize 100 +channel` to force all RGB channels to 255 while preserving alpha
+3. Pads transparently to match the target canvas size
+
+## Sizes
+
+| Density  | Size |
+|----------|------|
+| mdpi     | 24   |
+| hdpi     | 36   |
+| xhdpi    | 48   |
+| xxhdpi   | 72   |
+| xxxhdpi  | 96   |
+
+## File naming
+
+Titanium has no hard convention, but the de-facto name is `ic_stat_notify.png`. The skill emits this name. To reference it:
+
+**In JavaScript (local notification)**:
+
+```js
+Ti.Android.NotificationManager.notify(1, Ti.Android.createNotification({
+  contentTitle: 'Hello',
+  contentText: 'Hi there',
+  icon: Ti.App.Android.R.drawable.ic_stat_notify  // white+alpha
+}))
+```
+
+**In `platform/android/AndroidManifest.xml` (Firebase default)**:
+
+```xml
+<meta-data
+  android:name="com.google.firebase.messaging.default_notification_icon"
+  android:resource="@drawable/ic_stat_notify"/>
+<meta-data
+  android:name="com.google.firebase.messaging.default_notification_color"
+  android:resource="@color/notification_tint"/>
+```
+
+With a matching `values/colors.xml`:
+
+```xml
+<color name="notification_tint">#FDD900</color>
+```
+
+The `default_notification_color` is the tint the runtime applies to the white pixels.
+
+## References
+
+- Android: [Notifications overview](https://developer.android.com/develop/ui/views/notifications)
+- Firebase: [Setting the default notification icon](https://firebase.google.com/docs/cloud-messaging/android/client#manifest)

package/skills/ti-branding/references/splash-screen-api.md

@@ -0,0 +1,81 @@
+# Splash screens (modern)
+
+## Two strategies by platform
+
+### iOS — storyboard-driven (iOS 14+)
+
+Modern iOS uses `LaunchScreen.storyboard`. Titanium enables this via `tiapp.xml`:
+
+```xml
+<ios>
+  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+  <default-background-color>#0B1326</default-background-color>
+</ios>
+```
+
+The storyboard is a single layout that scales dynamically to any device. No per-device PNG launch images are needed. The `<default-background-color>` sets both the storyboard background AND the gap-color between the storyboard and the first view.
+
+This skill does NOT generate iOS launch images. It prints the `<default-background-color>` snippet for the user to paste.
+
+### Android 12+ — SplashScreen API (API 31+)
+
+Android 12 introduced a system-managed splash that replaces the old "put a PNG in drawable/background.png" approach. It's theme-driven:
+
+```xml
+<!-- platform/android/res/values-v31/splash_theme.xml -->
+<resources>
+  <style name="Theme.SnapGym.SplashScreen" parent="Theme.SplashScreen">
+    <item name="windowSplashScreenBackground">#0B1326</item>
+    <item name="windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>
+    <item name="postSplashScreenTheme">@style/Theme.AppDerived</item>
+  </style>
+</resources>
+```
+
+With a matching `AndroidManifest.xml` entry (inside `<application>`):
+
+```xml
+<meta-data android:name="io.tidev.titanium.splash.theme"
+           android:value="@style/Theme.SnapGym.SplashScreen"/>
+```
+
+Critical: **do NOT apply this theme to `<application android:theme>` or to a specific `<activity>`** — it only affects the system SplashScreen via the manifest meta-data. Applying it to the application breaks the ActionBar / TitleBar in every subsequent screen (as SNAP Gym learned the hard way).
+
+### Android <12 — fallback to launcher icon
+
+On API <31, the system uses the launcher icon as the splash. No extra file needed. The `background.9.png` 9-patch pattern is obsolete in Titanium SDK 13+.
+
+## splash_icon.png canvas (Android 12+)
+
+The SplashScreen API spec:
+
+- Total canvas: **288 dp**
+- Icon safe-zone: **192 dp centered** (≈ 67% of canvas)
+- OS applies a circular mask automatically — keep content centered
+
+Density sizes:
+
+| Density  | Total canvas | Icon area |
+|----------|--------------|-----------|
+| mdpi     | 288          | 192       |
+| hdpi     | 432          | 288       |
+| xhdpi    | 576          | 384       |
+| xxhdpi   | 864          | 576       |
+| xxxhdpi  | 1152         | 768       |
+
+The skill's `gen-splash-icon.sh` places the logo at `192/288 ≈ 67%` of the canvas with transparent padding around it.
+
+## Why we don't generate `background.9.png`
+
+The old 9-patch splash pattern works like this:
+
+- PNG with 1px borders marked as stretchable regions
+- Titanium references it as `background.9.png` in `drawable-*dpi/`
+- SDK pre-13 used it as `windowBackground` for the root activity
+
+Titanium 13+ handles splash via the modern SplashScreen API on 12+ and via the launcher icon itself on older versions. `background.9.png` produces worse results on 12+ (competing with the SplashScreen API) and offers no benefit on older versions that the launcher fallback can't provide.
+
+## References
+
+- Android: [Splash screens](https://developer.android.com/develop/ui/views/launch/splash-screen)
+- Apple: [Configuring your app's launch screen](https://developer.apple.com/documentation/xcode/configuring-your-apps-launch-screen)

package/skills/ti-branding/references/ti-icon-paths.md

@@ -0,0 +1,84 @@
+# Canonical paths — Titanium SDK 13.x
+
+## Alloy layout (primary)
+
+```
+project-root/
+├── DefaultIcon-ios.png              # iOS master (1024² no alpha)
+├── DefaultIcon.png                  # Generic master (1024² no alpha) — fallback
+├── iTunesConnect.png                # 1024² App Store submission
+├── MarketplaceArtwork.png           # 512² Google Play submission
+├── tiapp.xml
+└── app/
+    ├── assets/
+    │   ├── iphone/                  # (optional) manual iOS appiconset — skill doesn't write here
+    │   └── android/
+    │       ├── appicon.png          # 128² legacy fallback (pre-adaptive)
+    │       └── images/              # density-scaled in-app image assets (NOT launcher)
+    └── platform/
+        └── android/
+            └── res/
+                ├── mipmap-mdpi/
+                │   ├── ic_launcher.png              # legacy 48²
+                │   ├── ic_launcher_foreground.png   # adaptive 108²
+                │   ├── ic_launcher_background.png   # adaptive 108²
+                │   └── ic_launcher_monochrome.png   # themed 108²
+                ├── mipmap-hdpi/    # 72 / 162 / 162 / 162
+                ├── mipmap-xhdpi/   # 96 / 216 / 216 / 216
+                ├── mipmap-xxhdpi/  # 144 / 324 / 324 / 324
+                ├── mipmap-xxxhdpi/ # 192 / 432 / 432 / 432
+                ├── mipmap-anydpi-v26/
+                │   └── ic_launcher.xml              # binds the 3 adaptive layers
+                ├── drawable-mdpi/
+                │   ├── ic_stat_notify.png           # (optional) 24² white+alpha
+                │   └── splash_icon.png              # (optional) 288² Android 12+ splash
+                ├── drawable-hdpi/  # 36 / 432
+                ├── drawable-xhdpi/ # 48 / 576
+                ├── drawable-xxhdpi/ # 72 / 864
+                └── drawable-xxxhdpi/ # 96 / 1152
+```
+
+## Classic layout
+
+Same structure, different roots. The skill detects `Resources/` and remaps:
+
+| Alloy path | Classic path |
+|---|---|
+| `app/assets/android/appicon.png` | `Resources/android/appicon.png` |
+| `app/platform/android/res/...` | `platform/android/res/...` |
+
+Root-level files (`DefaultIcon*.png`, `iTunesConnect.png`, `MarketplaceArtwork.png`) are identical in both layouts.
+
+## What Titanium does at build time
+
+- **iOS**: reads the root master → writes to `build/iphone/Assets.xcassets/AppIcon.appiconset/` (build directory, regenerated every build, never commited)
+- **Android**: copies `app/platform/android/res/*` verbatim to `build/android/app/src/main/res/`, plus copies `app/assets/android/appicon.png` to `build/.../res/drawable-*dpi/appicon.png` if the legacy path is used
+
+Result: anything the skill writes to `app/platform/android/res/` or `app/assets/` survives builds. Nothing the skill generates can be accidentally overwritten by `ti build`.
+
+## What the skill writes
+
+After confirming with the user, the skill copies from its staging directory to:
+
+| Target | Files |
+|---|---|
+| Project root | `DefaultIcon-ios.png`, `iTunesConnect.png`, `MarketplaceArtwork.png` |
+| `app/platform/android/res/mipmap-*/` | Launcher icons (adaptive triplet + legacy flat), 5 densities |
+| `app/platform/android/res/mipmap-anydpi-v26/` | `ic_launcher.xml` |
+| `app/platform/android/res/drawable-*/` (optional) | `ic_stat_notify.png`, `splash_icon.png` |
+
+The skill never touches `tiapp.xml`, `config.json`, source code, or anything outside the asset/resource paths above.
+
+## Required `tiapp.xml` entry
+
+For the adaptive icon to be picked up, `tiapp.xml` must reference it:
+
+```xml
+<android>
+  <manifest>
+    <application android:icon="@mipmap/ic_launcher"/>
+  </manifest>
+</android>
+```
+
+The skill checks for this and, if missing, prints the snippet — does not edit the file. See `tiapp-xml-snippets.md` for the full set.

package/skills/ti-branding/references/tiapp-xml-snippets.md

@@ -0,0 +1,92 @@
+# tiapp.xml snippets
+
+The skill prints these blocks after generating assets. The user reviews and pastes them manually — `tiapp.xml` often contains sensitive info (API keys, signing identities, staging URLs) and automated editing would be fragile.
+
+## Block 1 — iOS background color (for storyboard splash)
+
+Under the `<ios>` element:
+
+```xml
+<ios>
+  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+  <default-background-color>#0B1326</default-background-color>
+</ios>
+```
+
+Replace `#0B1326` with the user's `--bg-color`.
+
+## Block 2 — Android application icon reference
+
+Under `<android><manifest><application>`:
+
+```xml
+<android>
+  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application android:icon="@mipmap/ic_launcher"
+                 android:usesCleartextTraffic="false"/>
+  </manifest>
+</android>
+```
+
+The `android:icon="@mipmap/ic_launcher"` tells Android to use the adaptive icon XML (via `mipmap-anydpi-v26/ic_launcher.xml` on API 26+) with automatic fallback to the flat `mipmap-*dpi/ic_launcher.png` on older devices.
+
+## Block 3 — Android 12+ splash screen (optional, requires `--with-splash-icon`)
+
+Requires three changes:
+
+### 3a. Splash theme resource
+
+Create `app/platform/android/res/values-v31/splash_theme.xml`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <style name="Theme.App.SplashScreen" parent="Theme.SplashScreen">
+    <item name="windowSplashScreenBackground">#0B1326</item>
+    <item name="windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>
+    <item name="postSplashScreenTheme">@style/Theme.AppDerived</item>
+  </style>
+</resources>
+```
+
+### 3b. Manifest meta-data (NOT a theme on `<application>` or `<activity>`)
+
+Under `<android><manifest><application>`:
+
+```xml
+<meta-data android:name="io.tidev.titanium.splash.theme"
+           android:value="@style/Theme.App.SplashScreen"/>
+```
+
+### 3c. DO NOT do this
+
+Setting `android:theme="@style/Theme.App.SplashScreen"` on `<application>` or `<activity>` will strip the ActionBar / TitleBar from every screen in the app because Titanium's `Theme.AppDerived` inherits from the application theme. The SplashScreen API is designed to work through the manifest meta-data entry above, not through activity theming.
+
+## Block 4 — Firebase Cloud Messaging notification icon (optional, requires `--with-notification`)
+
+Create `app/platform/android/res/values/colors.xml` (if it doesn't exist) with:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <color name="notification_tint">#FDD900</color>
+</resources>
+```
+
+Then under `<android><manifest><application>`:
+
+```xml
+<meta-data android:name="com.google.firebase.messaging.default_notification_icon"
+           android:resource="@drawable/ic_stat_notify"/>
+<meta-data android:name="com.google.firebase.messaging.default_notification_color"
+           android:resource="@color/notification_tint"/>
+```
+
+## What the skill reports
+
+After generation, the skill prints only the blocks relevant to the flags used and the project's current state:
+
+- Always prints Block 2 if `android:icon="@mipmap/ic_launcher"` is missing from tiapp.xml
+- Always prints Block 1 if `<default-background-color>` is missing
+- Prints Block 3 only if `--with-splash-icon` was used
+- Prints Block 4 only if `--with-notification` was used