feat: apple watch app + home screen widgets

[islandbitcoin]

Summary

• Adds the Flash Apple Watch app and BTC price complication with live BTC price, 30-day chart, Flash branding, refresh state, Scan quick action, and Receive Paycode QR display on the watch.
• Adds iOS home-screen WidgetKit support with BTC price, 30-day watch-style sparkline, stale chart-data cleanup, and Scan/Receive quick actions.
• Adds Android home-screen widget support and native bridge wiring so widget/watch state stays synced from the React Native app.
• Wires WatchConnectivity, app-group entitlements, Xcode targets/embed settings, and CocoaPods fixes needed for clean native builds.

Verification

• git diff --check origin/main...HEAD
• xcodebuild -workspace ios/LNFlash.xcworkspace -scheme 'FlashWatch Watch App' -configuration Debug -destination 'platform=watchOS Simulator,id=B12E90B2-3F78-4E36-874D-EC1835869416' -derivedDataPath /tmp/lnflash-watch-action-dd build
• xcodebuild -workspace ios/LNFlash.xcworkspace -scheme FlashWidgetExtension -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath /tmp/lnflash-watch-action-dd build
• xcodebuild -workspace ios/LNFlash.xcworkspace -scheme FlashWidgetExtension -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath /tmp/lnflash-watch-qr-ios-dd build

Current CI Notes

• Passing on latest checked run before cleanup: CodeQL and Conventional commits.
• Failing: Check Code stops at tsc -p . with TS5095 under the repo's current TypeScript config.
• Failing: Tests stop before running test cases because ts-jest cannot load missing ttypescript.
• Failing: Spell Check reports repo-wide existing typos such as Governement, Cantacts, Infor, and Enjoing in files outside this watch/widget scope.

Notes

• Local yarn tsc:check with the existing config hits the same TS5095 CI blocker.
• A local experiment with module: esnext, moduleResolution: bundler, and ts-patch clears the immediate CI config blockers but exposes broad existing TypeScript errors across app/test files, so that config cleanup is intentionally not included in this PR.

[islandbitcoin]

⛔ Request changes (posted as a comment — GitHub blocks the request-changes state on your own PR)

Solid feature work — the watch app, complication, and widgets are well organized, and the tooling fixes are sound. But four issues below are merge-blockers in my view: the watch quick actions silently do nothing in their primary use case, the pre-existing LNFlash-Alt target no longer compiles or signs, non-USD users (i.e. JMD — our home market) get corrupted watch charts, and every whole-widget tap lands on the Send screen with an error instead of Home.

Hold merge for:

1. Watch quick actions no-op when the phone app is backgrounded (WatchConnectivityBridge.swift)
2. LNFlash-Alt target broken — compile + entitlements (AppDelegate.mm, entitlements)
3. Mixed-currency history corrupts the watch chart/badge (PriceService.swift append)
4. flash://home routes to the Send screen; scan/receive shadow usernames (deep-link config)

Fast-follow candidates: Android widget render-before-fetch + process death, Float price truncation, complication self-reload, and the native-layer duplication cluster (2× PriceService, 2× sparkline, 3× hardcoded prod endpoint, duplicated paycode builder).

Inline comments have committable suggestions where the fix is local. One thing I explicitly checked and did NOT flag: cold-start deep links are fine — setAppUnlocked re-fetches Linking.getInitialURL() and replays it through the live listener.

[islandbitcoin]

Blocker: quick actions do nothing unless the phone app is already foregrounded. When the watch's sendMessage wakes this app in the background, iOS ignores UIApplication.shared.open — third-party apps cannot foreground themselves. The transferUserInfo fallback lands in didReceiveUserInfo and dead-ends in this same call, and the reply handler unconditionally reports received: true, so the failure is invisible on both sides. The comment in PhoneConnectivity.swift ("sendMessage can wake the iOS app in the background") is true, but the woken app still can't present UI.

Suggested approach: check UIApplication.shared.applicationState; if not .active, post a local notification (UNUserNotificationCenter) whose tap launches the deep link, instead of calling open directly. Also pass a real completionHandler and log/reply on failure so the watch can surface it.

[islandbitcoin]

Blocker: this unconditional import breaks the LNFlash-Alt target. Alt's Sources phase compiles only AppDelegate.h/.mm + main.m — zero Swift files — so no Flash-Swift.h is ever generated for it and this #import fails with file-not-found. Guarding with __has_include keeps Alt building (the header only resolves in targets that compile the Swift bridge):

Suggested change

	#import "Flash-Swift.h"
	#if __has_include("Flash-Swift.h")
	#import "Flash-Swift.h"
	#endif

