Add notification subscription API for watchapps

[killdano]

Note: This PR is built on top of #171; the first three commits are prerequisites that will disappear from this PR's view once #171 lands. Commits 4–6 are the new work.

---

This PR introduces a notification subscription API for watchapps, designed around per-watchapp field opt-in. A watchapp's package.json notificationFilter declares both which source apps it wants notifications from and which fields of those notifications it wants extracted on the phone and forwarded to PKJS.

Why opt-in fields

Bluetooth bandwidth to the watch is the binding constraint for this whole feature. A naive design that forwards every available notification field to every subscribing watchapp would force every consumer to pay the price of every field — adding album art for one watchapp would slow down navigation updates for another. With per-watchapp opt-in:

• Cheap, broadly useful fields (text, category, standard icons, action presence flags, primitive extras) ship in the default field set and watchapps that just want "notification arrived from package X" get them automatically.
• Bandwidth- or CPU-heavy fields (full bitmaps, structured media metadata, message arrays, Android 14+ Ongoing Activity icons) are explicit opt-ins. A watchapp pays for what it asks for.
• Forward-compatible: future fields can be added without renegotiating the default payload. Existing watchapps continue working unchanged; new ones declare what they want.

Schema

notificationFilter accepts both shapes; they can be mixed in the same array.

Bare-string — package name only, watchapp gets the default field set:

"notificationFilter": ["com.example.app"]

Object form — explicit field opt-in:

"notificationFilter": [
  {
    "package": "com.google.android.apps.maps",
    "fields": ["title", "text", "category", "iconExtras"]
  }
]

The polymorphic deserializer (NotificationSubscription.Serializer) accepts either; encoded form is always the object form.

Field catalog

Field	In default set?	Notes
title, text, subText, infoText	✅	Standard text slots
category	✅	Notification.category
smallIconBase64, largeIconBase64	✅	32×32 PNG, base64
actions	✅	{title, hasIntent} per action
extras	✅	Primitive entries from extras bundle
bigPictureBase64	—	BigPictureStyle photo, downsampled to fit byte cap
mediaMetadata	—	MediaSession state: {title, artist, album, durationMs, positionMs, playbackState, albumArtBase64}
messagingMessages	—	MessagingStyle messages: [{sender, timestamp, text}, …]
inboxLines	—	InboxStyle lines: […]
iconExtras	—	Icon-typed entries from extras (Android 14+ Ongoing Activity glyphs)

Per-field extraction is best-effort. Each field is wrapped in try/catch; per-field exceptions are logged at trace and the field surfaces as null/empty in the JSON, but other fields continue to be processed.

iconExtras and Maps' Ongoing Activity glyphs

Worth a section of its own — it's the most novel piece in this PR.

Android 14 introduced the Ongoing Activity API for rich live notifications. Google Maps' nav notification is the canonical example: turn-direction arrow, lane guidance, arrival flag, ETA chip glyph all stored as Icon parcelables in the notification's extras bundle, under keys named android.ongoingActivityNoti.chipIcon / nowbarIcon / secondIcon.

These don't surface via Notification.smallIcon / largeIcon (those carry the brand glyph), and they don't surface via Notification.contentView / bigContentView either — Maps' Ongoing Activity notifications don't populate those at all. The extras bundle is where the dynamic glyphs live.

iconExtras walks the extras bundle, finds every Icon-typed entry, rasterizes each to a 32×32 ARGB PNG, and emits a JSON object map keyed by extras key:

"iconExtras": {
  "android.ongoingActivityNoti.chipIcon": {
    "base64": "iVBORw0KGgo…",
    "hash": "9589c01a",
    "intrinsicW": 84,
    "intrinsicH": 84
  },
  "android.ongoingActivityNoti.nowbarIcon": { … },
  "android.largeIcon": { … }
}

Empirical validation

Live drives with the extractor confirmed Maps publishes a stable set of distinct glyphs across turn states. From two test trips:

State	chipIcon hash	largeIcon hash
Continue / straight	9589c01a	8fa71c8d
Turn left	1ad8de36	28f6365a
Turn right	5af1cf48	9d427851
U-turn	87d3a7aa	487ecffa
Arrive	35b76267	c4939096

The U-turn hash was confirmed by correlation with Maps' own voice-prompt timing — _MAKE_A_UTURN.mp3 fired 12 ms before the icon transition. The icon channel reliably encodes turn state even when the text channel doesn't (during the U-turn, Maps' notification text was "toward Kelvin Ave", which a text-only parser would have read as "continue straight").

Compatibility

• The bare-string form is the simple case for watchapps that just want "notify me when something arrives from package X" — they get a sensible default field set without extra ceremony.
• The schema is forward-compatible: field names not in the running libpebble3's catalog don't cause parse rejection. A watchapp targeting a future libpebble3 version can declare new fields and still load on older phones (it just won't get those fields in payloads).

Out of scope (intentionally)

• RemoteViews ImageView extraction. Investigated as an alternative path to dynamic glyphs; for Google Maps it returns nothing (contentView and bigContentView are both null on Ongoing Activity notifications). The iconExtras extractor covers the same use case via a stable Android API surface. If a future use case for RemoteViews extraction emerges, it can be added as another opt-in field without disturbing this design.
• Action invocation. actions field surfaces {title, hasIntent} per declared action button; PendingIntent dispatch from the watch is left for v2.

Diagnostic logging

WatchappNotificationSerializer emits a trace-level line per dispatched notification showing the parsed field set:

serialize <pkg> posted=<bool> fields=<set>

Useful for confirming per-watchapp opt-in is reaching the serializer correctly when integrating a new watchapp; trace-level only so it's silent at production logging levels.

Commits

1. Per-watchapp field opt-in for notification subscriptions — schema, dispatcher, listener plumbing, and the cheap default fields wired up.
2. Heavyweight notification extractors (BigPicture / Media / Messaging / Inbox) — opt-in fields for the standard rich-notification styles.
3. Extract Icon-typed entries from Notification.extras (iconExtras) — Android 14+ Ongoing Activity glyph extraction, motivated by the empirical findings above.

[CLAassistant]

All committers have signed the CLA.

[ericmigi]

@sjp4 is working on a permissioning system for apps that will be a prerequisite for this PR. He can also weigh in on whether this API makes sense as written.

The idea is awesome, though. It would be great for apps to be able to show custom, more detailed UIs for notifications!

[sjp4]

meta: this isn't really possible to review because it's based on another branch - you can choose the target branch at the top of the PR to fix that.

We probably don't want a dedicated API for this, IMO. Also this is not possible on iOS, so can never be a cross-platform API.

We are working on a broad set of generic APIs for sharing data sources, on top of which notifications could be exposed natively on Android.