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.
• Documents the URI shape, the reachable sheet routes and every exclusion in docs/deeplinks.md.
• 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.

[greptile-apps]

Greptile Summary

Adds development-mode deep links for root navigation destinations and manually selected sheet routes.

• Derives root-screen URI patterns from serializable route class names and arguments.
• Queues incoming screen links until Compose navigation is available, then routes them to the root graph or sheet host.
• Documents supported and excluded links and adds unit tests and emulator journeys.

Confidence Score: 4/5

The backup-success and hardware mid-flow links should be removed or made to establish their required state before this PR is merged.

Direct sheet entry can report a backup that never occurred or render hardware searching and paired states without starting discovery or establishing a paired device.

Files Needing Attention: app/src/main/java/to/bitkit/ui/utils/SheetDeepLinks.kt

Important Files Changed

Filename	Overview
app/src/main/java/to/bitkit/ui/utils/SheetDeepLinks.kt	Registers direct sheet entry points, including backup and hardware flow states that require work or initialization performed by earlier steps.
app/src/main/java/to/bitkit/ui/utils/ScreenDeepLinks.kt	Derives root-route deep links and excludes an explicit set of sensitive routes.
app/src/main/java/to/bitkit/ui/ContentView.kt	Replays queued links through either the sheet host or root NavController.
app/src/main/java/to/bitkit/viewmodels/AppViewModel.kt	Gates screen links on development mode and stores one pending URI for UI consumption.
app/src/main/java/to/bitkit/ui/utils/Transitions.kt	Makes generated screen links the default for root composable and nested-graph registrations.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["bitkit://screen/... intent"] --> B["AppViewModel checks dev mode"]
  B -->|disabled| C["Ignore link"]
  B -->|enabled| D["pendingScreenDeepLink"]
  D --> E{"SheetDeepLinks match?"}
  E -->|yes| F["showSheet with nested start route"]
  E -->|no| G["NavController.handleDeepLink"]

Loading

_{Reviews (1): Last reviewed commit: "feat: add deep links to bottom sheet scr..." | Re-trigger Greptile}

[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]

backup/show-mnemonic is denied by SheetDeepLinks, but it reaches this branch and hides the active backup intro before handleDeepLink reports the URI as unhandled. The new sheet journey therefore returns to the wallet overview instead of leaving the visible screen unchanged; any rejected screen URI can similarly dismiss the current sheet. Could we confirm that the URI matches a root destination before hiding the sheet and add regression coverage for a denied URI while a sheet is open?

[guzino]

Reordered so the sheet closes only after the link has matched, which leaves a rejected URI with the visible screen untouched. ContentViewTest covers a rejected link arriving while a sheet is open.

Resolved in 4362cc9

[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]

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]

Changelog fragments should describe public-facing capabilities. This entry belongs here because people can build the app themselves and provide their own Firebase configuration when needed. Could we remove the internal so QA and bug reports... framing and use: “Developers running their own build can now open supported screens directly with bitkit://screen/... links while dev mode is enabled”?

[guzino]

Rewritten to the wording you suggested.

Resolved in 4362cc9

[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.