feat: add deep links to every screen

[guzino]

Fixes #659
Refs #1118
Refs #1126

This PR adds a bitkit://screen/... URI for every screen in the app, bottom sheets included, gated on dev mode.

Description

A destination declares whether it may be entered directly, in the model that defines it. 88 root routes are Routes.DeepLinkable and 15 are Routes.InternalOnly, and deepLinkableComposable accepts only the former, so a new screen has to make the choice rather than inherit one. ScreenDeepLinks adapts the URI and nothing else: it derives the id by kebab-casing the class name, so Routes.RgsServer is reachable at bitkit://screen/rgs-server. Arguments without a default become path segments, arguments with a default become query parameters.

Bottom sheets needed a second mechanism. They are not in the root graph: they are Sheet values rendered by SheetHost, each carrying the start route of its own nested NavHost, so NavController.handleDeepLink cannot reach them. Each sealed route family declares DeepLinkStart or InternalOnly on its states and owns a fromDeepLink lookup, and SheetDeepLinks picks the family and wraps the result. Ids derive from class names throughout, so bitkit://screen/widgets/price-edit comes from Sheet.Widgets plus WidgetsRoute.PriceEdit.

• Registers 38 sheet paths across send, receive, backup, widgets, hardware and the three sheets with no nested graph.
• Gates screen links on isDevModeEnabled in AppViewModel.handleDeeplinkIntent, and holds one until the wallet is loaded; ContentView replays it.
• Detaches the screen URI from the Activity intent in MainActivity once the gated pipeline has read it, so graph creation cannot navigate outside the dev-mode gate.
• Classifies the recovery phrase, auth, transfer and LNURL destinations as internal, so they yield no link at all. Links navigate and prefill only, and never send, broadcast or change a setting without the usual confirmation.
• Leaves payment URIs (bitcoin:, lightning:, lnurl*) on the scanner decode path, untouched.
• Dismisses an open sheet only once a root-screen URI has matched, so a rejected link leaves the visible screen alone.
• Removes docs/deeplinks.md. The route markers, deepLinkableComposable, the sheet families' fromDeepLink and the unit tests are the source of truth, and a parallel doc drifted three times during review.
• Keeps the 25 flow-only sheet states internal. None is tap-reachable, so none is a user-facing defect. Direct support for the late transfer screens is tracked in feat: deep link the late transfer screens #1126.

Not every nested state is a valid start destination. I fired all 51 against an emulator, then re-ran each rejected one in isolation against logcat. The states left internal fall into three groups:

• SendRoute.FeeRate and FeeCustom sit inside navigationWithDefaultTransitions<SendRoute.FeeNav>. A nested graph's child cannot be a NavHost start destination, so both throw IllegalStateException: Cannot find startDestination ... from NavGraph. send/fee-nav resolves but renders only the screen title.
• send/quick-pay throws on requireNotNull(quickPayData) (SendSheet.kt:309). send/confirm and the four receive confirm/liquidity routes do not crash but render empty or zero-amount screens. send/confirm offers "Swipe To Pay" over a payment that was never built.
• backup/success reports a backup that never ran, and its OK button persists backupVerified = true (BackupNavSheetViewModel.onSuccessContinue). backup/warning is one tap upstream of the same write. hardware/searching waits forever because discovery starts from the intro's continue action, and hardware/paired claims a paired device over default state.

Tests pin the classification, and a final sweep confirmed the rejected paths no-op with the wallet overview intact and zero fatal exceptions.

Preview

N/A

QA Notes

Dev mode is on by default on debug builds (Settings ▸ Advanced ▸ Dev Settings). The app must be past onboarding.

Manual Tests

• 1. adb shell am start -a android.intent.action.VIEW -d "bitkit://screen/settings" to.bitkit.dev → Settings opens. A mistyped id still resolves MainActivity, because the manifest accepts every bitkit: URI by scheme, so check logcat for Unhandled screen deeplink rather than relying on -W.
• 2. Deep-linked screen → Back: returns to the wallet overview, not the launcher.
• 3. bitkit://screen/send → Send sheet on the recipient picker. bitkit://screen/widgets/price-edit → Bitcoin Price editor.
• 4. bitkit://screen/recovery-mnemonic and bitkit://screen/backup/show-mnemonic → screen unchanged, recovery phrase never shown, logcat carries Unhandled screen deeplink.
• 5. bitkit://screen/send/fee-rate and bitkit://screen/backup/success → screen unchanged, no crash, and backupVerified is untouched.
• 6. PIN screen up → fire any screen link: navigates behind the PIN, which is still required before anything is visible.
• 7. Dev mode off → any bitkit://screen/... link is ignored, on warm start and on cold start. Settings ▸ Support, tap Version five times to toggle.
• 8. regression: scan a bitcoin: / lightning: / lnurl URI → still decodes through the scanner path.

