@maccesar/titools 4.21.0 → 4.23.0

package/README.md

@@ -160,7 +160,7 @@ Together they work like this:
 | ------------------------------- | ------------------------------- | ----------------------------- |
 | "Create a login screen"         | Context about project structure | `ti-expert`, `ti-ui`          |
 | "Optimize ListView performance" | Points to docs location         | `ti-ui` reads specific files  |
-| "Implement push notifications"  | API reference paths             | `ti-howtos`                   |
+| "Implement push notifications"  | API reference paths             | `ti-expert`, `ti-howtos`      |
 
 You do not need to explicitly invoke skills. The AI detects when to use them based on your question.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.21.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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ti-expert
-description: "Use when designing, reviewing, auditing, or analyzing Titanium SDK architecture and implementation (Alloy or Classic) — creating controllers/views/services, choosing models vs collections, deciding between app-owned and system UI, designing reusable Widgets or feedback/modality patterns, hunting memory leaks and cleanup gaps, testing, migrating legacy apps, building adaptive layouts for tablets, foldables and large screens, or moving documents in and out of the app: custom file types, UTIs, CFBundleDocumentTypes, Android intent filters, AirDrop/Quick Share, document icons, sharing a link or file via the iOS share sheet or Android intent chooser. AUTO-DETECT: If tiapp.xml exists, invoke BEFORE architectural decisions, new controllers/views, feedback components, or restructuring. Titanium navigation, memory, event, and modal patterns differ from web frameworks."
+description: "Use when designing, reviewing, auditing, or analyzing Titanium SDK architecture and implementation (Alloy or Classic) — creating controllers/views/services, choosing models vs collections, deciding between app-owned and system UI, designing reusable Widgets or feedback/modality patterns, hunting memory leaks and cleanup gaps, testing, migrating legacy apps, building adaptive layouts for tablets, foldables and large screens, or moving documents in and out of the app: custom file types, UTIs, CFBundleDocumentTypes, Android intent filters, AirDrop/Quick Share, document icons, sharing a link or file via the iOS share sheet or Android intent chooser, or push notifications: FCM, a tap that opens nothing, an app that restarts when tapped. AUTO-DETECT: If tiapp.xml exists, invoke BEFORE architectural decisions, new controllers/views, feedback components, or restructuring. Titanium navigation, memory, event, and modal patterns differ from web frameworks."
 argument-hint: "[architecture-topic]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
 ---
@@ -26,6 +26,7 @@ This file is an index. Read the references that govern the task before making a
 | Tablet, foldable, large screen, or responsive behavior | [Adaptive layouts](references/adaptive-layouts.md) |
 | Opening or receiving files: custom extensions, UTIs, intent filters, AirDrop, Quick Share, document icons | [File type association](references/file-type-association.md) |
 | Sending content out: share sheet, intent chooser, sharing a link or a file, `dk.napp.social`, `com.alcoapps.socialshare` | [Sharing content out](references/sharing.md) |
+| Push notifications: FCM, `firebase.cloudmessaging`, a tap that opens nothing, an app that restarts on tap, the payload to send | [Push notifications](references/push-notifications.md) |
 | Security architecture | [Security fundamentals](references/security-fundamentals.md), [Device security](references/security-device.md) |
 | Testing or performance | Load the matching guide under Quality & Performance below |
 
@@ -185,6 +186,7 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 - [Controller Patterns](references/controller-patterns.md)
 - [File Type Association](references/file-type-association.md) (custom extensions and UTIs, `CFBundleDocumentTypes`, Android intent filters, receiving files from AirDrop/Quick Share, document icons)
 - [Sharing Content Out](references/sharing.md) (share sheet and intent chooser, why iOS still needs `dk.napp.social` and Android does not, text versus file, iPad popovers)
+- [Push Notifications](references/push-notifications.md) (the four doors a push arrives through on Android, why a tap does not fire `didReceiveMessage`, `singleTop` and `newintent`, data-only versus `notification` block, the HTTP v1 payload)
 - [Feedback Surfaces & App-Owned UI](references/feedback-surfaces.md)
 - [Feedback Widget Contracts](references/feedback-widget-contracts.md)
 - [Feedback Migration](references/feedback-migration.md)

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

