Watchapp notification subscription api

[killdano]

Add notification subscription API for watchapps

This PR introduces a platform capability for watchapps to receive structured notification events from packages they declare interest in. Designed for live mirroring use cases where a watchapp wants to surface a phone-side app's ongoing-activity state on the watch face — turn-by-turn from Google Maps, now-playing from Spotify, fitness session from Strava, ride status from Uber, etc.

The motivating use case is MirrorMap, which uses Maps' navigation notifications (turn text + distance + ETA + arrow icon) to drive a live HUD overlay on the watch independent of any MirrorMap-side route state. But nothing in this PR is Maps-specific — any package can be declared in the watchapp's notificationFilter array.

Builds on coredevices#171

This PR is stacked on top of [Add share-intent target API for watchapps](coredevices#171) because the two share PKJS infrastructure — both add new event types via the same registration pattern in startup.js, dispatch through the same JsRunner mechanism, and read package.json fields via the same PbwAppInfo parser. The base branch for this PR is set to share-intent-target-api, so the diff shows only the incremental notification-subscription changes. After PR 1 lands, this PR's base will auto-rebase to master.

What's new

Watchapp side

Watchapps opt in via a new field in package.json:

{
  "notificationFilter": ["com.google.android.apps.maps", "com.spotify.music"]
}

PKJS receives notifications via:

Pebble.addEventListener('appnotification', function(e) {
  // e.package         — source package name
  // e.posted          — true on post, false on removal
  // e.title, e.text   — convenience-surfaced text fields
  // e.subText, e.infoText
  // e.smallIconBase64 — base64 PNG, 32×32 (see "Icon forwarding" below)
  // e.largeIconBase64 — base64 PNG, 32×32
  // e.extras          — full extras Bundle as a JSON object
});

Watchapps that need to catch up on existing notification state when spinning up (e.g. user launched watchapp mid-trip with Maps already navigating) call:

Pebble.getActiveNotifications(['com.google.android.apps.maps'])
  // returns array of notification objects in the same shape as appnotification events

Consent model

A watchapp's declaration in package.json is the consent signal. The user explicitly installed a watchapp that announced its notification interests; no separate per-watchapp consent prompt is required. The Pebble app's existing notification access grant — a single OS-level permission already granted by the user — is the only OS-level gate.

This keeps the UX simple while remaining responsible: watchapps can't silently expand their notification access after install (the filter list is read from the PBW manifest at install time and fixed for the lifetime of that PBW version).

Foreground-only dispatch

PKJS only exists for the watchapp currently running on the watch, so notifications only flow while the user has the watchapp open. This is a deliberate choice — it bounds the privacy surface area and avoids the watchapp-as-background-listener antipattern. Watchapps that need to bootstrap state on launch use getActiveNotifications for catch-up.

Icon forwarding

smallIconBase64 and largeIconBase64 ship the notification's icons as base64-encoded 32×32 PNGs.

This is included because notification icons are often the most semantically rich visual signal — Maps' turn arrows (left, right, straight, U-turn, exit, roundabout, etc.) live in the smallIcon, music apps put album art in largeIcon, fitness apps put activity glyphs in smallIcon. Without forwarding the icons, watchapps would have to bake a separate icon set into firmware for every source app they want to mirror — which doesn't scale.

NotificationIconExtractor rasterizes the icons via Drawable.draw() to a fixed 32×32 ARGB bitmap and PNG-encodes them. Failures are best-effort (logged + skipped) — they don't affect the rest of the payload. Icons are skipped on removal events (the icon adds no signal when the notification is being cleared).

Cost: ~280-820 bytes per icon base64-encoded; trivial overhead at typical notification rates.

Architecture

Three new classes split by platform:

• WatchappNotificationDispatcher (commonMain) — fans incoming notifications out to the currently-running PKJS watchapps that subscribe to the source package. Cheap to call on every notification (typically O(connected_watches) with usually 1 watch and 1 running PKJS).

• WatchappNotificationSerializer (androidMain) — converts an Android StatusBarNotification to JSON for PKJS consumption. Surfaces well-known fields at top level for convenience plus a raw extras map for app-specific keys (e.g. Maps's ongoingActivityNoti.next_step_message). Non-primitive extras (Parcelables, RemoteInput) are skipped — JSON isn't the right format for those.

• NotificationIconExtractor (androidMain) — Drawable → 32×32 bitmap → PNG → base64. Fast path when the Drawable is already a bitmap of the target size; otherwise standard Canvas.draw() rasterize.

LibPebbleNotificationListener already had the platform-level notification access; this PR adds a sibling fan-out path to the existing notification-relay pipeline. The original watch-UI relay is unchanged; failures in the new watchapp dispatch path don't affect it.

Testing notes

End-to-end validated on a Samsung Galaxy + Pebble Time Steel with MirrorMap as the subscriber. Tested:

• ✅ Live notification streaming during Google Maps active navigation (notifications arriving every ~10s, parsed for turn text + distance + ETA, displayed on watch via MirrorMap's HUD overlay)
• ✅ getActiveNotifications cold-start retrieval (user launches MirrorMap mid-trip with Maps already navigating; gets immediate state without waiting for next push)
• ✅ Notification removal events firing the posted: false event when Maps clears its persistent ongoing-activity notification
• ✅ Icon forwarding verified end-to-end via PKJS console log: smallIcon ~968 bytes base64, largeIcon ~596 bytes base64, both null on removal events

Caveats / known limitations

• CloudPebble strips unknown manifest fields. Same workaround as PR 1 — post-build appinfo.json patching for now.
• iOS receiving side is not implemented. Stub JavascriptCoreJsRunner.kt no-op for iOS. PKJS event interface is platform-neutral so iOS can be added later.
• No app-specific parsing. This PR forwards raw notification fields. Watchapps that want structured turn-direction or maneuver-type data from Maps notifications need to do their own parsing of the text/extras (or use the smallIcon as a maneuver-type signal).

Files

New

• libpebble3/.../notification/WatchappNotificationDispatcher.kt
• libpebble3/.../notification/WatchappNotificationSerializer.kt
• libpebble3/.../notification/NotificationIconExtractor.kt
• libpebble3/.../di/WatchappNotificationModule.kt

Modified — see commit for full list. Highlights: package.json parsing (PbwAppInfo.kt) for notificationFilter field, PKJS event registration, fan-out hook in LibPebbleNotificationListener.kt.

---

cc @ericmigi — per our discussion. Stacked on coredevices#171 (share-intent target API).