Expose navigation handlers as @_spi(Testing) for unit tests

[Sajjon]

Summary

• Adds @_spi(Testing) public internal(set) var navigationHandler and modalNavigationHandler to NanoViewController<View> so unit tests can drive coordinator routing without going through the view-model's Combine pipeline (no UIKit taps, no text entry, no runloop drains).
• subscribeToNavigation / subscribeToModalNavigation stash the same closure the Combine sink uses on the matching hook before installing the subscription. Zero production-path behaviour change.
• Heavy DocC on both properties (rationale, worked example, trade-off, visibility), and a new "Testing your coordinators" section in the README. Example coordinator (OnboardingCoordinator in SignUpDemo) gains a doc-comment snippet showing the consumer-side usage.

Why

Coordinators register routing logic as a trailing closure to push(...) / modallyPresent(...):

push(scene: PrepareScene.self, viewModel: vm) { [weak self] step in
    switch step {
    case .cancel:              self?.finish()
    case let .submit(payment): self?.toReviewPayment(payment)
    }
}

That closure is only invokable through NVC's Combine subscription on scene.navigation. Tests that want to assert "when .submit fires, ReviewScene is pushed" otherwise have to drive the full view → view-model → Combine pipeline through real UIKit (tap, setText, drainRunLoop) just to reach the switch statement. For coordinator routing assertions, that's an expensive and brittle way to test mechanical wiring.

With the SPI hook, consumers do:

@_spi(Testing) import NanoViewControllerController

prepare.navigationHandler?(.submit(payment))
XCTAssertTrue(nav.viewControllers.last is ReviewScene)

Visibility

@_spi(Testing) public internal(set) — production callers see the property as internal (i.e. invisible across module boundaries) unless they opt in with @_spi(Testing) import. NVC writes through the internal(set); consumers can only read.

Trade-off

Driving the SPI handler directly does not assert that the ViewModel's emitted step actually reaches the coordinator's subscription — only that the handler routes correctly once invoked. The Combine wiring is identical across every push(...) / modallyPresent(...) call, so a single happy-path UI-driven test (or simply observing that the scene appears on the stack after start()) covers it. Documented in the README + property docstrings so consumers can make the call for their own test pyramid.

Test plan

• just test — 28 tests pass (24 prior + 4 new in NavigationHandlerSPITests).
• just example-build — SignUpDemo still builds with the added doc comment on OnboardingCoordinator.
• Pre-commit hook: typos, swiftformat, swiftlint, full unit suite — all green.
• Manual smoke: confirmed scene.navigationHandler is nil for a controller that hasn't been pushed/presented (default state), set after push, and routes through the same closure the Combine sink fires.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.43%. Comparing base (6486ca4) to head (88c8178).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #12   +/-   ##
=======================================
  Coverage   97.42%   97.43%           
=======================================
  Files          39       39           
  Lines        1166     1168    +2     
=======================================
+ Hits         1136     1138    +2     
  Misses         30       30           

Files with missing lines	Coverage Δ
...inating+NanoViewController+NavigationHelpers.swift	100.00% <100.00%> (ø)
...oViewControllerController/NanoViewController.swift	98.06% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR exposes SPI-only navigation handler hooks on NanoViewController so coordinator routing can be unit-tested without driving the full ViewModel/Combine/UI pipeline.

Changes:

• Adds navigationHandler and modalNavigationHandler SPI properties to NanoViewController.
• Stores registered push/modal routing closures on those hooks during navigation subscription setup.
• Adds tests and documentation showing direct invocation of the SPI hooks.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Sources/NanoViewControllerController/NanoViewController.swift	Adds SPI hook properties and DocC explaining intended test usage.
Sources/NanoViewControllerController/Coordinating+NanoViewController+NavigationHelpers.swift	Assigns routing closures to the new SPI hooks before subscribing to navigation publishers.
Tests/NanoViewControllerControllerTests/NavigationHandlerSPITests.swift	Adds unit tests for push and modal SPI handler behavior.
README.md	Documents coordinator testing with SPI navigation handlers.
Examples/SignUpDemo/Sources/Onboarding/OnboardingCoordinator.swift	Adds example documentation for testing coordinator routing.

Comments suppressed due to low confidence (1)

Sources/NanoViewControllerController/Coordinating+NanoViewController+NavigationHelpers.swift:44

• When a scene instance that was previously pushed is later reused with a modal-style helper, the old navigationHandler remains set alongside the new modal hook. Clear scene.navigationHandler here so the SPI properties stay mutually exclusive and cannot expose stale routing closures.

        scene.modalNavigationHandler = handler

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.