refactor: migrate incrementally to navigation 3

[ovitrif]

Parent: #1113
Depends on: #1114, #1115, and #1116

Goal

Migrate Bitkit from Compose Navigation 2 to Navigation 3 through approachable, separate-concern pull requests, beginning with an isolated onboarding navigator and preserving a runnable, tested app after every merge.

Preparation

• Update Android CLI and install or refresh the official navigation-3 skill before refinement and implementation.
• Use the skill's current migration guidance and primary Android documentation as the implementation contract.
• Reinspect current master after the toolchain/dependency issues land.
• Use closed PR refactor: migrate navigation to nav3 #554 as the coverage inventory for routes, navigator state, entry organization, sheets, transitions, deep links, timed overlays, drawer/tab behavior, QR flows, settings, transfers, widgets, startup/PIN handling, and receive/send in-sheet flows.
• Implement each slice from the settled current baseline with focused review and verification.

Incremental boundary

Navigation 2 remains the root host during the first slice. Its onboarding destination hosts a Navigation 3 NavDisplay with a typed back stack. Completion and cancellation return through explicit callbacks to the legacy root. This provides a complete onboarding vertical slice without coupling it to the whole-app migration.

Ordered pull-request series

PR 1: Navigation 3 foundation and onboarding

• Add mutually compatible stable Navigation 3 dependencies selected at implementation time.
• Add typed onboarding routes, NavBackStack, entry provider, state save/restore, and focused navigator tests.
• Host onboarding NavDisplay behind the existing root boundary.
• Migrate the complete onboarding route sequence and back behavior.
• Preserve completion, terms, wallet creation/import entry, process recreation, and return-to-root behavior.
• Add/update the onboarding journey and Compose/instrumentation coverage.

PR 2: Shared route model and root screen navigation

• Establish the shared typed route hierarchy and repository Navigator contract.
• Migrate root wallet, drawer, tab, settings-entry, and non-sheet screen transitions.
• Preserve deep-link handoff boundaries and restored navigation state.
• Keep remaining legacy destinations reachable through explicit adapters.

PR 3: Sheet scene strategy and in-sheet flows

• Introduce the Navigation 3 scene strategy for Bitkit bottom sheets.
• Migrate receive, send, selectors, suggestions, and nested in-sheet navigation.
• Preserve swipe, back, overlay-tap, transition, amount-retention, and nested-dismiss behavior.
• Keep sheet presentation aligned with the supported design.

PR 4: Lifecycle-driven and external navigation

• Migrate deep links, timed sheets, critical-update routing, startup/PIN behavior, clipboard-triggered navigation, QR handoff, external connections, and notification-driven routes.
• Make lifecycle ownership and one-shot event consumption explicit.
• Add focused tests for restored back stacks and repeated external events.

PR 5: Complete migration and remove legacy navigation

• Migrate remaining settings, transfer, widget, activity, and developer routes from the current codebase/refactor: migrate navigation to nav3 #554 inventory.
• Remove the final Navigation 2 host, adapters, dependencies, route definitions, and obsolete tests.
• Reconcile final navigation guidance in AGENTS.md and .ai/rules/android.md.
• Run the full navigation regression matrix and product journeys.

Each PR owns one concern and can split further when current inspection identifies a smaller independently testable boundary. Record every added slice in this issue before implementation.

Acceptance criteria

• This issue links the refreshed navigation-3 skill version/date and primary Android migration sources.
• A route/surface inventory is reconciled against current master and closed PR refactor: migrate navigation to nav3 #554.
• PR 1 delivers a complete Navigation 3 onboarding vertical slice while Navigation 2 hosts the rest of the app.
• Every intermediate merge leaves migrated and unmigrated routes reachable with correct forward, back, restoration, and deep-link behavior.
• Every PR covers one concern and includes focused unit, Compose, instrumentation, or journey evidence.
• Sheet slices preserve swipe-down, system-back, overlay-tap, nested-flow, transition, and state retention.
• Lifecycle-driven routes consume each external event once and restore safely after process recreation.
• The final slice removes Navigation 2 dependencies, hosts, adapters, routes, and obsolete tests.
• Repository guidance requires the established Navigation 3 patterns.
• just compile, just test, just lint, just build, and affected device/journey checks pass for each slice.
• Final regression covers onboarding, drawer/tabs, wallet screens, settings, send, receive, transfers, sheets, deep links, QR, startup/PIN, timed overlays, widgets, and external events.
• The app installs, launches, restores its back stack, and completes representative E2E flows on supported devices.

References

• Navigation 3
• Closed migration PR #554

[ovitrif]

Follow-up: deep links from #659

The external-contributor PR described in this implementation analysis targets current master and can proceed using the current Navigation 2 architecture. The incremental migration in this issue starts each slice from the then-current master and owns adapting the landed deep-link implementation. #659 carries no Navigation 3 preparation work.

The migration carries these durable artifacts forward:

• The bitkit://screen/<id>[/<arg>][?<arg>=] URI contract, including path arguments, query parameters, and input prefilling.
• The dev-mode gate, route identifiers, denied-route inventory, sheet paths, pending-link replay, and cold/warm intent behavior.
• Contract tests for unique route IDs and well-formed paths, plus the adb-driven deep-link journeys.

The Navigation 3 series owns the integration work:

• Earlier slices preserve the landed deep-link behavior while Navigation 2 remains present.
• PR 4 re-inspects current master and replaces Navigation 2-specific navDeepLink and NavController.handleDeepLink plumbing with URI-to-NavKey matching and explicit back-stack construction.
• The sheet migration reconciles screen and sheet links onto the shared Navigation 3 back stack through the established scene strategy.
• The migration re-evaluates Navigation 2-only exclusions when nested-graph constraints disappear and expands coverage where the Navigation 3 route model supports it safely.
• Every affected slice preserves supported URIs, argument delivery, repeated external-event handling, process restoration, and expected Back behavior.