feat(app): Universal Links for roadflare.app share pages (#63)

[variablefate]

Closes #63.

Summary

Tap https://roadflare.app/share/d/<npub> or /share/r/<npub> on a
device with RoadFlare installed → app opens with the Add Driver sheet
pre-filled. Falls back to the existing share page (with App Store CTA)
when the app isn't installed — the long-term primary share UX, replacing
the custom roadflared: scheme from PR #66 as the marketing-link path
once the AASA file ships.

Architecture

This is the deferred Universal Links work anticipated by ADR-0012
("the AppState.handleIncomingURL plumbing is reusable when Universal
Links land"). No new ADR — the routing pattern is the same one the ADR
documents, just with a second SwiftUI scene modifier feeding into it.

Routing pattern: .onContinueUserActivity → AppState.handleIncomingUserActivity → existing handleIncomingURL → existing parser → existing pendingDriverDeepLink → existing DriversTab observer → existing AddDriverSheet(prefill:).

Symmetric with the .onOpenURL modifier added in PR #66. The
DriverQRCodeParser.parseURLOrEmbeddedNpub arm already accepts the
https://roadflare.app/share/... URL shape, so this PR is purely
routing-layer wiring.

What's in the diff

File	Change
RoadFlare/RoadFlare/RoadFlare.entitlements	Add applinks:roadflare.app alongside the existing webcredentials: entry
RoadFlare/RoadFlare/RoadFlareApp.swift	Add .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) modifier mirroring .onOpenURL
RoadFlare/RoadFlareCore/ViewModels/AppState.swift	Add handleIncomingUserActivity(_ activity: NSUserActivity) — thin wrapper that extracts webpageURL and routes through handleIncomingURL
RoadFlare/RoadFlareTests/AppState/HandleIncomingURLTests.swift	4 new Swift Testing cases

Total: 4 files, 91 insertions, 0 deletions. All additive — no existing signatures change. No parser changes; no view changes; no SDK changes.

⚠️ AASA prerequisite — required for production

The Associated Domains entitlement is only half of Universal Links.
Apple's CDN must be able to fetch a valid apple-app-site-association
file from https://roadflare.app/.well-known/apple-app-site-association
or this PR is a no-op in production.

The site work is tracked separately at roadflare-site#4 (related draft). The AASA JSON should look like:

{
  \"applinks\": {
    \"details\": [
      {
        \"appIDs\": [\"6Y98438M9X.com.roadflare.RoadFlare\"],
        \"components\": [
          { \"/\": \"/share/d/*\", \"comment\": \"Driver profile share\" },
          { \"/\": \"/share/r/*\", \"comment\": \"Rider profile share\" }
        ]
      }
    ]
  },
  \"webcredentials\": {
    \"apps\": [\"6Y98438M9X.com.roadflare.RoadFlare\"]
  }
}

Team ID 6Y98438M9X and Bundle ID com.roadflare.RoadFlare confirmed against RoadFlare.xcodeproj/project.pbxproj. The webcredentials section preserves the existing Sign in with Apple Passwords integration.

Notes for shipping:

• Must be served with Content-Type: application/json (GitHub Pages does this by default for .well-known/ static files).
• Apple's CDN caches AASA aggressively. New installs pull fresh; existing installs may need Settings → Developer → Associated Domains Development to re-fetch during testing.
• HTTPS is required (it is — roadflare.app is HTTPS-only).

Tests

4 new tests in HandleIncomingURLTests:

• universalLinkDriverShareRoutesToDriversTab — https://roadflare.app/share/d/<npub>?name=... populates pendingDriverDeepLink with the parsed npub + display name, switches selectedTab to drivers
• universalLinkRiderShareRoutesToDriversTab — /share/r/<npub> goes through the same parser path (parser is segment-agnostic; existing DriverLookupDraftTests confirms this is consistent with the rest of the codebase)
• userActivityWithoutWebpageURLIsDropped — NSUserActivity without a webpageURL is a no-op
• universalLinkUnknownPathIsDropped — https://roadflare.app/about (no embedded npub) is dropped silently

The tests construct synthetic NSUserActivity instances with the browsing-web type and exercise the AppState entry point directly. The SwiftUI .onContinueUserActivity modifier itself is a one-liner that just calls appState.handleIncomingUserActivity(activity) and isn't unit-testable without a host app + simulator, but it's covered by the manual test plan below.

Verification

xcodebuild -scheme RoadFlare -destination 'platform=iOS Simulator,name=iPhone 17,OS=latest' build
** BUILD SUCCEEDED **

xcodebuild -scheme RoadFlareTests -destination 'platform=iOS Simulator,name=iPhone 17,OS=latest' -parallel-testing-enabled NO test
** TEST SUCCEEDED **
Test run with 295 tests in 35 suites passed

HandleIncomingURLTests itself: 11 tests passed (7 pre-existing + 4 new).

Manual test checklist (run after merge + AASA is live)

• Confirm AASA fetch: curl -i https://roadflare.app/.well-known/apple-app-site-association returns 200 with Content-Type: application/json and the JSON above
• Install fresh App Store build (delete TestFlight first if installed)
• Long-press a https://roadflare.app/share/d/npub1... link in Messages → "Open in RoadFlare" option appears
• Tap the link → app opens, Drivers tab selected, Add Driver sheet pre-filled with that npub
• Repeat the cold-start case (force-quit between attempts) — the AppState.pendingDriverDeepLink + DriversTab .onChange(of:initial:) path from ADR-0012 handles this
• Tap a https://roadflare.app/about link → opens in Safari (no embedded npub, AASA components filter doesn't claim it)
• Existing roadflared:npub1... flow from PR feat(app): register roadflared: URL scheme for driver-share deep links #66 still works unchanged

Two-app partitioning

Same partitioning notes from PR #66 apply: rider shares (/share/r/*) currently route to the rider app's Add Driver sheet (consistent with existing parser + DriverLookupDraft behavior). Once a dedicated iOS driver app exists, the AASA details array can be split per app — the apple-app-site-association format supports multiple appID entries.

🤖 Generated with Claude Code