feat(devices): pairing-UX scaffold (Phase 2)

Lays the groundwork for device families that require a one-time
physical pairing action (Nanoleaf hold-power-button, Tuya local-key
extraction, Twinkly network-setup mode, Hue link-button). No driver
uses it yet -- Nanoleaf will be the first concrete consumer.

Phase 2 as originally written had three bullets; only this one was
genuinely missing work. The other two (generic NetworkDiscoveryService
fan-out, unified scan-network UI) were already solved at the route
level by the existing /api/v1/devices/discover handler running all
providers in parallel via asyncio.gather(return_exceptions=True).
Marked WONTDO in TODO.md with rationale.

Backend:
- LEDDeviceProvider gains an async pair_device(url) -> dict method.
  Default raises NotImplementedError so missing implementations on a
  requires_pairing provider fail loud at request time.
- New PairingNotReady exception, distinct from generic errors so the
  route handler can return 409 (user must perform the physical action,
  retry possible) instead of 500.
- POST /api/v1/devices/pair endpoint with PairDeviceRequest /
  PairDeviceResponse schemas. Status-code mapping:
    200 -> paired, fields returned for the subsequent create payload
    400 -> unknown device type, or type doesn't support pairing
    409 -> PairingNotReady (retryable from the UI)
    422 -> invalid URL / device configuration (ValueError)
    502 -> transport / network failure (other exceptions)
    500 -> provider returned a non-dict (defensive)
- 8 route tests register a stub provider and exercise every
  status-code path.

Frontend:
- New modals/pair-device.html with five state blocks (idle / pairing
  / not_ready / success / failed) toggled via data-pair-state, plus
  a 30-second SVG progress ring with monospace countdown.
- New features/pairing-flow.ts exposing
  runPairingFlow({deviceType, url, instructionsKey?}) ->
  Promise<{fields: Record<string, unknown>>. Wires the modal to the
  pair endpoint, maps response codes to UI states, AbortControllers
  in-flight fetches on cancel. Exports a PairingCancelled sentinel
  error class.
- Generic pairing.* i18n keys in en/ru/zh. Drivers will add their own
  device.<type>.pair.instructions key that overrides the default.

Design decisions (per frontend-design skill):
- Single SVG ring + centered countdown (HomeKit-style)
- Instructions stay visible during pairing, dimmed to 60% via :has()
- Success state held 450 ms before auto-dismiss
- Cancel-X in the footer; primary action lives in the state block
- prefers-reduced-motion disables pulse/fade/ring transitions

Note: the components.css diff includes a pre-existing MiniSelect block
from the user's parallel work; pairing-specific styles are the second
hunk (lines ~1628+).

TODO.md

@@ -710,9 +710,24 @@ Philips' UDP-local budget tier. Port 38899 JSON UDP.
 
 After phase 1 the codebase will have 3 fresh examples of "ping the LAN, listen for replies, present a list". Factor that out into a generic discovery scaffold + a "first-run pairing" UX component before adding Tuya/Govee/etc., which each need a one-time pairing dance.
 
-- [ ] Generic `NetworkDiscoveryService` that fan-outs mDNS + SSDP + UDP-broadcast probes in parallel
-- [ ] Unified "scan network for devices" UI affordance instead of per-type buttons
-- [ ] Reusable "pair device" component (consent button, countdown, retry)
+- [WONTDO] Generic `NetworkDiscoveryService` — the existing
+  `/api/v1/devices/discover` route already runs all providers in parallel
+  via `asyncio.gather(return_exceptions=True)`. Extracting it would not
+  unlock anything; revisit only if discovery cadence/dedup becomes a
+  real complaint.
+- [WONTDO] Unified scan UI — already exists; one "Scan network" button
+  triggers the cross-provider fan-out.
+- [x] **Reusable pair-device scaffold** (the actually-needed piece).
+      Backend: `LEDDeviceProvider.pair_device(url)` abstract method with
+      `PairingNotReady` sentinel; `POST /api/v1/devices/pair` endpoint
+      with status-code mapping (200/400/409/422/502); 8 route tests
+      covering every outcome. Frontend: `templates/modals/pair-device.html`
+      five-state modal (idle / pairing / not-ready / success / failed)
+      with a 30-second SVG progress ring; reusable
+      `static/js/features/pairing-flow.ts` exposing
+      `runPairingFlow({deviceType, url}) → Promise<{fields}>` with
+      `PairingCancelled` sentinel; locale strings in en/ru/zh. No driver
+      uses it yet — Nanoleaf will be the first concrete consumer.
 
 ### Phase 3 — Big aggregator unlocks