Automated Checks

• Unit tests in ScreenDeepLinksTest.kt: id derivation, path vs query argument placement, and that every route declares its eligibility.
• Unit tests in SheetDeepLinksTest.kt: bare-id defaults, sub-route selection, case-insensitive lookup, ids derived from the Sheet class names, and that every state marked as a start is registered in its family lookup.
• Instrumented ScreenDeepLinkDetachmentTest: graph creation stays on Home after detachment, the captured URI reaches Settings only through the replay, and a denied route is not matched.
• Two journeys under journeys/deeplinks/, including cold-start cases for dev mode off and on.
• Fired all 38 sheet paths and the screen links against an API 33 emulator and confirmed each renders. The rejected paths no-op without crashing.
• Local: just compile, just test, just lint all pass, no new detekt findings.

[ovitrif]

Thanks for addressing the existing backup and hardware findings; I confirmed both fixes on 511250c.

I found three blocking issues: cold-start links bypass the dev-mode gate, bitkit://screen/recovery-mode is consumed by the legacy parser before the gate, and external-confirm can reach invalid fresh state and crash. I also left two non-blocking corrections for Home registration and the adb -W guidance.

[ovitrif]

Thanks for addressing the earlier findings. Three blocking issues remain:

• Cold-start coverage is missing at the Activity/NavHost boundary.
• Late transfer destinations allow entry without the flow state they require.
• Root-screen links route behind an active sheet.

[ovitrif]

One blocking navigation regression remains: rejected screen links dismiss an active sheet before route handling determines that the URI is invalid.

[ovitrif]

The deep-link implementation currently splits navigation policy across the route models and parallel registries, so I came up with 4 required corrections to keep direct entry safe and make the route hierarchy the single source of truth, and fix the changelog:

• A denied root-screen link dismisses an active sheet before rejection, so rejected input changes the visible flow.
• Root-screen eligibility has a second owner in ScreenDeepLinks.DENIED, so new routes become reachable without an explicit decision and every route change must synchronize a parallel policy.
• SheetDeepLinks.SHEETS correctly fails closed while duplicating which nested states may start a flow outside the sealed route families that define them.
• The changelog is incorrect because it describes an internal QA workflow rather than the public developer capability available to people running their own builds.

[ovitrif]

ScreenDeepLinks becomes a second owner of the route model because DENIED duplicates direct-entry eligibility outside the sealed Routes hierarchy. Every future destination change therefore needs to synchronize the route hierarchy, navigation graph, this registry, its tests, the documentation, and the journeys.

That duplication does not guard future changes:

• A new route becomes externally reachable automatically because composableWithDefaultTransitions calls linksFor(T::class) by default.
• A route that should remain internal can remain externally reachable because its author must also know to add it to DENIED.
• The every-route test does not enforce an explicit eligibility decision because every unlisted route is accepted as deep-linkable.

The navigation model should follow the same ownership principle we use from DDD: behavior and invariants live with the model that owns them. Within this navigation boundary, the sealed Routes hierarchy should own whether a destination may be entered directly, while ScreenDeepLinks only adapts external URIs.

The sealed hierarchy should make that choice explicit:

sealed interface Routes {
    sealed interface DeepLinkable : Routes
    sealed interface InternalOnly : Routes

    @Serializable
    data object Settings : DeepLinkable

    @Serializable
    data object SpendingConfirm : InternalOnly
}

The graph helper should then accept only Routes.DeepLinkable, making every new destination declare its policy in the same model that defines it. Could we move root-screen eligibility into the sealed Routes hierarchy and constrain the graph helper to Routes.DeepLinkable, leaving ScreenDeepLinks responsible only for URI adaptation?

[guzino]

Moved eligibility into the sealed hierarchy, so DENIED is gone.

I could not constrain the shared helper: it also registers the sheet and startup families, so 73 of its 171 call sites are not Routes, and a same-name overload clashes. Root screens use a separate deepLinkableComposable.

Resolved in c4f4bca

[ovitrif]

Confirmed fixed on c755819: DENIED is gone and root-screen eligibility now lives on Routes.DeepLinkable / Routes.InternalOnly with deepLinkableComposable registration, though ExternalConnection still needs that wiring.

