@maccesar/titools 4.22.0 → 4.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.22.0",
+  "version": "4.23.0",
   "description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
   "main": "lib/index.js",
   "type": "module",

package/skills/purgetss/SKILL.md

@@ -468,7 +468,7 @@ Load these only when needed:
 - [PurgeTSS UI in Classic](references/purgetss-ui-classic.md) - Native JavaScript setup, public exports, animation objects, cleanup, and platform notes
 
 ### Release Notes
-- [Version History](references/version-history.md) - Release-by-release feature additions and behavior changes (v7.4.0 → v7.17.0)
+- [Version History](references/version-history.md) - Release-by-release feature additions and behavior changes (v7.4.0 → v7.17.1)
 
 > **💡 TEXT FONTS (Google Fonts, Roboto, etc.)**
 > For text fonts, see [Custom Fonts](references/custom-fonts.md).

package/skills/purgetss/references/app-branding.md

@@ -25,6 +25,7 @@ For the terse flag reference, see the [`brand` command reference](./cli-commands
 - [Android dark mode](#android-dark-mode)
 - [Android 12+ splash artwork](#android-12-splash-artwork)
 - [Android pre-12 splash](#android-pre-12-splash)
+- [FCM notification icon](#fcm-notification-icon)
 - [The iOS launch screen and LaunchLogo.png](#the-ios-launch-screen-and-launchlogopng)
 - [iPhone launch images](#iphone-launch-images)
 - [iOS 18+ Dark and Tinted variants](#ios-18-dark-and-tinted-variants)
@@ -164,9 +165,10 @@ brand: {
   appicon:          { padding: '10%' },   // appicon.png (128×128)
   androidSplash:    { padding: '26%' },   // assets/android/default.png + images/res-*/default.png × 11
 
-  // Opt-in: inert until you edit the Android theme / FCM meta-data by hand.
+  // Opt-in: splash_icon stays inert until the Android theme points at it.
+  // notificationicon is read by firebase.cloudmessaging, by that exact name.
   splashIcon:       { enabled: false },   // drawable-*/splash_icon.png × 5
-  notificationIcon: { enabled: false },   // drawable-*/ic_stat_notify.png × 5
+  notificationIcon: { enabled: false },   // drawable-*/notificationicon.png × 5
   ninePatch:        { enabled: false }    // background.9.png (not implemented yet)
 }
 ```
@@ -258,12 +260,12 @@ And these live at the top level:
 | `appicon` | `appicon` | `appicon.png` (128×128) | `10%` | yes |
 | `android-splash` | `androidSplash` | `assets/android/default.png` + `images/res-*/default.png` × 11 | `26%` | yes |
 | `splash-icon` | `splashIcon` | `drawable-*/splash_icon.png` × 5 | — | `--splash-icon` |
-| `notification-icon` | `notificationIcon` | `drawable-*/ic_stat_notify.png` × 5 | — | `--notification-icon` |
+| `notification-icon` | `notificationIcon` | `drawable-*/notificationicon.png` × 5 | — | `--notification-icon` |
 | `nine-patch` | `ninePatch` | `background.9.png` | — | `--nine-patch` (not implemented yet) |
 
 `ic_launcher.xml` always travels inside `adaptive`; it is never generated on its own.
 
-Only three pieces are opt-in, and for one reason: they produce nothing useful until you edit XML by hand. `splash_icon.png` is inert without `windowSplashScreenAnimatedIcon` in the theme, and `ic_stat_notify.png` is inert without the FCM `meta-data` entry.
+Three pieces are opt-in, because none of them does anything on its own. `splash_icon.png` is inert until the theme points `windowSplashScreenAnimatedIcon` at it. `notificationicon.png` needs `firebase.cloudmessaging` in the project, plus a `meta-data` entry for the notification messages that do not reach it by name — see [FCM notification icon](#fcm-notification-icon). `background.9.png` is not implemented yet.
 
 ### `background` is inherited, `padding` is not
 
@@ -497,6 +499,34 @@ Earlier versions regenerated only the first file and hid the other 11 behind a `
 > A solid `windowBackground` wins
 > If the launch theme sets `android:windowBackground` to a plain color — which is what [Matching the launch background](#matching-the-launch-background) recommends — that color takes precedence over this artwork on Android <12. Drop the `windowBackground` item if you want the image to show instead.
 
+## FCM notification icon
+
+`notification-icon` is off by default. Turn it on with `brand.notificationIcon.enabled`, or for a single run with `--notification-icon`. It writes five densities to `app/platform/android/res/drawable-*/notificationicon.png` (`platform/android/res/drawable-*/notificationicon.png` in Classic), white on transparent, because **Android tints status-bar icons at runtime**: every non-transparent pixel comes out white and the color in the artwork is discarded.
+
+The filename is fixed, like `appicon.png` and `DefaultIcon.png`, because the consumer dictates it. `firebase.cloudmessaging` resolves the drawable by name inside `TiFirebaseMessagingService.showNotification()`, through `getResource("notificationicon")`, and that lookup is the only path a **data** message has. When the drawable is missing the module falls back to `appicon` — the opaque launcher icon, which the status bar renders as a white blob, since only the alpha channel survives the tint.
+
+**Notification** messages take the configurable path instead. Two `meta-data` entries go under `<application>` in `tiapp.xml`:
+
+```xml
+<meta-data android:name="com.google.firebase.messaging.default_notification_icon"
+           android:resource="@drawable/notificationicon"/>
+<meta-data android:name="com.google.firebase.messaging.default_notification_color"
+           android:resource="@color/notification_tint"/>
+```
+
+The second one colors the notification's accent, not the icon. Create or merge `app/platform/android/res/values/colors.xml` (`platform/android/res/values/colors.xml` in Classic):
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <color name="notification_tint">#0B1326</color>
+</resources>
+```
+
+> **Renamed in v7.17.1**
+>
+> The piece used to write `ic_stat_notify.png`, the Android convention for status-bar drawables but not the name the module looks up. Under the old name a data message never found the icon, whatever the `meta-data` said. A project that wired `@drawable/ic_stat_notify` by hand changes that one line and deletes the five stale files.
+
 ## The iOS launch screen and LaunchLogo.png
 
 Titanium builds `LaunchLogo.imageset` itself on every iOS build, resizing one source into the five sizes it needs. It looks for `LaunchLogo.png` first and falls back to `DefaultIcon.png`.
@@ -744,6 +774,10 @@ cp docs/my-logo-mono.svg purgetss/brand/logo-mono.svg
 purgetss brand
 ```
 
+### The notification shows a white square, or the app icon instead of my notification icon
+
+`firebase.cloudmessaging` did not find the drawable and fell back to `appicon`, which the status bar tints into a solid blob. Three causes, in order of likelihood: the piece was never generated (`brand.notificationIcon.enabled` is `false` by default — run `purgetss brand --only notification-icon`), the project still carries `ic_stat_notify.png` from before v7.17.1, or the `meta-data` entry points at the old name. See [FCM notification icon](#fcm-notification-icon).
+
 ### iOS rejects the app icon upload ("contains transparency")
 
 Apple requires App Store icons to have no alpha channel. `DefaultIcon-ios.png` is always flattened on `brand.background` for that reason. If you edited the file manually and reintroduced alpha, re-run `purgetss brand`.

package/skills/purgetss/references/cli-commands.md

@@ -82,7 +82,8 @@ module.exports = {
     adaptive: { padding: '18%' }, legacyIcon: { padding: '10%' },
     appicon: { padding: '10%' }, androidSplash: { padding: '26%' },
 
-    // Opt-in: inert until you edit the Android theme / FCM meta-data by hand.
+    // Opt-in: splash_icon stays inert until the Android theme points at it.
+    // notificationicon is read by firebase.cloudmessaging, by that exact name.
     splashIcon: { enabled: false }, notificationIcon: { enabled: false },
     ninePatch: { enabled: false }
   },
@@ -236,7 +237,7 @@ Radius precedence and the outputs intentionally left unmasked are documented in
 
 | Flag | Purpose |
 | --- | --- |
-| `--notification-icon` | Also emit `ic_stat_notify.png × 5`. |
+| `--notification-icon` | Also emit `notificationicon.png × 5`. |
 | `--splash-icon` | Also emit `splash_icon.png × 5`. |
 | `--nine-patch` | Declared but not implemented yet; prints a warning and writes nothing. |
 **Logo variants & overrides**

package/skills/purgetss/references/customization-deep-dive.md

@@ -70,9 +70,10 @@ module.exports = {
     appicon:          { padding: '10%' },   // appicon.png (128×128)
     androidSplash:    { padding: '26%' },   // assets/android/default.png + images/res-*/default.png × 11
 
-    // Opt-in: inert until you edit the Android theme / FCM meta-data by hand.
+    // Opt-in: splash_icon stays inert until the Android theme points at it.
+    // notificationicon is read by firebase.cloudmessaging, by that exact name.
     splashIcon:       { enabled: false },   // drawable-*/splash_icon.png × 5
-    notificationIcon: { enabled: false },   // drawable-*/ic_stat_notify.png × 5
+    notificationIcon: { enabled: false },   // drawable-*/notificationicon.png × 5
     ninePatch:        { enabled: false }    // background.9.png (not implemented yet)
   },
   // Sources in purgetss/images/ are 4x masters: a 1024px file yields

package/skills/purgetss/references/version-history.md

@@ -8,6 +8,10 @@ When in doubt about whether a class, flag, or config key exists in the user's in
 
 ---
 
+## v7.17.1
+- **The `notification-icon` piece writes `notificationicon.png`, not `ic_stat_notify.png`.** `firebase.cloudmessaging` hardcodes that name — `TiFirebaseMessagingService.showNotification()` calls `getResource("notificationicon")` — and it is the only path a **data** message has. The `default_notification_icon` meta-data is the configurable one and covers **notification** messages alone, so under the old name no manifest entry could rescue a data message: the module fell back to the opaque `appicon`, which the status bar renders as a white blob. The filename is fixed rather than a config key, for the same reason `appicon.png` and `DefaultIcon.png` are. Projects that wired `@drawable/ic_stat_notify` by hand need to update that one meta-data line and delete the five stale files. See [app-branding.md](app-branding.md).
+- The comment above the opt-in pieces in the generated config now names each consumer instead of claiming both are inert without hand-edited XML. Only `splash_icon` is.
+
 ## v7.17.0
 - The `images:` section rejects unknown keys instead of ignoring them, at both levels: the five top-level keys (`quality`, `format`, `autoSync`, `confirmOverwrites`, `files`) and the three inside each `files[]` entry (`filename`, `width`, `height`, with `filename` required). Nothing is generated when validation fails. Never suggest `width`, `opacity`, `padding` or `output` as config keys — they are CLI flags and now abort the run. See [multi-density-images.md](multi-density-images.md).
 - The generated `images:` block gained four comment lines explaining the 4× master convention, and the `quality` comment now names the formats it reaches: `webp`, `jpeg`, `avif`, `tiff`. PNG uses `compressionLevel: 9` and GIF takes no quality parameter, so neither is affected. Both copies changed — the one patched into an existing config and the one `init` seeds.

package/skills/ti-expert/references/push-notifications.md

@@ -11,7 +11,6 @@ This file is about the community module [`firebase.cloudmessaging`](https://gith
 <!-- TOC-START -->
 ## Contents
 
-- [Contents](#contents)
 - [1. The four doors](#1-the-four-doors)
 - [2. The payload decides how much of the module runs](#2-the-payload-decides-how-much-of-the-module-runs)
 - [3. A tap does not fire `didReceiveMessage`](#3-a-tap-does-not-fire-didreceivemessage)
@@ -34,7 +33,7 @@ This file is about the community module [`firebase.cloudmessaging`](https://gith
 | Backgrounded, person taps the notification | `Ti.App` `resumed`, then read the Intent | nothing |
 | **Already in front**, person taps a notification sitting in the tray | `newintent` on the root activity | `launchMode="singleTop"` |
 
-A module that fires `didOpenNotification` replaces rows two to four with one listener. See [If your module fires `didOpenNotification`](#if-your-module-fires-didopennotification).
+A module that fires `didOpenNotification` replaces rows three and four with one listener. Row two still arrives in the Intent, because the module does not exist yet when the notification is opened. See [If your module fires `didOpenNotification`](#if-your-module-fires-didopennotification).
 
 Verified case by case on a physical Android phone, reading a log line that named which door each message came through rather than watching the screen.
 
@@ -93,6 +92,12 @@ That last symptom is worth naming because it sends people down the wrong road. I
 
 Firebase's own server documentation teaches the `notification` block, which is why this is such a common shape to arrive at.
 
+### The icon, whichever route posts it
+
+Both routes need a drawable named `notificationicon`, because the module resolves it by that exact name: `TiFirebaseMessagingService.showNotification()` calls `getResource("notificationicon")`, and that lookup is the only path a data message has. When it is missing the module falls back to `appicon` — the opaque launcher icon, which the status bar tints into a white square, since only the alpha channel survives. A notification message takes the configurable path instead, the `com.google.firebase.messaging.default_notification_icon` meta-data, which is why the same project can show a correct icon on one route and a blob on the other.
+
+PurgeTSS generates the five densities, white on transparent and under the right name, with `purgetss brand --only notification-icon` — off by default. Its `app-branding.md` § "FCM notification icon" carries both meta-data entries and the `colors.xml` resource that `default_notification_color` needs.
+
 ## 3. A tap does not fire `didReceiveMessage`
 
 When the module posts the notification and the person taps it, `PushHandlerActivity` puts the payload on the launcher Intent as the `fcm_data` extra and starts the activity. It does not fire `didReceiveMessage`.
@@ -134,7 +139,16 @@ Take the activity name from the built manifest rather than guessing it: `build/a
 
 ### If your module fires `didOpenNotification`
 
-Everything above is what the published module needs. A module that fires `didOpenNotification` from `setNotificationData()` makes all of it unnecessary: no `singleTop`, no `newintent`, no reading the Intent on resume. One listener covers every tap, whatever the app was doing.
+Everything above is what the published module needs. A module that fires `didOpenNotification` from `setNotificationData()` drops the `singleTop`, the `newintent` listener and the Intent read on resume. Two routes remain instead of four, and they are exclusive:
+
+| What the app was doing | Where the payload arrives |
+| --- | --- |
+| Open, in front, message arrives | `didReceiveMessage` |
+| Backgrounded, person taps | `didOpenNotification` |
+| Already in front, person taps a notification in the tray | `didOpenNotification` |
+| Killed, person taps | `fcm_data` extra on the launch Intent |
+
+Verified on a physical Android 15 phone and an API 35 emulator, each row confirmed by a log line naming the route. The first three ran back to back on one process id with a game in progress, which survived; only the fourth starts a new process.
 
 ```javascript
 modulo.addEventListener('didOpenNotification', (e) => {
@@ -148,6 +162,8 @@ The Intent is still how a cold start arrives, so keep that path. Check `timodule
 
 Do not run both. Where the module also puts the payload on the Intent, `resumed` finds it again on Titanium's second pass and the panel opens twice. That is a real symptom, not a hypothetical: it shows up on Android 10 and not on Android 15, because the two versions differ in whether the launcher Intent gets delivered to a task that already exists.
 
+To test the fourth row, swipe the app out of Recents. `adb shell am kill` looks like the same thing and is not: it kills the process but Android keeps the activity's saved state, and on restore Titanium puts `tiLaunchIntentExtras` from the previous launch back over the new Intent, taking `fcm_data` with it. The `TiRootActivity` checkpoint tells you which one you got — `savedInstanceState: null` is a real cold start, anything else is a restore. `adb shell am force-stop` is worse: it leaves the app in the stopped state, where Android stops delivering FCM messages until someone launches it by hand.
+
 ## 5. Why two splash screens flash by
 
 Tap a notification and you may see one or two blank pages slide past before the app appears, and the splash icon never finishes animating. Opening the same app from the launcher icon looks fine.
@@ -297,6 +313,7 @@ Do not test with the app added to the battery whitelist. That measures a phone y
 | --- | --- | --- |
 | Tapping restarts the app from zero and loses state | Top-level `notification` block; the system owns the intent | Section 2 |
 | `image`, `big_text`, `channelId`, `sound`, `vibrate` ignored | Same | Section 2 |
+| A white square or the launcher icon in the status bar | No `notificationicon` drawable; the module fell back to `appicon` | Section 2 |
 | Foreground and cold start work, backgrounded tap does nothing | Nobody reads the Intent on resume | Section 3 |
 | Nothing at all happens when tapping a stored notification while using the app | No `resumed`, no `newintent` listener, or no `singleTop` | Section 4 |
 | Blank pages slide past before the app appears | `PushHandlerActivity` has no theme; Titanium spawns a duplicate root activity | Section 5 |