@@ -0,0 +1,325 @@
+# Push notifications: what actually reaches your code
+
+Receiving a push in a Titanium app is not one path. On Android a notification can reach your JavaScript through four different doors depending on what the app was doing when it arrived and what the person did with it, and the official documentation describes one of them.
+
+iOS has one door and it works in every state. That asymmetry matters when a bug report says "it works on my iPhone": the same app, the same payload and the same handler behave differently, and the difference is not in your code.
+
+That is the fact that explains every "the notification arrives but nothing happens" report you will find. The push is delivered, nothing errors, and the feature simply does not run, because the code is listening at a door the message never came through.
+
+This file is about the community module [`firebase.cloudmessaging`](https://github.com/hansemannn/titanium-firebase-cloud-messaging), which is how Titanium apps do FCM. `Ti.Network.registerForPushNotifications()` exists on Android too, but its job there is the `POST_NOTIFICATIONS` runtime permission, not the token: it never reads a `callback` and never returns a `deviceToken`. The FCM token comes from the module.
+
+<!-- TOC-START -->
+## 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)
+- [4. The case nobody documents: tapping with the app in front](#4-the-case-nobody-documents-tapping-with-the-app-in-front)
+- [5. Why two splash screens flash by](#5-why-two-splash-screens-flash-by)
+- [6. Sending the message](#6-sending-the-message)
+- [7. Every value inside `data` is a string](#7-every-value-inside-data-is-a-string)
+- [8. iOS](#8-ios)
+- [9. The device may sit on your push for twenty minutes](#9-the-device-may-sit-on-your-push-for-twenty-minutes)
+- [10. Symptom to cause](#10-symptom-to-cause)
+
+<!-- TOC-END -->
+
+## 1. The four doors
+
+| What the app was doing | Where the payload arrives | Requires |
+| --- | --- | --- |
+| Open, in front, message arrives | `didReceiveMessage` on the module | nothing |
+| Closed, person taps the notification | `fcm_data` extra on the launch Intent | reading it at startup |
+| 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 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.
+
+The first row is the only one the module's own example covers. The second and third are in its README under `### Android intent data`, a section that sits between the token example and "Sending push messages" with no explanation of why you would need it. The fourth is not documented anywhere.
+
+A single handler serves all four:
+
+```javascript
+if (OS_ANDROID) {
+  const mostrarAviso = (intentNuevo, origen) => {
+    const intent = intentNuevo || Ti.Android.rootActivity.intent
+    const contenido = intent.getStringExtra('fcm_data')
+
+    if (!contenido) {
+      log.debug(`Sin aviso en el Intent (${origen})`)
+      return
+    }
+
+    let datos
+    try {
+      datos = JSON.parse(contenido)
+    } catch (error) {
+      modulo.clearLastData()
+      return
+    }
+
+    // Consume it, or the same payload fires again on the next resume.
+    modulo.clearLastData()
+    log.info(`Aviso abierto (${origen})`)
+    abrirPanel(datos)
+  }
+
+  // Both events pass an argument of their own, so they are wrapped: only
+  // 'newintent' carries an Intent and only it should be forwarded.
+  Ti.App.addEventListener('resumed', () => mostrarAviso(null, 'resumed'))
+  Ti.Android.rootActivity.addEventListener('newintent', (e) => mostrarAviso(e.intent, 'newintent'))
+
+  mostrarAviso(null, 'arranque')
+}
+```
+
+**Label the origin.** Not for tidiness: when someone reports that no panel appeared, the word in that log line tells you immediately which door was involved, and the four behave differently. Without it every path prints the same sentence and a whole afternoon goes into finding out which one ran.
+
+**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)`.
+
+## 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.
+
+Send a top-level `notification` block with the app in the background and Android posts the notification itself. `onMessageReceived` is never called, so `showNotification()` never runs and `PushHandlerActivity` never runs. What that costs:
+
+- `image`, `big_text`, `big_text_summary`, `icon`, `rounded_large_icon`, `force_show_in_foreground`, `id`, `color`, `vibrate`, `sound` and `badge` are all ignored.
+- The tap intent belongs to the system, so tapping **launches the app from scratch** instead of resuming it. Any game in progress, any half-filled form, gone.
+
+That last symptom is worth naming because it sends people down the wrong road. It looks like an activity or `launchMode` problem, and it is not: `launchMode="singleTask"` on the root activity makes it worse, and patching the module's `PushHandlerActivity` does nothing, because neither of them ever runs. The fix is on the sender: put the fields inside `data`.
+
+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`.
+
+The only thing that turns that extra into the event is `parseBootIntent()`, and it is called from exactly one place: the end of the module's `registerForPushNotifications()`. So the tap behaves differently depending on the app's state:
+
+- **App closed.** It starts, calls register, `parseBootIntent()` runs, `didReceiveMessage` fires.
+- **App backgrounded.** It resumes, register is not called again, nothing fires. The payload sits on the Intent and nobody reads it.
+
+Two paths out of three appear to work, which is what makes this so hard to see. Taps work from a cold start, foreground delivery works, and the background case fails silently — so the investigation starts on the server.
+
+If you read the Intent yourself at startup, as in section 1, `parseBootIntent()` finds nothing afterwards because `clearLastData()` already removed the extra. Only one of them fires. That is fine, and it is why the log says `arranque` rather than `didReceiveMessage` on a cold start.
+
+## 4. The case nobody documents: tapping with the app in front
+
+The notification arrived earlier and stayed in the tray. Later the person opens the app and plays. Then they pull down the shade for something else, see your notification there, and tap it.
+
+The app is already in the foreground. It never paused, so **`resumed` does not fire**. And the activity is not recreated, so nothing reads the Intent. Nothing happens at all.
+
+This is not an edge case. It is the most ordinary way a stored notification gets opened.
+
+It needs two things, and neither works without the other:
+
+```xml
+<!-- tiapp.xml, inside <application> -->
+<activity android:name="com.yourdomain.yourapp.YourAppActivity"
+          android:launchMode="singleTop" tools:node="merge" />
+```
+
+```javascript
+Ti.Android.rootActivity.addEventListener('newintent', (e) => mostrarAviso(e.intent, 'newintent'))
+```
+
+Without `singleTop`, Android treats the launcher Intent as "bring the existing task to the front" and discards it, so `onNewIntent` never runs and `newintent` never fires. Without the listener, the Intent arrives and nobody reads it.
+
+`singleTop` is not `singleTask`. `singleTask` clears the task stack and will restart your app from its first screen; `singleTop` only prevents a second instance when the activity is already on top, and leaves the stack alone. Confusing the two costs a debugging session.
+
+Take the activity name from the built manifest rather than guessing it: `build/android/app/build/intermediates/merged_manifest/debug/processDebugMainManifest/AndroidManifest.xml`.
+
+### If your module fires `didOpenNotification`
+
+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) || {})
+})
+```
+
+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.
+
+Two separate causes, and it is worth knowing which is which before trying to fix either.
+
+**The module's own activity.** `PushHandlerActivity` is declared in the module's `timodule.xml` without `android:theme`, so it inherits the application theme and Android gives it a full window with an enter and an exit animation. The activity calls `finish()` on its first line and never shows anything.
+
+**Titanium's resume mechanism.** `TiRootActivity.onCreate()` builds the only intent it accepts:
+
+```java
+// This is the only intent Titanium supports in order to simulate "singleTask" like resume behavior.
+Intent mainIntent = Intent.makeMainActivity(getComponentName());
+mainIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+mainIntent.addFlags(Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED);
+mainIntent.setPackage(getPackageName());
+```
+
+The module's relaunch intent does not match it, so Android creates a **second** root activity. That one recognises itself as a duplicate, forwards the intent to the live activity through `onNewIntent()` and finishes. It works — and it is in fact what delivers the payload — but the duplicate draws its own splash first.
+
+The two are linked: the mismatch is what makes the delivery happen. "Fixing" the intent so it matches removes the second splash **and** the delivery, unless the module also fires an event for the tap. Verified by trying it: the extra window disappeared and the panel stopped appearing.
+
+So this is not something an app can fix on its own. Do not spend an afternoon on `launchMode` or on splash themes looking for it.
+
+## 6. Sending the message
+
+The legacy FCM API, the one with `'to' => 'DEVICE_TOKEN'` and a server key, was deprecated on 20 June 2023 and shut down from 22 July 2024. Examples using it are still all over the web and they no longer deliver anything.
+
+HTTP v1 needs an OAuth 2.0 access token instead of the static key, which is why examples use a library rather than a bare POST.
+
+```php
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
+use Kreait\Firebase\Factory;
+use Kreait\Firebase\Messaging\CloudMessage;
+
+$factory = (new Factory)->withServiceAccount('/path/to/service-account.json');
+$messaging = $factory->createMessaging();
+
+$message = CloudMessage::new()
+    ->withToken($token)
+    ->withData([
+        'title' => 'Title',
+        'message' => 'Body',
+        'channelId' => 'default_channel',
+    ]);
+
+$messaging->send($message);
+```
+
+`composer require kreait/firebase-php`. Note `withToken()`: version 8.0 removed `CloudMessage::withTarget()` outright and deprecated `toToken()`, so older snippets fail on a fresh install.
+
+`channelId` must match a channel your app created, or Android 8 and later drop the notification with nothing in the log to say so.
+
+**Without Composer**, sign the service account JWT yourself with `openssl_sign`, exchange it for an access token at Google's token endpoint, and POST the same payload to `https://fcm.googleapis.com/v1/projects/<project-id>/messages:send`. It is about forty lines and it is the right answer when deployment does not carry `/vendor` to the server.
+
+To reach every installed device without keeping token lists, send to a topic the app subscribes to at startup. Two requests cover a whole install base regardless of size, with no queue, no batching and no dead tokens to clean up.
+
+## 7. Every value inside `data` is a string
+
+FCM rejects anything else. Sending `['badge' => 3]` or `['vibrate' => true]` returns an `INVALID_ARGUMENT` naming the field, and Kreait throws before the request even leaves.
+
+This collides with the module's documented field list, which describes `vibrate` as boolean, `badge` and `id` as int, and `rounded_large_icon` and `force_show_in_foreground` as Boolean. They travel as `"true"` and `"1"`. The module parses them back with `TiConvert.toBoolean` and `JSONObject.optBoolean`, both of which accept the string forms.
+
+An `array_map('strval', ...)` over the whole payload before sending saves the round trip.
+
+## 8. iOS
+
+iOS has one door, and it works. Everything in section 1 is an Android problem.
+
+`Ti.Network.registerForPushNotifications` takes a `callback`, and that callback fires whether the message arrives with the app in front, whether the person taps a notification from the tray, and whether the app was closed. There is no intent to read, no `launchMode` to declare, no second listener. The payload is in `e.data`, and `e.inBackground` says which it was.
+
+| What the app was doing | Panel shown |
+| --- | --- |
+| Open, in front, message arrives | yes |
+| Backgrounded, person taps | yes |
+| Already in front, person taps a stored notification | yes |
+| Closed, person taps | yes |
+
+Verified case by case on an iPad. The third row is the one that does not work on Android without the extra listener, which is worth knowing when a bug report says "it works on my iPhone".
+
+```javascript
+Ti.Network.registerForPushNotifications({
+  success: (e) => { enviarTokenAlServidor(e.deviceToken) },
+  error: (e) => { log.error(e.error) },
+  callback: (e) => {
+    // Foreground, background and closed all arrive here.
+    const datos = (e && e.data) || {}
+    abrirPanel(datos)
+  }
+})
+```
+
+The module's own `example/app.js` leaves that callback empty, so copying the example gives an app that registers correctly, receives the push, and does nothing when tapped.
+
+**Firebase has to start before APNs answers.** The module's `_configure` registers it as an application delegate, and its `didRegisterForRemoteNotificationsWithDeviceToken` is what hands the APNs token to Firebase. Load the module later, from a service or from a window's `open` handler, and APNs has already answered: nobody picks that token up and Firebase never issues one of its own.
+
+Nothing fails visibly. The permission is granted, APNs returns a 64-character token, and then `fetchToken` never calls back and `didRefreshRegistrationToken` never fires. There is nothing in any log pointing at load order.
+
+```javascript
+// alloy.js
+if (OS_IOS) {
+  const FirebaseCore = require('firebase.core')
+  FirebaseCore.configure()
+  require('firebase.cloudmessaging')
+}
+```
+
+**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
+'data' => ['title' => $titulo, 'message' => $cuerpo, 'channelId' => 'default_channel'],
+'apns' => [
+    'headers' => ['apns-priority' => '10'],
+    'payload' => ['aps' => ['alert' => ['title' => $titulo, 'body' => $cuerpo], 'sound' => 'default']],
+],
+```
+
+Forgetting the `apns` block is a quiet failure: Android works, iOS receives the message and displays nothing, and the payload is identical in both.
+
+**Images need a Notification Service Extension.** *Read, not run.* The module's `image` field is Android only: `showNotification()` downloads it and builds a `BigPictureStyle`. On iOS, Firebase documents `apns.fcm_options.image` together with `"mutable-content": 1` inside `aps`, and that path needs a Notification Service Extension in the app, a separate Xcode target with its own App ID and provisioning profile, which a module cannot ship.
+
+An image inside your own UI is a different matter and works normally: it is just a URL in `data` that your controller hands to an `ImageView`.
+
+**`defaultImage` is a placeholder, not a fallback.** An `ImageView` that declares `defaultImage` and never gets an `image` renders the default on Android and an empty box on iOS. Reproduced on a device, and fixed by assigning the local asset explicitly:
+
+```javascript
+// Not: if (args.imagen) { $.preview.applyProperties({ image: args.imagen }) }
+$.preview.applyProperties({ image: args.imagen || LOGO })
+```
+
+The API reference calls `defaultImage` the image to show *while* the remote one loads, so leaning on it for "no image at all" asks more of it than it promises. The failure is invisible from Android, which is where this kind of notification usually gets tested.
+
+## 9. The device may sit on your push for twenty minutes
+
+Aggressive OEM battery management holds FCM messages for backgrounded apps and releases them in a batch when something wakes the connection. On a ColorOS device this shows up in logcat by name, `OplusHansManager freeze`, seconds after the app goes to the background.
+
+The practical consequence is for testing, not for production: a message that has not arrived after ten seconds has not necessarily failed. Confirm arrival in the log before concluding anything, or you will spend an hour debugging a delivery that was simply queued. Five test messages arriving within 700 milliseconds of each other, after twenty minutes of silence, is what this looks like.
+
+Do not test with the app added to the battery whitelist. That measures a phone your users do not have.
+
+## 10. Symptom to cause
+
+| Symptom | Cause | Where to look |
+| --- | --- | --- |
+| 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 |
+| Nothing is delivered and no error comes back | Legacy FCM API, shut down in 2024 | Section 6 |
+| `INVALID_ARGUMENT` naming a `data` field | A non-string value | Section 7 |
+| Android shows the notification, iOS shows nothing | No `apns.payload.aps.alert` in the message | Section 8 |
+| 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 |

package/skills/ti-ui/references/icons-and-splash-screens.md

@@ -14,6 +14,7 @@
 - [9. Common issues](#9-common-issues)
 - [11. iOS launch files (storyboards)](#11-ios-launch-files-storyboards)
 - [Best practices](#best-practices)
+- [Community-Discovered Patterns](#community-discovered-patterns)
 
 <!-- TOC-END -->
 
@@ -401,3 +402,37 @@ iOS caches launch screen snapshots. If changes do not appear:
 6. Square icons only.
 7. Clean the project after icon changes.
 8. Use adaptive icons for Android 8.0+.
+
+## Community-Discovered Patterns
+
+### Android 12+ splash: the theme's parent decides whether any of it applies
+
+Verified against SDK 13.4.1.GA, reading the generated `build/android/app/src/main/res/values*/ti_styles.xml` and `res/values-v31/` inside `titanium-13.4.1.aar`.
+
+Titanium writes `android:theme="@style/Theme.Titanium"` onto the launcher Activity it generates, and builds this chain, where the last link is whatever theme the app declared on `<application>`:
+
+```text
+Theme.Titanium
+└── Base.Theme.Titanium.Splash
+    └── Theme.AppDerived
+        └── the app's <application> theme
+```
+
+An `<application>` theme therefore ends up an *ancestor* of `Theme.Titanium`, and loses every attribute the two links below it already set. On API 31+ those are `android:windowBackground` and `android:windowSplashScreenBackground`, so a splash color declared on `<application>` silently does nothing. A custom theme must inherit from `@style/Theme.Titanium` and be assigned to the launcher Activity, which is what section 6's `tiapp.xml` snippet does — but its companion style inherits from `Theme.MaterialComponents.NoActionBar`, which detaches from the chain and drops the app's own theme with it.
+
+Three attributes, one color:
+
+| Attribute | Consumer |
+|---|---|
+| `android:windowSplashScreenBackground` | The API 31+ system splash. |
+| `android:windowBackground` | The native window between the system splash and Titanium's first Window. |
+| `android:colorBackground` | `Base.Theme.Titanium.Splash` points `windowSplashScreenBackground` at `?android:attr/colorBackground` on API 31+, and the launch status and navigation bars read it. |
+
+Two consequences worth knowing before choosing a value:
+
+- **Setting only the first two leaves the inherited color showing.** `colorBackground` is the one that is easy to miss.
+- **A flat color for `windowBackground` replaces `@drawable/titanium_splash_icon_background`**, the layer-list Titanium uses on API 31+. That drawable paints a 160 dp white circle behind the icon, which is invisible on a white background and obvious on any other. Replacing it with a plain color removes the circle and the icon along with it.
+
+Section 6's troubleshooting entry says the background color is the only customizable part. `android:windowSplashScreenAnimatedIcon` replaces the icon too — it is an icon slot, not a full-screen image, so the color around it still comes from the attributes above.
+
+The `purgetss` skill's [launch-background.md](../../purgetss/references/launch-background.md) carries the full version of this, including the interaction with the legacy `res-*/default.png` artwork, and `purgetss brand --notes` prints the setup with the project's own brand color already substituted.