@maccesar/titools 4.22.0 → 4.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.22.0",
+  "version": "4.23.1",
   "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.
 
@@ -80,6 +79,26 @@ if (OS_ANDROID) {
 
 **Wrap the listeners.** `Ti.App.addEventListener('resumed', mostrarAviso)` passes the event object as the first argument, and if the function's first parameter is an Intent, the code blows up inside `getStringExtra`. The same trap catches `Alloy.Events.on('algo', unaFuncionConParametros)`.
 
+### Registering on Android: two calls that go quiet
+
+The channel has to exist and be handed to the module **before** asking for the token, and its id has to match the `default_notification_channel_id` meta-data in `tiapp.xml`. Mismatch them and the notification is posted against a channel nobody declared.
+
+```javascript
+modulo.notificationChannel = Ti.Android.NotificationManager.createNotificationChannel({
+  id: 'default_channel',        // the same id tiapp.xml declares
+  name: L('push_channel_name'),
+  importance: Ti.Android.IMPORTANCE_DEFAULT
+})
+
+modulo.registerForPushNotifications()
+
+// Firebase does not announce a token it already had, so didRefreshRegistrationToken
+// may never fire on a device that registered before. Ask for it once, a moment later.
+setTimeout(() => guardarToken(modulo.fcmToken), 4000)
+```
+
+That last line is the one that bites. On a fresh install the event fires and everything looks fine; on a device that already had a token from an earlier run it never fires, the app never sends the token to the server, and every push to that device is addressed to nobody. Make `guardarToken` idempotent — it will be called more than once with the same value.
+
 ## 2. The payload decides how much of the module runs
 
 Android distinguishes a *notification message* from a *data message*, and the difference is not cosmetic.
@@ -93,6 +112,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,20 +159,54 @@ 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) => {
-  abrirPanel((e.message && e.message.data) || {})
-})
+if (OS_ANDROID) {
+  // With the runtime alive the launcher Intent is not delivered a second time,
+  // so this event is the only way in.
+  modulo.addEventListener('didOpenNotification', (e) => {
+    abrirPanel((e.message && e.message.data) || {})
+  })
+
+  // On a cold start the module does not exist yet when the notification is
+  // opened, so the payload travels in the Intent. This is that route.
+  const desdeElIntent = (origen) => {
+    const contenido = Ti.Android.rootActivity.intent.getStringExtra('fcm_data')
+
+    if (!contenido) {
+      log.debug(`Nothing in the Intent (${origen})`)
+      return
+    }
+
+    modulo.clearLastData()
+    abrirPanel(JSON.parse(contenido))
+  }
+
+  Ti.App.addEventListener('resumed', () => desdeElIntent('resumed'))
+  desdeElIntent('arranque')
+}
 ```
 
+`resumed` stays even though the event covers the warm tap: it is what catches an Intent the module left behind on a version that still writes one. When the event delivered the payload the Intent is empty and the handler returns without opening anything, which is the exclusivity the section below describes.
+
 The payload sits under `message.data`, the same place `didReceiveMessage` puts it on both its live and its cold-start path, so one accessor covers a tap and an arrival. The first version of the event wrapped it directly in `message`; if the module you have predates 3.6.0, read `e.message` instead, or log the event once and look.
 
 The Intent is still how a cold start arrives, so keep that path. Check `timodule.xml` in your installed module for the event, or just add the listener and watch whether it fires: a module without it ignores the registration silently.
 
 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.
@@ -233,7 +292,15 @@ Verified case by case on an iPad. The third row is the one that does not work on
 
 ```javascript
 Ti.Network.registerForPushNotifications({
-  success: (e) => { enviarTokenAlServidor(e.deviceToken) },
+  success: (e) => {
+    // e.deviceToken is the APNs one. It is not what you send to a server that
+    // pushes through FCM, and Firebase picks it up on its own — see below.
+    log.info(`APNs token: ${e.deviceToken ? 'received' : 'EMPTY'}`)
+
+    modulo.fetchToken((r) => {
+      if (r && r.token) { guardarToken(r.token) }
+    })
+  },
   error: (e) => { log.error(e.error) },
   callback: (e) => {
     // Foreground, background and closed all arrive here.
@@ -258,6 +325,16 @@ if (OS_IOS) {
 }
 ```
 
+**The token comes from `fetchToken`, not from the property.** Right after APNs answers, `modulo.fcmToken` is empty: Firebase still has to exchange the APNs token for its own, and that exchange has no fixed duration. Waiting does not fix it — four seconds was still empty on a device. `fetchToken` calls back when the token exists, which is the only way to know.
+
+```javascript
+// The apnsToken is never assigned by hand. Firebase's swizzling does it, and
+// setting it yourself produces BadDeviceToken when you send.
+modulo.fetchToken((e) => {
+  if (e && e.token) { guardarToken(e.token) }
+})
+```
+
 **A data-only message shows nothing on iOS.** Android reads the text from `data`; iOS reads it from the APNs alert. Send both, they do not interfere:
 
 ```php
@@ -297,6 +374,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 |
@@ -306,3 +384,6 @@ Do not test with the app added to the battery whitelist. That measures a phone y
 | iOS registers but never gets a token | Firebase loaded after APNs answered | Section 8 |
 | iOS receives the push and does nothing when tapped | Empty `callback` | Section 8 |
 | Nothing arrives for twenty minutes, then five at once | OEM battery management | Section 9 |
+| Push works on a fresh install and never on a reinstall | `didRefreshRegistrationToken` does not fire for a token Firebase already had | Section 1 |
+| iOS: `fcmToken` is empty right after the permission is granted | It is; the APNs-for-FCM exchange has no fixed duration. Use `fetchToken` | Section 8 |
+| iOS: `BadDeviceToken` when sending | `apnsToken` was assigned by hand instead of leaving it to the swizzling | Section 8 |