feat: device pinning — stream from a chosen pair (SpecificDeviceSelector)

[gdelataillade]

Stacked on #12 (feat/get-devices-api) — review/merge that first; this PR's diff is pinning-only.

Summary

Step 2 of the device-selection work: startStreamSession(deviceId) now streams from a specific paired pair instead of whatever the shared AutoDeviceSelector happens to pick. Pass a WearableDevice.id (from the getDevices() added in #12) to pin it via the SDK's SpecificDeviceSelector; pass null to auto-select. This fixes the "connects to a random pair" problem with two pairs.

How it works

• The pin is state (pinnedDeviceId) applied at startStreamSession, routed through a single pin-aware selector factory used at every construction site — so the load-bearing blind-rebuild recovery path keeps the pin instead of silently dropping it.
• Both platforms keep one shared selector (the SpecificDeviceSelector when pinned), so the existing availability-watchdog / thermal / getDevices().isActive stack stays correct — we never run a specific selector beside the auto one.
• A different deviceId while a stream is already active returns STREAM_ACTIVE (PlatformException) rather than silently returning the old device's texture — stop first.

Notable details

• Android Device exposes no identifier, so an AutoDeviceSelector filter can't match by id — SpecificDeviceSelector(DeviceIdentifier) is the only id-based option, hence the uniform approach.
• Android deferred init: selector is built through a nullable holder + accessor (never before Wearables.initialize()), and startStreamSession guards with NOT_INITIALIZED before any selector/texture work.
• On a pin change: tear down the session, rebuild the selector, relaunch the iOS watchdog, and restartMonitoring(force: true) on both event handlers (added a force path on Android) so nothing keeps observing the old selector.
• API: the positional deviceUUID param on startStreamSession/stopStreamSession/capturePhoto is renamed to deviceId (positional → non-breaking).

Example app

Tap a pair (or Automatic) in the Paired-devices sheet to choose which one streams next (takes effect on the next Start, per the chosen UX). Selection is the sole source of truth (null = Automatic); the mock is pinned explicitly on pair and cleared on unpair only when the selection still points at it.

Verification

• dart analyze clean (root + example); flutter test green in both (startStreamSession wire forwarding / STREAM_ACTIVE; provider selection policy incl. unpair-preserves-real-pair).
• flutter build apk ✓ and flutter build ios --no-codesign ✓.
• Pending (needs hardware — yours): the two-real-pairs manual checks from the plan — pick B → Start → confirm B streams; switch via Stop→pick A→Start; STREAM_ACTIVE on switch-while-streaming; pinned-device disconnect/reconnect recovery.

🤖 Generated with Claude Code

[gdelataillade]

Addressed all three review findings in 8b99d62:

• [P1] Stopped streams treated as active — the conflict guard now checks the actual Stream state (iOS streamSession.state, Android stream.state.value). A non-nil but STOPPED/STOPPING/CLOSED stream is treated as inactive: it's torn down (teardownStreamOnly) and recreated, so restarting the same device no longer returns a stale texture and switching no longer false-positives STREAM_ACTIVE.
• [P1] Concurrent starts can hang Android — added an in-flight guard (isStartingSession / startInProgress) that rejects a second start with STREAM_ACTIVE while one is in progress, so a second start can't tear down the first's in-flight session. Belt-and-suspenders: Android ensureSessionStarted now awaits STARTED || STOPPED and returns null on STOPPED, so a session torn down mid-start can't hang the awaiter.
• [P2] Specific selector can't monitor iOS availability — confirmed via Meta's docs that iOS SpecificDeviceSelector.activeDeviceStream() emits once then completes. iOS now pins via a filtered AutoDeviceSelector (filter: { $0.identifier == id }) instead, which keeps a continuous stream that emits nil when the pinned device disconnects — so the availability watchdog and the active-device/thermal handlers keep working. The iOS selector field + handler provider types reverted from any DeviceSelector back to concrete AutoDeviceSelector.

Correction to the PR description: the approach is no longer a uniform SpecificDeviceSelector. iOS uses a filtered AutoDeviceSelector (continuous stream); Android keeps SpecificDeviceSelector (its Device exposes no identifier to filter on, and its activeDeviceFlow() wasn't flagged for the emit-once behavior).

Re-verified: dart analyze clean (root + example), flutter test green in both (19 + 4), flutter build apk ✓ and flutter build ios --no-codesign ✓. The two-real-pairs + disconnect-recovery manual checks still need hardware.

[gdelataillade]

Both remaining findings addressed in 5fd8249:

• [P1] New selection can't escape a disconnected pin — the example's Start button is now gated on a new StreamSessionProvider.canStartSelected, which reflects the selected pair's link state (from the last getDevices() snapshot) rather than the shared selector's activeDevice. In Automatic mode it still mirrors hasActiveDevice. So with a pin to a now-disconnected pair, you can pick a connected pair and Start becomes enabled — the native selector re-pins on startStreamSession. Added a provider test (canStartSelected reflects the selected pair connectivity).
• [P3] Selector doc — agent/cursor/rules/dat-streaming.mdc no longer says pinning always uses SpecificDeviceSelector; it now notes SpecificDeviceSelector on Android and a filtered AutoDeviceSelector on iOS, matching the CHANGELOG.

No native changes this round, so the prior green flutter build apk / build ios still hold. dart analyze clean, example tests now 5 (root 19) — all green.