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
+- [WONTDO] Generic `NetworkDiscoveryService` — the existing
-- [ ] Unified "scan network for devices" UI affordance instead of per-type buttons
+  `/api/v1/devices/discover` route already runs all providers in parallel
-- [ ] Reusable "pair device" component (consent button, countdown, retry)
+  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
 

server/src/ledgrab/api/routes/devices.py

@@ -5,6 +5,7 @@ from fastapi import APIRouter, HTTPException, Depends, Query, WebSocket, WebSock
 
 from ledgrab.api.auth import AuthRequired
 from ledgrab.core.devices.led_client import (
+    PairingNotReady,
     get_all_providers,
     get_device_capabilities,
     get_provider,
@@ -26,6 +27,8 @@ from ledgrab.api.schemas.devices import (
     DiscoverDevicesResponse,
     OpenRGBZoneResponse,
     OpenRGBZonesResponse,
+    PairDeviceRequest,
+    PairDeviceResponse,
     PowerRequest,
 )
 from ledgrab.core.processing.processor_manager import ProcessorManager
@@ -282,6 +285,72 @@ async def create_device(
         raise HTTPException(status_code=500, detail="Internal server error")
 
 
+@router.post(
+    "/api/v1/devices/pair",
+    response_model=PairDeviceResponse,
+    tags=["Devices"],
+)
+async def pair_device(
+    body: PairDeviceRequest,
+    _auth: AuthRequired,
+):
+    """Run a pairing handshake against a device before creating it.
+
+    The frontend opens this endpoint after the user has performed the
+    device's physical pairing action (e.g. held the power button for 5s).
+    The response carries provider-specific fields the caller must include
+    in the subsequent ``POST /api/v1/devices`` body.
+
+    Status codes:
+      200  paired — fields returned
+      400  unknown device type, or device type does not support pairing
+      409  device not ready — user must perform the physical action
+            (or retry, e.g. the pairing window timed out)
+      422  invalid URL or device configuration
+    """
+    try:
+        provider = get_provider(body.device_type)
+    except ValueError:
+        raise HTTPException(status_code=400, detail=f"Unknown device type: {body.device_type}")
+
+    try:
+        fields = await provider.pair_device(body.url)
+    except NotImplementedError:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Device type {body.device_type!r} does not support pairing",
+        )
+    except PairingNotReady as exc:
+        raise HTTPException(status_code=409, detail=str(exc))
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+    except Exception as exc:
+        logger.warning(
+            "Pairing failed for %s at %s: %s",
+            body.device_type,
+            body.url,
+            exc,
+            exc_info=True,
+        )
+        raise HTTPException(
+            status_code=502,
+            detail=f"Pairing failed for {body.device_type} at {body.url}.",
+        )
+
+    if not isinstance(fields, dict):
+        logger.warning(
+            "Provider %s.pair_device returned %r (expected dict)",
+            body.device_type,
+            type(fields).__name__,
+        )
+        raise HTTPException(
+            status_code=500,
+            detail=f"Provider {body.device_type!r} returned malformed pairing result",
+        )
+
+    return PairDeviceResponse(fields=fields)
+
+
 @router.get("/api/v1/devices", response_model=DeviceListResponse, tags=["Devices"])
 async def list_devices(
     _auth: AuthRequired,

server/src/ledgrab/api/schemas/devices.py

@@ -232,6 +232,32 @@ class DeviceUpdate(BaseModel):
     )
 
 
+class PairDeviceRequest(BaseModel):
+    """Initiate a pairing handshake with a device before creating it.
+
+    The caller is expected to have just performed the device's physical
+    pairing action (e.g. holding the power button on a Nanoleaf for 5 s,
+    pressing the Hue bridge link button). The response carries any
+    provider-specific fields the frontend must include in the subsequent
+    ``POST /api/v1/devices`` payload — typically an auth token.
+    """
+
+    device_type: str = Field(description="Device type identifier (e.g. 'nanoleaf')")
+    url: str = Field(description="Device URL (e.g. 'nanoleaf://192.168.1.50')")
+
+
+class PairDeviceResponse(BaseModel):
+    """Successful pairing result. ``fields`` is merged into the create payload."""
+
+    fields: Dict[str, object] = Field(
+        default_factory=dict,
+        description=(
+            "Provider-specific fields to include in the subsequent device-create "
+            "request (e.g. {'nanoleaf_token': 'abc...'})."
+        ),
+    )
+
+
 class CalibrationLineSchema(BaseModel):
     """One LED line in advanced calibration."""
 

server/src/ledgrab/core/devices/led_client.py

@@ -37,6 +37,15 @@ class DeviceHealth:
     error: Optional[str] = None
 
 
+class PairingNotReady(Exception):
+    """Raised by ``pair_device`` when the user hasn't performed the physical
+    pairing action yet (or it timed out before the device acknowledged).
+
+    Distinct from generic exceptions so the route handler can return a 409
+    instead of a 500 — the UI shows a retry prompt rather than a hard error.
+    """
+
+
 @dataclass
 class DiscoveredDevice:
     """A device found via network discovery."""
@@ -216,6 +225,30 @@ class LEDDeviceProvider(ABC):
         """
         return []
 
+    async def pair_device(self, url: str) -> Dict[str, object]:
+        """Run a pairing handshake against the device at ``url``.
+
+        Implementations expect the user to have just performed the device's
+        physical pairing action (Nanoleaf: hold power 5s; Hue: press the
+        link button; Twinkly: enter Network setup mode) before calling.
+
+        Returns:
+            A dict of provider-specific fields that the caller should merge
+            into the subsequent ``create_device`` payload — e.g.
+            ``{"nanoleaf_token": "abc..."}`` or ``{"tuya_local_key": "..."}``.
+
+        Raises:
+            PairingNotReady when the user hasn't performed the physical
+                action yet (the caller surfaces this as a retryable 409 so
+                the UI can show "Press the button now, then try again").
+            ValueError on a fundamentally invalid URL or device.
+
+        Default: raises ``NotImplementedError`` so a missing implementation
+        on a ``requires_pairing`` provider fails loud at request time
+        rather than silently returning an empty dict.
+        """
+        raise NotImplementedError(f"{self.device_type} doesn't support pairing")
+
     async def get_brightness(self, url: str) -> int:
         """Get device brightness (0-255). Override if capabilities include brightness_control."""
         raise NotImplementedError

server/src/ledgrab/static/css/components.css

@@ -1045,6 +1045,79 @@ textarea:focus-visible {
     border-color: var(--primary-color);
     background: color-mix(in srgb, var(--primary-color) 12%, var(--bg-secondary));
 }
+/* ── MiniSelect (icon-less compact dropdown) ── */
+.mini-select-trigger {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 10px;
+    min-height: 28px;
+    background: var(--bg-secondary);
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    color: var(--text-primary);
+    font-size: 0.85rem;
+    cursor: pointer;
+    transition: border-color 120ms ease, background 120ms ease;
+}
+.mini-select-trigger:hover,
+.mini-select-trigger:focus-visible {
+    border-color: var(--primary-color);
+}
+.mini-select-trigger-arrow {
+    opacity: 0.6;
+    font-size: 0.75em;
+}
+.mini-select-popup {
+    position: fixed;
+    background: var(--card-bg);
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    box-shadow: 0 6px 24px rgba(0, 0, 0, 0.35);
+    z-index: 9999;
+    overflow-y: auto;
+    display: none;
+    padding: 4px;
+    min-width: 120px;
+}
+.mini-select-popup.open { display: block; }
+.mini-select-popup:focus,
+.mini-select-popup:focus-visible {
+    outline: none;
+}
+.mini-select-option {
+    padding: 6px 10px;
+    border-radius: 4px;
+    cursor: pointer;
+    color: var(--text-primary);
+    font-size: 0.85rem;
+    user-select: none;
+}
+.mini-select-option:hover {
+    background: color-mix(in srgb, var(--primary-color) 14%, transparent);
+}
+.mini-select-option.active {
+    color: var(--primary-color);
+    font-weight: 600;
+}
+.mini-select-option.focused {
+    background: color-mix(in srgb, var(--primary-color) 20%, transparent);
+    box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--primary-color) 45%, transparent);
+}
+
+.icon-select-cell.focused {
+    border-color: var(--primary-color);
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color) 30%, transparent);
+}
+/* When the keyboard cursor lands on the currently-selected cell, intensify
+   the focus ring so the combined active+focused state is unambiguous. */
+.icon-select-cell.active.focused {
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color) 55%, transparent);
+}
+.icon-select-popup:focus,
+.icon-select-popup:focus-visible {
+    outline: none;
+}
 
 .icon-select-cell-icon {
     display: flex;
@@ -1628,3 +1701,194 @@ textarea:focus-visible {
     height: 16px;
     fill: currentColor;
 }
+
+/* ── Pair Device Modal ──────────────────────────────────────────
+   Reusable handshake UI for drivers that require a physical pairing
+   action (Nanoleaf, Tuya, Twinkly, …). See `features/pairing-flow.ts`
+   and `modals/pair-device.html`. The instructions stay visible across
+   states, dimming during pairing so the user remains oriented while
+   the progress ring takes focal point. */
+
+.pair-instructions {
+    color: var(--lux-ink-dim, var(--text-secondary));
+    font-size: 0.92rem;
+    line-height: 1.5;
+    margin: 0 0 18px 0;
+    transition: opacity 0.25s ease;
+}
+
+.pair-states[data-pair-state="pairing"] ~ .pair-instructions,
+.pair-states[data-pair-state="pairing"] .pair-instructions {
+    /* Selector kept for posterity — actual dimming is applied via the
+       parent attribute below. */
+}
+
+.modal-body:has(.pair-states[data-pair-state="pairing"]) .pair-instructions {
+    opacity: 0.6;
+}
+
+.pair-states {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 18px;
+    padding: 8px 0 4px;
+    min-height: 200px;
+}
+
+.pair-state {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 18px;
+    width: 100%;
+    animation: pairFade 0.28s ease both;
+}
+
+@keyframes pairFade {
+    from { opacity: 0; transform: translateY(4px); }
+    to   { opacity: 1; transform: none; }
+}
+
+.pair-action {
+    min-width: 180px;
+    justify-content: center;
+}
+
+/* ── Idle visual: device-glyph with a soft pulse halo ────────── */
+
+.pair-visual {
+    position: relative;
+    width: 96px;
+    height: 96px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.pair-visual-glyph {
+    width: 56px;
+    height: 56px;
+    color: var(--ch-signal, var(--primary-color));
+    opacity: 0.85;
+}
+
+.pair-pulse {
+    position: absolute;
+    inset: 0;
+    border-radius: 50%;
+    background: radial-gradient(
+        circle at center,
+        color-mix(in srgb, var(--ch-signal, var(--primary-color)) 28%, transparent),
+        transparent 70%
+    );
+    animation: pairPulse 2.2s ease-in-out infinite;
+}
+
+@keyframes pairPulse {
+    0%, 100% { transform: scale(0.85); opacity: 0.55; }
+    50%      { transform: scale(1.08); opacity: 1; }
+}
+
+/* ── Pairing ring + countdown ────────────────────────────────── */
+
+.pair-ring-wrap {
+    position: relative;
+    width: 140px;
+    height: 140px;
+}
+
+.pair-ring {
+    width: 100%;
+    height: 100%;
+    /* Rotate so the fill starts at 12 o'clock and progresses clockwise. */
+    transform: rotate(-90deg);
+}
+
+.pair-ring-bg {
+    stroke: color-mix(in srgb, var(--lux-line-bold, var(--border-color)) 60%, transparent);
+}
+
+.pair-ring-fg {
+    stroke: var(--ch-signal, var(--primary-color));
+    stroke-dasharray: 0 100;
+    transition: stroke-dasharray 0.18s linear;
+    filter: drop-shadow(0 0 8px color-mix(in srgb, var(--ch-signal, var(--primary-color)) 45%, transparent));
+}
+
+.pair-ring-content {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 2px;
+    pointer-events: none;
+}
+
+.pair-ring-count {
+    font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+    font-size: 1.9rem;
+    font-weight: 500;
+    color: var(--lux-ink, var(--text-color));
+    letter-spacing: 0.02em;
+    line-height: 1;
+}
+
+.pair-ring-label {
+    font-size: 0.72rem;
+    text-transform: uppercase;
+    letter-spacing: 0.16em;
+    color: var(--lux-ink-dim, var(--text-secondary));
+}
+
+/* ── Status banners (not-ready / success / failed) ───────────── */
+
+.pair-status {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    width: 100%;
+    padding: 14px 16px;
+    border-radius: 8px;
+    border: 1px solid var(--lux-line-bold, var(--border-color));
+    background: color-mix(in srgb, var(--lux-bg-1, var(--card-bg)) 80%, transparent);
+    font-size: 0.92rem;
+    line-height: 1.45;
+    color: var(--lux-ink, var(--text-color));
+}
+
+.pair-status .icon {
+    flex: 0 0 auto;
+    width: 22px;
+    height: 22px;
+    margin-top: 1px;
+}
+
+.pair-status-ok {
+    border-color: color-mix(in srgb, var(--ch-signal, var(--primary-color)) 55%, transparent);
+    background: color-mix(in srgb, var(--ch-signal, var(--primary-color)) 12%, transparent);
+}
+.pair-status-ok .icon { color: var(--ch-signal, var(--primary-color)); }
+
+.pair-status-warn {
+    border-color: color-mix(in srgb, var(--ch-amber, #d99a00) 55%, transparent);
+    background: color-mix(in srgb, var(--ch-amber, #d99a00) 12%, transparent);
+}
+.pair-status-warn .icon { color: var(--ch-amber, #d99a00); }
+
+.pair-status-err {
+    border-color: color-mix(in srgb, var(--ch-coral, var(--danger-color)) 55%, transparent);
+    background: color-mix(in srgb, var(--ch-coral, var(--danger-color)) 12%, transparent);
+}
+.pair-status-err .icon { color: var(--ch-coral, var(--danger-color)); }
+
+@media (prefers-reduced-motion: reduce) {
+    .pair-pulse,
+    .pair-state { animation: none; }
+    .pair-ring-fg { transition: none; }
+}
+

server/src/ledgrab/static/js/features/pairing-flow.ts

@@ -0,0 +1,333 @@
+/**
+ * Reusable pairing-flow controller — opens the `#pair-device-modal`,
+ * drives its state transitions, POSTs to `/devices/pair`, and resolves
+ * with the provider-returned fields so a caller can merge them into a
+ * device-create payload.
+ *
+ * The module is driver-agnostic. Future drivers call
+ * `runPairingFlow({deviceType, url})` and consume the returned `fields`
+ * directly — the flow knows nothing about Nanoleaf, Tuya, Twinkly, etc.
+ *
+ * Backend contract:
+ *   POST /api/v1/devices/pair  { device_type, url }
+ *     200 → { fields: {...} }           — success
+ *     409 → device not ready / window timed out  — retryable
+ *     400 / 422 / 502 → terminal failure with error detail
+ */
+
+import { fetchWithAuth, ApiError } from '../core/api.ts';
+import { t } from '../core/i18n.ts';
+import { Modal } from '../core/modal.ts';
+
+/** Length of the visual pairing window in seconds. Most consumer IoT
+ *  devices open a 30s window after the user presses the pairing button;
+ *  the ring fills from 0 → full over this period purely as a UI hint —
+ *  the actual handshake duration is dictated by the backend, not this
+ *  timer. */
+const PAIRING_WINDOW_SECONDS = 30;
+
+/** Tiny pause after a successful pair so the user sees the confirmation
+ *  before the modal disappears. */
+const SUCCESS_DISMISS_DELAY_MS = 450;
+
+export interface PairingFlowOptions {
+    /** Device type slug, matched to backend driver registry (e.g. 'nanoleaf'). */
+    deviceType: string;
+    /** Pairing URL — driver-specific scheme accepted (e.g. 'nanoleaf://10.0.0.5'). */
+    url: string;
+    /** Override the instructions i18n key. Defaults to
+     *  `device.${deviceType}.pair.instructions`, with fallback to
+     *  `pairing.instructions.default` when the type-specific key is missing. */
+    instructionsKey?: string;
+}
+
+export interface PairingFlowResult {
+    /** Fields returned by the provider, ready to merge into the
+     *  device-create payload (token, client key, group id, …). */
+    fields: Record<string, unknown>;
+}
+
+/** Sentinel thrown when the user dismisses the modal (cancel / close /
+ *  backdrop / Esc). Callers should treat this as a soft cancel — not
+ *  an error to surface. */
+export class PairingCancelled extends Error {
+    constructor() {
+        super('Pairing cancelled by user');
+        this.name = 'PairingCancelled';
+    }
+}
+
+type PairState = 'idle' | 'pairing' | 'notready' | 'success' | 'failed';
+
+interface RunCtx {
+    modal: PairModal;
+    opts: PairingFlowOptions;
+    resolve: (value: PairingFlowResult) => void;
+    reject: (err: unknown) => void;
+    /** AbortController for an in-flight pair request, used by Cancel. */
+    abort: AbortController | null;
+    /** RequestAnimationFrame/interval handle for the countdown ring. */
+    countdownTimer: number | null;
+    /** True once we've resolved or rejected — guards double-finalize. */
+    settled: boolean;
+}
+
+class PairModal extends Modal {
+    constructor() { super('pair-device-modal'); }
+}
+
+let _modal: PairModal | null = null;
+let _ctx: RunCtx | null = null;
+
+/** Lazy single-instance modal so we don't bind listeners until first use. */
+function _getModal(): PairModal {
+    if (!_modal) _modal = new PairModal();
+    return _modal;
+}
+
+function _byId<T extends HTMLElement = HTMLElement>(id: string): T | null {
+    return document.getElementById(id) as T | null;
+}
+
+/** Set the modal's `[data-pair-state]` attribute and toggle child blocks. */
+function _setState(state: PairState): void {
+    const root = document.querySelector('#pair-device-modal .pair-states') as HTMLElement | null;
+    if (!root) return;
+    root.setAttribute('data-pair-state', state);
+    const blocks = root.querySelectorAll<HTMLElement>('[data-pair-state-block]');
+    blocks.forEach(b => {
+        const isActive = b.getAttribute('data-pair-state-block') === state;
+        b.style.display = isActive ? '' : 'none';
+    });
+}
+
+/** Apply the type-specific (or fallback) instruction text. */
+function _applyInstructions(opts: PairingFlowOptions): void {
+    const el = _byId('pair-device-instructions');
+    if (!el) return;
+    const specificKey = opts.instructionsKey ?? `device.${opts.deviceType}.pair.instructions`;
+    const fallbackKey = 'pairing.instructions.default';
+    // If the i18n helper returns the key unchanged it means the key is missing —
+    // fall back to the generic default so the user always sees real copy.
+    const specific = t(specificKey);
+    el.textContent = specific === specificKey ? t(fallbackKey) : specific;
+    // Keep the data-i18n attribute pointing at whatever key we ended up
+    // showing so `updateAllText` (triggered on language change) refreshes it.
+    el.setAttribute('data-i18n', specific === specificKey ? fallbackKey : specificKey);
+}
+
+/** Start the visual countdown ring. Purely cosmetic — the actual fetch
+ *  has its own deadline. */
+function _startCountdown(ctx: RunCtx): void {
+    const ring = document.querySelector('#pair-device-modal .pair-ring-fg') as SVGCircleElement | null;
+    const countEl = _byId('pair-countdown');
+    if (!ring || !countEl) return;
+
+    const totalMs = PAIRING_WINDOW_SECONDS * 1000;
+    const startedAt = performance.now();
+
+    // pathLength=100, so stroke-dasharray "X 100" fills X% of the circumference.
+    ring.style.strokeDasharray = '0 100';
+    countEl.textContent = String(PAIRING_WINDOW_SECONDS);
+
+    const tick = () => {
+        if (ctx.settled) return;
+        const elapsed = performance.now() - startedAt;
+        const ratio = Math.min(1, elapsed / totalMs);
+        ring.style.strokeDasharray = `${(ratio * 100).toFixed(2)} 100`;
+        const remaining = Math.max(0, Math.ceil((totalMs - elapsed) / 1000));
+        countEl.textContent = String(remaining);
+        if (ratio < 1) {
+            ctx.countdownTimer = requestAnimationFrame(tick);
+        } else {
+            ctx.countdownTimer = null;
+        }
+    };
+    ctx.countdownTimer = requestAnimationFrame(tick);
+}
+
+function _stopCountdown(ctx: RunCtx): void {
+    if (ctx.countdownTimer !== null) {
+        cancelAnimationFrame(ctx.countdownTimer);
+        ctx.countdownTimer = null;
+    }
+}
+
+/** Fire the POST and dispatch to the appropriate post-response state. */
+async function _attemptPair(ctx: RunCtx): Promise<void> {
+    if (ctx.settled) return;
+    _setState('pairing');
+    _startCountdown(ctx);
+
+    ctx.abort = new AbortController();
+    try {
+        const resp = await fetchWithAuth('/devices/pair', {
+            method: 'POST',
+            body: JSON.stringify({
+                device_type: ctx.opts.deviceType,
+                url: ctx.opts.url,
+            }),
+            signal: ctx.abort.signal,
+            // The pairing window itself can be ~30s; allow a little headroom.
+            timeout: 45_000,
+            // Don't retry — pairing isn't idempotent and 5xx during a handshake
+            // means the device side is unhappy. Surface immediately.
+            retry: false,
+        });
+        _stopCountdown(ctx);
+        ctx.abort = null;
+        await _handleResponse(ctx, resp);
+    } catch (err: unknown) {
+        _stopCountdown(ctx);
+        ctx.abort = null;
+        if (ctx.settled) return;
+        // AbortError surfaces when Cancel was clicked — settled was already
+        // set in the cancel handler; nothing more to do.
+        if ((err as { name?: string })?.name === 'AbortError') return;
+        if (err instanceof ApiError && err.isAuth) {
+            // The api layer already opened the login flow; just reject so
+            // callers don't hang.
+            _finalize(ctx, () => ctx.reject(err));
+            return;
+        }
+        const detail = err instanceof Error ? err.message : t('api.error.network');
+        _showFailure(detail);
+    }
+}
+
+async function _handleResponse(ctx: RunCtx, resp: Response): Promise<void> {
+    if (resp.status === 200) {
+        let parsed: { fields?: Record<string, unknown> } = {};
+        try { parsed = await resp.json() as { fields?: Record<string, unknown> }; }
+        catch { /* fall through with empty fields */ }
+        const fields = parsed.fields ?? {};
+        _setState('success');
+        // Brief confirmation before dismissing, so the user gets feedback.
+        window.setTimeout(() => {
+            _finalize(ctx, () => {
+                ctx.modal.forceClose();
+                ctx.resolve({ fields });
+            });
+        }, SUCCESS_DISMISS_DELAY_MS);
+        return;
+    }
+
+    if (resp.status === 409) {
+        _setState('notready');
+        return;
+    }
+
+    // 400 / 422 / 502 / any other non-2xx → terminal failure.
+    let detail = '';
+    try {
+        const body = await resp.json() as { detail?: string };
+        if (typeof body?.detail === 'string') detail = body.detail;
+    } catch { /* no JSON body */ }
+    _showFailure(detail || `${resp.status} ${resp.statusText}`);
+}
+
+function _showFailure(detail: string): void {
+    const detailEl = _byId('pair-failure-detail');
+    if (detailEl) {
+        // Render localized prefix + raw detail. The i18n helper supports
+        // {detail} interpolation, so we use the templated form when available
+        // and fall back to "Pairing failed: <detail>" assembled manually.
+        const templated = t('pairing.failed', { detail });
+        // If the helper returned the key unchanged it means the locale file
+        // doesn't carry the key — assemble manually as a safety net.
+        if (templated === 'pairing.failed' || templated.includes('{detail}')) {
+            detailEl.textContent = `${t('pairing.failed_prefix')} ${detail}`.trim();
+        } else {
+            detailEl.textContent = templated;
+        }
+    }
+    _setState('failed');
+}
+
+function _finalize(ctx: RunCtx, work: () => void): void {
+    if (ctx.settled) return;
+    ctx.settled = true;
+    _stopCountdown(ctx);
+    if (ctx.abort) { ctx.abort.abort(); ctx.abort = null; }
+    _detachHandlers();
+    _ctx = null;
+    work();
+}
+
+// ── Event-handler refs (kept so we can detach on close) ──────────────
+
+let _onStart: (() => void) | null = null;
+let _onRetry: (() => void) | null = null;
+let _onCloseTerminal: (() => void) | null = null;
+let _onCancel: (() => void) | null = null;
+let _onCloseBtn: (() => void) | null = null;
+
+function _attachHandlers(ctx: RunCtx): void {
+    _onStart = () => { if (!ctx.settled) void _attemptPair(ctx); };
+    _onRetry = () => { if (!ctx.settled) void _attemptPair(ctx); };
+    const cancelAll = () => {
+        _finalize(ctx, () => {
+            ctx.modal.forceClose();
+            ctx.reject(new PairingCancelled());
+        });
+    };
+    _onCancel = cancelAll;
+    _onCloseTerminal = cancelAll;
+    _onCloseBtn = cancelAll;
+
+    _byId('pair-start-btn')?.addEventListener('click', _onStart);
+    _byId('pair-retry-btn')?.addEventListener('click', _onRetry);
+    _byId('pair-close-btn')?.addEventListener('click', _onCloseTerminal);
+    _byId('pair-cancel-btn')?.addEventListener('click', _onCancel);
+    _byId('pair-device-close-btn')?.addEventListener('click', _onCloseBtn);
+}
+
+function _detachHandlers(): void {
+    if (_onStart) _byId('pair-start-btn')?.removeEventListener('click', _onStart);
+    if (_onRetry) _byId('pair-retry-btn')?.removeEventListener('click', _onRetry);
+    if (_onCloseTerminal) _byId('pair-close-btn')?.removeEventListener('click', _onCloseTerminal);
+    if (_onCancel) _byId('pair-cancel-btn')?.removeEventListener('click', _onCancel);
+    if (_onCloseBtn) _byId('pair-device-close-btn')?.removeEventListener('click', _onCloseBtn);
+    _onStart = _onRetry = _onCloseTerminal = _onCancel = _onCloseBtn = null;
+}
+
+/**
+ * Open the pair modal, run the pairing handshake on user gesture, and
+ * resolve with the provider-returned `fields`. Rejects with
+ * {@link PairingCancelled} on user dismiss, or with the underlying error
+ * for terminal failures.
+ *
+ * Only one pairing flow can be active at a time — calling this while
+ * another is in flight rejects the previous one as cancelled.
+ */
+export function runPairingFlow(opts: PairingFlowOptions): Promise<PairingFlowResult> {
+    // If another flow is mid-run, soft-cancel it. The caller of the
+    // previous run will see a PairingCancelled rejection, matching what
+    // happens when the user clicks Cancel.
+    if (_ctx && !_ctx.settled) {
+        const prev = _ctx;
+        _finalize(prev, () => {
+            prev.modal.forceClose();
+            prev.reject(new PairingCancelled());
+        });
+    }
+
+    return new Promise<PairingFlowResult>((resolve, reject) => {
+        const modal = _getModal();
+        _applyInstructions(opts);
+        _setState('idle');
+
+        const ctx: RunCtx = {
+            modal,
+            opts,
+            resolve,
+            reject,
+            abort: null,
+            countdownTimer: null,
+            settled: false,
+        };
+        _ctx = ctx;
+        _attachHandlers(ctx);
+        modal.open();
+    });
+}

server/src/ledgrab/static/locales/en.json

@@ -2939,5 +2939,16 @@
   "streams.group.audio_processing": "Audio Processing",
   "section.empty.audio_processing_templates": "No audio processing templates yet. Click + to create one.",
   "audio_source.group.capture": "Capture Sources",
-  "audio_source.group.processed": "Processed Sources"
+  "audio_source.group.processed": "Processed Sources",
+  "pairing.title": "Pair Device",
+  "pairing.instructions.default": "Press and hold the pairing button on your device, then click Start. Devices typically open a 30-second pairing window — be ready to act quickly.",
+  "pairing.start": "Start pairing",
+  "pairing.pairing": "Pairing…",
+  "pairing.cancel": "Cancel",
+  "pairing.retry": "Try again",
+  "pairing.close": "Close",
+  "pairing.success": "Paired successfully",
+  "pairing.not_ready": "Device didn't respond. Press the pairing button on your device, then try again.",
+  "pairing.failed": "Pairing failed: {detail}",
+  "pairing.failed_prefix": "Pairing failed:"
 }

server/src/ledgrab/static/locales/ru.json

@@ -2619,5 +2619,16 @@
   "streams.group.audio_processing": "Обработка звука",
   "section.empty.audio_processing_templates": "Пока нет шаблонов обработки звука. Нажмите +, чтобы создать.",
   "audio_source.group.capture": "Захват звука",
-  "audio_source.group.processed": "Обработанные источники"
+  "audio_source.group.processed": "Обработанные источники",
+  "pairing.title": "Сопряжение устройства",
+  "pairing.instructions.default": "Нажмите и удерживайте кнопку сопряжения на устройстве, затем нажмите «Начать». Устройства обычно открывают окно сопряжения на 30 секунд — действуйте быстро.",
+  "pairing.start": "Начать сопряжение",
+  "pairing.pairing": "Сопряжение…",
+  "pairing.cancel": "Отмена",
+  "pairing.retry": "Повторить",
+  "pairing.close": "Закрыть",
+  "pairing.success": "Успешно сопряжено",
+  "pairing.not_ready": "Устройство не ответило. Нажмите кнопку сопряжения на устройстве и попробуйте снова.",
+  "pairing.failed": "Сопряжение не удалось: {detail}",
+  "pairing.failed_prefix": "Сопряжение не удалось:"
 }

server/src/ledgrab/static/locales/zh.json

@@ -2614,5 +2614,16 @@
   "streams.group.audio_processing": "音频处理",
   "section.empty.audio_processing_templates": "暂无音频处理模板。点击 + 创建一个。",
   "audio_source.group.capture": "音频捕获",
-  "audio_source.group.processed": "已处理的源"
+  "audio_source.group.processed": "已处理的源",
+  "pairing.title": "配对设备",
+  "pairing.instructions.default": "请按住设备上的配对按钮，然后点击「开始」。设备通常会打开 30 秒的配对窗口——请准备好快速操作。",
+  "pairing.start": "开始配对",
+  "pairing.pairing": "配对中…",
+  "pairing.cancel": "取消",
+  "pairing.retry": "重试",
+  "pairing.close": "关闭",
+  "pairing.success": "配对成功",
+  "pairing.not_ready": "设备未响应。请按下设备上的配对按钮后重试。",
+  "pairing.failed": "配对失败：{detail}",
+  "pairing.failed_prefix": "配对失败："
 }

server/src/ledgrab/templates/index.html

@@ -236,6 +236,7 @@
     {% include 'modals/setup-required.html' %}
     {% include 'modals/confirm.html' %}
     {% include 'modals/add-device.html' %}
+    {% include 'modals/pair-device.html' %}
     {% include 'modals/capture-template.html' %}
     {% include 'modals/test-template.html' %}
     {% include 'modals/test-stream.html' %}

server/src/ledgrab/templates/modals/pair-device.html

@@ -0,0 +1,86 @@
+<!-- Pair Device Modal — reusable handshake UI for drivers that require a
+     physical pairing action on the device (Nanoleaf, Tuya, Twinkly, …).
+
+     The runtime controller (`features/pairing-flow.ts`) populates the
+     instructions text, drives state transitions (idle → pairing → success
+     | not_ready | failed), and resolves a Promise with the provider-returned
+     fields. State blocks are toggled via the `[data-pair-state]` attribute
+     on `.pair-states`; only the active block is visible. -->
+<div id="pair-device-modal" class="modal" role="dialog" aria-modal="true" aria-labelledby="pair-device-modal-title">
+    <div class="modal-content" style="max-width: 480px;">
+        <div class="modal-header">
+            <h2 id="pair-device-modal-title">
+                <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 12h6"/><path d="M12 9v6"/><circle cx="12" cy="12" r="9"/></svg>
+                <span data-i18n="pairing.title">Pair Device</span>
+            </h2>
+            <button class="modal-close-btn" id="pair-device-close-btn" title="Close" data-i18n-aria-label="aria.close">&#x2715;</button>
+        </div>
+        <div class="modal-body">
+            <p id="pair-device-instructions" class="pair-instructions" data-i18n="pairing.instructions.default">
+                Press and hold the pairing button on your device, then click Start. Devices typically open a 30-second pairing window — be ready to act quickly.
+            </p>
+
+            <div class="pair-states" data-pair-state="idle">
+
+                <!-- ── IDLE ────────────────────────────────────────── -->
+                <div class="pair-state pair-state-idle" data-pair-state-block="idle">
+                    <div class="pair-visual pair-visual-idle" aria-hidden="true">
+                        <span class="pair-pulse"></span>
+                        <svg class="icon pair-visual-glyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="3"/><path d="M19.07 4.93a10 10 0 0 1 0 14.14M4.93 4.93a10 10 0 0 0 0 14.14M16.24 7.76a6 6 0 0 1 0 8.48M7.76 7.76a6 6 0 0 0 0 8.48"/></svg>
+                    </div>
+                    <button type="button" class="btn btn-primary pair-action" id="pair-start-btn" data-i18n="pairing.start">
+                        Start pairing
+                    </button>
+                </div>
+
+                <!-- ── PAIRING (progress ring + countdown) ─────────── -->
+                <div class="pair-state pair-state-pairing" data-pair-state-block="pairing" style="display: none;">
+                    <div class="pair-ring-wrap" role="status" aria-live="polite">
+                        <svg class="pair-ring" viewBox="0 0 100 100" aria-hidden="true">
+                            <circle class="pair-ring-bg" cx="50" cy="50" r="44" fill="none" stroke-width="4"/>
+                            <circle class="pair-ring-fg" cx="50" cy="50" r="44" fill="none" stroke-width="4" stroke-linecap="round" pathLength="100"/>
+                        </svg>
+                        <div class="pair-ring-content">
+                            <div class="pair-ring-count" id="pair-countdown">30</div>
+                            <div class="pair-ring-label" data-i18n="pairing.pairing">Pairing…</div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- ── NOT READY (409 retryable) ───────────────────── -->
+                <div class="pair-state pair-state-notready" data-pair-state-block="notready" style="display: none;">
+                    <div class="pair-status pair-status-warn">
+                        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
+                        <span data-i18n="pairing.not_ready">Device didn't respond. Press the pairing button on your device, then try again.</span>
+                    </div>
+                    <button type="button" class="btn btn-primary pair-action" id="pair-retry-btn" data-i18n="pairing.retry">
+                        Try again
+                    </button>
+                </div>
+
+                <!-- ── SUCCESS (brief confirmation) ────────────────── -->
+                <div class="pair-state pair-state-success" data-pair-state-block="success" style="display: none;">
+                    <div class="pair-status pair-status-ok">
+                        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
+                        <span data-i18n="pairing.success">Paired successfully</span>
+                    </div>
+                </div>
+
+                <!-- ── FAILED (terminal) ───────────────────────────── -->
+                <div class="pair-state pair-state-failed" data-pair-state-block="failed" style="display: none;">
+                    <div class="pair-status pair-status-err">
+                        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/></svg>
+                        <span id="pair-failure-detail" data-i18n="pairing.failed">Pairing failed.</span>
+                    </div>
+                    <button type="button" class="btn btn-secondary pair-action" id="pair-close-btn" data-i18n="pairing.close">
+                        Close
+                    </button>
+                </div>
+
+            </div>
+        </div>
+        <div class="modal-footer">
+            <button type="button" class="btn btn-icon btn-secondary" id="pair-cancel-btn" title="Cancel" data-i18n-aria-label="aria.cancel">&#x2715;</button>
+        </div>
+    </div>
+</div>

server/tests/api/routes/test_devices_routes.py

@@ -203,3 +203,140 @@ class TestBatchStates:
         resp = client.get("/api/v1/devices/batch/states")
         assert resp.status_code == 200
         assert "states" in resp.json()
+
+
+# ---------------------------------------------------------------------------
+# PAIRING
+# ---------------------------------------------------------------------------
+
+
+class _PairableProviderStub:
+    """Test double that exercises the four pair_device outcomes.
+
+    Registered into the provider registry at test-time and unregistered
+    afterwards so the global registry stays clean across tests.
+    """
+
+    def __init__(self, outcome: str):
+        self._outcome = outcome
+
+    @property
+    def device_type(self) -> str:
+        return "_pair_test"
+
+    @property
+    def capabilities(self) -> set:
+        return {"requires_pairing"}
+
+    def create_client(self, config, *, deps):  # pragma: no cover -- not used here
+        raise AssertionError("Stub provider should not be asked to create a client")
+
+    async def check_health(self, url, http_client, prev_health=None):  # pragma: no cover
+        raise AssertionError("Stub provider should not be asked for health")
+
+    async def validate_device(self, url):  # pragma: no cover
+        return {}
+
+    async def pair_device(self, url: str):
+        from ledgrab.core.devices.led_client import PairingNotReady
+
+        if self._outcome == "success":
+            return {"_pair_test_token": "token-abc", "_pair_test_meta": 42}
+        if self._outcome == "not_ready":
+            raise PairingNotReady("Press the device button and try again.")
+        if self._outcome == "invalid_url":
+            raise ValueError("URL is missing a host")
+        if self._outcome == "boom":
+            raise RuntimeError("transport blew up")
+        if self._outcome == "malformed":
+            return "not-a-dict"  # type: ignore[return-value]
+        if self._outcome == "not_implemented":
+            raise NotImplementedError("paired? what is paired?")
+        raise AssertionError(f"unknown outcome: {self._outcome}")
+
+
+@pytest.fixture
+def pair_stub_registered():
+    """Register a test provider for the duration of one test."""
+    from ledgrab.core.devices import led_client as _led_client
+
+    registered: dict = {}
+
+    def _register(outcome: str):
+        provider = _PairableProviderStub(outcome)
+        _led_client.register_provider(provider)  # type: ignore[arg-type]
+        registered["type"] = provider.device_type
+        return provider
+
+    yield _register
+
+    if "type" in registered:
+        _led_client._provider_registry.pop(registered["type"], None)
+
+
+class TestPairDevice:
+    def test_returns_provider_fields_on_success(self, client, pair_stub_registered):
+        pair_stub_registered("success")
+        resp = client.post(
+            "/api/v1/devices/pair",
+            json={"device_type": "_pair_test", "url": "test://host"},
+        )
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {"fields": {"_pair_test_token": "token-abc", "_pair_test_meta": 42}}
+
+    def test_unknown_device_type_returns_400(self, client):
+        resp = client.post(
+            "/api/v1/devices/pair",
+            json={"device_type": "nonexistent_zzz", "url": "x://y"},
+        )
+        assert resp.status_code == 400
+        assert "unknown device type" in resp.json()["detail"].lower()
+
+    def test_not_implemented_returns_400(self, client, pair_stub_registered):
+        pair_stub_registered("not_implemented")
+        resp = client.post(
+            "/api/v1/devices/pair",
+            json={"device_type": "_pair_test", "url": "test://host"},
+        )
+        assert resp.status_code == 400
+        assert "does not support pairing" in resp.json()["detail"]
+
+    def test_pairing_not_ready_returns_409(self, client, pair_stub_registered):
+        pair_stub_registered("not_ready")
+        resp = client.post(
+            "/api/v1/devices/pair",
+            json={"device_type": "_pair_test", "url": "test://host"},
+        )
+        assert resp.status_code == 409
+        assert "press" in resp.json()["detail"].lower()
+
+    def test_invalid_url_returns_422(self, client, pair_stub_registered):
+        pair_stub_registered("invalid_url")
+        resp = client.post(
+            "/api/v1/devices/pair",
+            json={"device_type": "_pair_test", "url": "test://host"},
+        )
+        assert resp.status_code == 422
+        assert "host" in resp.json()["detail"]
+
+    def test_transport_exception_returns_502(self, client, pair_stub_registered):
+        pair_stub_registered("boom")
+        resp = client.post(
+            "/api/v1/devices/pair",
+            json={"device_type": "_pair_test", "url": "test://host"},
+        )
+        assert resp.status_code == 502
+        assert "pairing failed" in resp.json()["detail"].lower()
+
+    def test_malformed_provider_result_returns_500(self, client, pair_stub_registered):
+        pair_stub_registered("malformed")
+        resp = client.post(
+            "/api/v1/devices/pair",
+            json={"device_type": "_pair_test", "url": "test://host"},
+        )
+        assert resp.status_code == 500
+        assert "malformed" in resp.json()["detail"].lower()
+
+    def test_missing_required_fields_returns_422(self, client):
+        resp = client.post("/api/v1/devices/pair", json={"device_type": "nanoleaf"})
+        assert resp.status_code == 422