(The cleaner alternative is adding WatchConnectivityBridge.swift/WidgetBridge.swift to the Alt target, but Alt presumably shouldn't ship watch connectivity at all.)

[islandbitcoin]

Same Alt-target break at the call site — WatchConnectivityBridge is undeclared there:

Suggested change

	[WatchConnectivityBridge activateSession];
	#if __has_include("Flash-Swift.h")
	[WatchConnectivityBridge activateSession];
	#endif

Related signing issue: Alt's CODE_SIGN_ENTITLEMENTS points at the same LNFlash/LNFlash.entitlements / LNFlashDebug.entitlements files this PR adds com.apple.security.application-groups (group.com.lnflash) to, so com.flashapp.alt now requires an app-group-capable provisioning profile. Either give Alt its own entitlements files without the app group, or register the capability for its profile.

[islandbitcoin]

Blocker: this appends display-currency prices into USD history, corrupting the chart for non-USD users. The snapshot is priced in the phone-synced display currency (query uses previous.currencyCode), but priceHistory is filled by fetchHistory with USD-only btcPriceListUnauthed points (no currency arg exists). The complication's getTimeline calls only fetch, so for a JMD user (~155× USD) JMD points steadily accumulate in USD history; ContentView reads the store at launch and whenever the history fetch fails, and its only filter is price > 0 — result: a ~+15,000% change badge and a spiked sparkline. The widget copy of this file already removed the append for exactly this reason ("Don't append to history here — the 30D fetch is the authoritative source").

Suggested change

WatchStore.appendHistory(snapshot)

Also worth porting the widget's SharedStore.sanitizeHistory ratio guard into WatchStore.readHistory as defense in depth — the watch currently has no mixed-unit protection at all.

[islandbitcoin]

Self-reload loop: ComplicationProvider.getTimeline calls this same fetch (SETUP.md ticks this file into the complication target), so every complication timeline generation unconditionally requests its own invalidation via reloadComplications() → getTimeline → fetch → repeat. WidgetKit coalesces extension-originated reloads, so in practice this burns the daily refresh budget early and then the complication freezes stale, instead of honoring the .after(20 min) policy.

Suggested change

reloadComplications()

Trigger the reload only from the watch-app context instead (e.g. in ContentView.refreshAll after its fetch completes), so the provider path never self-invalidates.

[islandbitcoin]

Blocker: flash://home opens the Send Bitcoin screen, not Home. There is no home path in the navigation linking config, so it falls through to the pre-existing sendBitcoinDestination: ":payment" catch-all — a whole-widget tap opens the Send screen trying to parse "home" as a payment destination (invalid-destination error, or worse, a real user named home). Same for iOS (FlashWidgetEntryView.swift DeepLink.sendHome) and the watch bridge's home action.

For "just open the app", a plain launch intent is more robust than a deep link here (context.packageManager.getLaunchIntentForPackage(context.packageName) wrapped in the same PendingIntent); alternatively namespace the widget links (see my comment in navigation-container-wrapper.tsx) and add an explicit home mapping.

[islandbitcoin]

These static paths shadow the :payment catch-all — and home isn't mapped at all. React Navigation ranks static segments above param segments regardless of config order, so https://pay.getflash.io/receive (a valid pay link for a user literally named receive — username rules allow it) now opens the local Receive screen instead of the send-to-user flow. Meanwhile the widgets' flash://home has no mapping and falls through to sendBitcoinDestination: ":payment", opening the Send screen with payment="home".

Recommend namespacing the widget quick actions so they can never collide with usernames and the whole family is explicit:

scanningQRCode: "widget/scan",
receiveBitcoin: "widget/receive",

plus updating the three emitters (FlashWidgetProvider.kt, FlashWidgetEntryView.swift DeepLink, WatchConnectivityBridge.handleWatchAction) to flash://widget/..., and either mapping widget/home to Home or using a plain launch intent for the whole-widget tap.

[islandbitcoin]

Float truncates the price. The pipeline is Double end-to-end (JS bridge getDouble, PriceFetcher math) but persistence narrows to 32-bit Float (~7 significant digits). At JMD scale (~1.7e7/BTC) Float spacing is 2, at IDR scale (~1.8e9) it's 128 — and formattedPrice() renders every digit, so the widget shows visibly wrong trailing digits. iOS stores full Double. Store the raw bits in a long instead (keys are new in this PR, so no migration concern):

Suggested change

	context.getSharedPreferences(PREFS, Context.MODE_PRIVATE).edit()
	.putFloat(KEY_PRICE, snapshot.btcPrice.toFloat())
	.putString(KEY_CURRENCY, snapshot.currencyCode)
	.putString(KEY_SYMBOL, snapshot.currencySymbol)
	.putInt(KEY_FRACTION, snapshot.fractionDigits)
	.putFloat(KEY_TIMESTAMP, snapshot.timestamp.toFloat())
	.apply()
	context.getSharedPreferences(PREFS, Context.MODE_PRIVATE).edit()
	.putLong(KEY_PRICE, snapshot.btcPrice.toRawBits())
	.putString(KEY_CURRENCY, snapshot.currencyCode)
	.putString(KEY_SYMBOL, snapshot.currencySymbol)
	.putInt(KEY_FRACTION, snapshot.fractionDigits)
	.putLong(KEY_TIMESTAMP, snapshot.timestamp.toRawBits())
	.apply()

[islandbitcoin]

Matching read side for the Double-bits storage:

Suggested change

	return Snapshot(
	btcPrice = p.getFloat(KEY_PRICE, 0f).toDouble(),
	currencyCode = p.getString(KEY_CURRENCY, "USD") ?: "USD",
	currencySymbol = p.getString(KEY_SYMBOL, "$") ?: "$",
	fractionDigits = p.getInt(KEY_FRACTION, 2),
	timestamp = p.getFloat(KEY_TIMESTAMP, 0f).toDouble(),
	)
	return Snapshot(
	btcPrice = Double.fromBits(p.getLong(KEY_PRICE, 0L)),
	currencyCode = p.getString(KEY_CURRENCY, "USD") ?: "USD",
	currencySymbol = p.getString(KEY_SYMBOL, "$") ?: "$",
	fractionDigits = p.getInt(KEY_FRACTION, 2),
	timestamp = Double.fromBits(p.getLong(KEY_TIMESTAMP, 0L)),
	)

[islandbitcoin]

Duplication cluster (fast-follow, but worth a plan before this ships):

1. This file and FlashWatch Watch App/PriceService.swift are near-identical (~165 lines: same endpoint, char-identical GraphQL strings, same conversion/sampling) and have already diverged inside this PR (append/sanitize/reload behavior). One shared PriceService.swift with multi-target membership — the pattern SETUP.md already uses for WatchStore.swift — with the store injected per target.
2. The prod GraphQL URL is hardcoded here, in the watch copy, and in PriceFetcher.kt, while the app resolves per-instance graphqlUri from app/config/galoy-instances.ts (6 instances). Staging/Test builds will show prod prices in widgets, and a future API host change bricks shipped widgets. The JS sync layer already pushes snapshots natively — push the endpoint too and read it here.
3. The Catmull-Rom sparkline (SmoothLineShape/AreaShape/SmoothPath) is duplicated line-for-line between FlashWidgetEntryView.swift and the watch ContentView.swift — and only the widget side got the sanitizeHistory ratio guard.
4. app/components/watch-receive-sync/index.tsx re-implements the LNURL paycode builder byte-for-byte from app/screens/receive-bitcoin-screen/payment/payment-request.ts (same HRP, limit 1500, same ?lightning= composite) — extract a shared helper so the watch QR can't drift from the Receive screen.

[islandbitcoin]

Pushed 4baafb44 addressing the review:

Blockers — all fixed:

1. Watch quick actions in background — when the app isn't active, the action is stashed (5-min TTL) and surfaced as a local notification; the deep link fires on next activation via a didBecomeActiveNotification observer (no notification-delegate wiring needed, so no conflict with Firebase swizzling). Foreground path now logs open failures.
2. LNFlash-Alt target — __has_include guards around the Swift header import and activateSession call; Alt now signs with its own LNFlashAlt{,Debug}.entitlements (pre-PR content, no app group).
3. Mixed-currency watch history — removed the display-currency appendHistory from fetch, ported the widget's ratio-guard sanitizeHistory into WatchStore.readHistory (self-heals any already-contaminated cache), and removed the dead appendHistory function.
4. Deep links — quick actions namespaced to flash://widget/{scan,receive} (config + all three emitters + SETUP.md); whole-widget tap uses a plain launch intent on Android and unmapped flash://widget/home on iOS, so nothing routes into :payment anymore.

Fast-follows included: complication no longer self-reloads (watch app triggers reloads from refreshAll); Android onUpdate renders the cached snapshot synchronously before fetching; WidgetStore persists Doubles as raw bits; shared getPaycodeQRContent helper extracted (Receive screen + watch QR).

Deliberately deferred (needs Xcode target-membership restructuring, best done in-editor): merging the two PriceService copies / sparkline into shared multi-target files, and pushing the per-instance GraphQL endpoint from JS into the native stores. The hardcoded-prod-endpoint issue stands — suggest a follow-up ticket.

Verification: yarn check-code + full jest (159 passed) locally; :app:compileDebugKotlin compiles; Swift changes parse but this machine has no Xcode — the iOS workspace needs a build on a machine with Xcode before merge (watch scheme + main app + Alt scheme to confirm the entitlements/guard fixes).

[islandbitcoin]

✅ iOS build verified on a machine with Xcode — that was the last open item from the review fixes in 4baafb44. With CI green (all 7 checks) and the native build confirmed, all four review blockers are now fixed and verified; the deferred dedup/endpoint work is tracked in ENG-480. Good to merge from the review's perspective.

(If the build didn't include the LNFlash-Alt scheme specifically, worth one build of that scheme too — it's the target nobody normally builds, and it's what the __has_include guards + new LNFlashAlt{,Debug}.entitlements exist to fix.)