[ovitrif]

SheetDeepLinks correctly fails closed because SHEETS is a positive allowlist. The maintenance defect is that this object becomes a second catalog of which nested states may safely start a flow, separate from the sealed SendRoute, ReceiveRoute, BackupRoute, WidgetsRoute, and HardwareRoute families that define those states.

Future flow changes therefore need synchronized maintenance:

• A startable state needs to be declared in its route family and registered in SHEETS.
• Reclassifying a flow-only state therefore changes this catalog and its parallel tests instead of one route contract.
• The route declaration does not communicate whether the state is a valid independent entry point.

The nested navigation models should follow the same DDD ownership principle: each sealed route family owns the invariant that determines whether a state can start independently, while SheetDeepLinks only adapts the external URI.

Each sealed route family should make that choice explicit and own its lookup:

sealed interface SendRoute {
    sealed interface DeepLinkStart : SendRoute
    sealed interface InternalOnly : SendRoute

    @Serializable
    data object Recipient : DeepLinkStart

    @Serializable
    data object Confirm : InternalOnly

    companion object {
        fun fromDeepLink(path: String): DeepLinkStart? = TODO()
    }
}

SheetDeepLinks should keep the standalone Sheet entries it directly owns. For nested flows, it should select the sheet family, delegate the child path to that family’s route-owned lookup, and wrap the eligible state in the corresponding Sheet. Could we move nested sheet-entry eligibility and lookup into the existing sealed route families, leaving SheetDeepLinks as the family and standalone URI adapter?

[guzino]

Moved this into the route families too. Each now declares DeepLinkStart or InternalOnly and owns its fromDeepLink lookup, so SheetDeepLinks only picks the family and wraps the result. A state marked as a start but missing from its lookup now fails a test.

Resolved in 0e0a16b

[ovitrif]

Confirmed fixed on c755819: sheet families now own DeepLinkStart / fromDeepLink, and SheetDeepLinks only selects the family and wraps the result.

[guzino]

The red e2e-status is not from this branch. e2e-tests-staging - pubky_paykit fails the same four contact specs on ContactViewName here and on #1123, which touches only channel-details time formatting. My #1111 passed that job on 29 Jul and ContactDetailScreen has not changed since May, so the break is on master or in the staging env rather than in either PR.

The rest is green: build, build-local, build-staging, detekt, and both local e2e specs.

[ovitrif]

Thanks for addressing the earlier findings. One blocking issue and one docs cleanup remain:

• ExternalConnection is still Routes.DeepLinkable but registered with composableWithDefaultTransitions, so bitkit://screen/external-connection lost its Nav deep link after that helper stopped auto-registering links.
• docs/deeplinks.md no longer matches the fail-closed route-owned model and should be removed rather than kept as a second source of truth for this developer-oriented feature.

PS. We can ignore the red e2e failures, it's caused by a premature merge of a PR in the e2e repo targeting paykit-related PRs that are not yet into master. Classic PR stacks issues 🙃 .

[ovitrif]

ExternalConnection is marked Routes.DeepLinkable, but its NavHost registration still uses composableWithDefaultTransitions, which no longer attaches screen deep links by default. Before the ownership migration this URI was reachable; now bitkit://screen/external-connection is unhandled even though the route model says it may be entered directly. Could we register it with deepLinkableComposable like the other DeepLinkable leaves under nested graphs?

[guzino]

Good catch, that one was imported bare as ExternalConnection so my sweep to the new helper missed it. Registered with deepLinkableComposable now and the URI opens Manual Setup again on device. The other 15 non-linking registrations are exactly the InternalOnly routes.

Resolved in ce7f8a8

[ovitrif]

This ownership note is right, but the rest of docs/deeplinks.md still contradicts the fail-closed model (auto-registration via composableWithDefaultTransitions, hand-maintained SheetDeepLinks entries). For this developer-oriented feature the durable source of truth is the route markers, deepLinkableComposable, sheet-family DeepLinkStart / fromDeepLink, and the unit tests, so a long parallel doc will keep drifting. Could we delete docs/deeplinks.md (or shrink it to a short pointer to those code/tests) instead of maintaining it as a second catalog?

[guzino]

Deleted it. The markers, deepLinkableComposable, the family lookups and the unit tests are the source of truth, and that doc drifted three times during this review alone. The journeys stay since they are executable.

Resolved in ce7f8a8