@meshconnect/uwc-core 1.2.3-snapshot.dcfdbbf → 1.3.0

package/src/events.ts

@@ -94,6 +94,24 @@ export interface UWCEventMap {
     error: WalletError
   }
 
+  /**
+   * The WalletConnect relay transport socket dropped (relayer `disconnect`) — e.g.
+   * iOS suspending the WebView during a wallet deep-link silently kills the socket.
+   * Distinct from `relayError` (an abnormal close that surfaced an ERROR): this is
+   * the lifecycle FACT of the socket going down. Emitted once per outage (WC core
+   * re-emits `disconnect` on each failed reconnect); pair with `relayReconnected`
+   * to measure the dead window that leaves an in-flight sign/connect response
+   * undelivered (CARE-263). The relayer passes no payload, so this carries no
+   * reason. Telemetry-only.
+   */
+  relayDisconnected: void
+  /**
+   * The WalletConnect relay transport reconnected after a `relayDisconnected`.
+   * The elapsed time since the paired disconnect is the socket's dead window.
+   * Telemetry-only.
+   */
+  relayReconnected: void
+
   /**
    * `SignClient.init` (WalletConnect) rejected — the client could not be created, so
    * no connect could proceed. Rejects on a storage (IndexedDB) or crypto init failure,
@@ -125,11 +143,8 @@ export interface UWCEventMap {
 
   /** Network switching is in progress. Fires on start and end. */
   networkSwitching: { isLoading: boolean; isWaitingForUserApproval: boolean }
-  /** Network switch succeeded. `address` is the new address the switch
-   *  resolved to (present whenever the connector returned one) — used by
-   *  the lifecycle bridge to suppress the wallet's own echo of this same
-   *  change (see attachLifecycle's echo-suppression window). */
-  networkSwitched: { network: Network; address?: string }
+  /** Network switch succeeded. */
+  networkSwitched: { network: Network }
 
   /** Wallet capabilities were refreshed. */
   capabilitiesUpdated: { capabilities: Record<string, EVMCapabilities> }
@@ -208,6 +223,11 @@ export interface UWCEventMap {
     timeoutMs?: number | undefined
     /** switchNetwork only: target chain already the active one (no-op switch). */
     targetAlreadyActive?: boolean | undefined
+    /** Backgrounding during this handoff: cumulative hidden time (ms) + transition count. */
+    backgroundedMs?: number | undefined
+    backgroundCount?: number | undefined
+    /** WalletConnect only: relay-socket drops seen while this handoff was pending. */
+    relayDropCount?: number | undefined
   }
   /** The user explicitly rejected (4001 / WalletError.type === 'rejected'). Closes a handoff. */
   walletRejected: {
@@ -225,6 +245,11 @@ export interface UWCEventMap {
     errorCode?: string | undefined
     failureKind?: FailureKind | undefined
     source?: ErrorSource | undefined
+    /** Backgrounding during this handoff: cumulative hidden time (ms) + transition count. */
+    backgroundedMs?: number | undefined
+    backgroundCount?: number | undefined
+    /** WalletConnect only: relay-socket drops seen while this handoff was pending. */
+    relayDropCount?: number | undefined
   }
   /** The op failed for any non-rejection reason. Closes a handoff. */
   walletFailed: {
@@ -243,6 +268,11 @@ export interface UWCEventMap {
     errorCode?: string | undefined
     failureKind?: FailureKind | undefined
     source?: ErrorSource | undefined
+    /** Backgrounding during this handoff: cumulative hidden time (ms) + transition count. */
+    backgroundedMs?: number | undefined
+    backgroundCount?: number | undefined
+    /** WalletConnect only: relay-socket drops seen while this handoff was pending. */
+    relayDropCount?: number | undefined
   }
   /**
    * Side marker: the deadline passed with the op still pending. OBSERVATIONAL —
@@ -262,6 +292,11 @@ export interface UWCEventMap {
     timeoutMs: number
     /** switchNetwork only: target chain already the active one (no-op switch). */
     targetAlreadyActive?: boolean | undefined
+    /** Backgrounding so far (marker fires mid-flight): hidden time (ms) + transition count. */
+    backgroundedMs?: number | undefined
+    backgroundCount?: number | undefined
+    /** WalletConnect only: relay-socket drops seen so far while this handoff was pending. */
+    relayDropCount?: number | undefined
   }
 
   // ---- Provider lifecycle (telemetry-only) ----------------------------------
@@ -324,7 +359,12 @@ export interface UWCEventMap {
    * handoff (a bfcache restore can fire both `pageshow` and `visibilitychange`
    * for one physical return). Telemetry-only.
    */
-  pageVisibleDuringHandoff: { handoffId: string; platform: Platform }
+  pageVisibleDuringHandoff: {
+    handoffId: string
+    platform: Platform
+    /** Duration the page was hidden for THIS hide→show segment (ms). */
+    hiddenMs?: number | undefined
+  }
 
   /**
    * Back-compat catch-all. Fires after every other event above.
@@ -348,6 +388,8 @@ export const TELEMETRY_ONLY_EVENTS: ReadonlySet<UWCEventName> = new Set([
   'walletDiscoveryFailed',
   'bridgeError',
   'relayError',
+  'relayDisconnected',
+  'relayReconnected',
   'walletConnectInitError',
   'walletAccountChanged',
   'walletChainChanged',
@@ -375,6 +417,8 @@ const EVENT_NAME_FLAGS: Record<UWCEventName, true> = {
   walletDiscoveryFailed: true,
   bridgeError: true,
   relayError: true,
+  relayDisconnected: true,
+  relayReconnected: true,
   walletConnectInitError: true,
   connecting: true,
   connected: true,

package/src/observability/focus-tracker.test.ts

@@ -88,17 +88,92 @@ describe('trackFocusDuringHandoff', () => {
 
     const { doc, fire } = makeFakeDoc()
     const { win } = makeFakeWin()
-    trackFocusDuringHandoff(em, 'h-1', 'mobile', doc, win)
+    let t = 1000
+    trackFocusDuringHandoff(em, 'h-1', 'mobile', doc, win, () => t)
 
     doc.visibilityState = 'hidden'
     doc.hidden = true
-    fire('visibilitychange')
+    fire('visibilitychange') // hidden at t=1000
+    t = 1700
     doc.visibilityState = 'visible'
     doc.hidden = false
-    fire('visibilitychange')
+    fire('visibilitychange') // visible at t=1700 → 700ms hidden
 
     expect(hidden).toEqual([{ handoffId: 'h-1', platform: 'mobile' }])
-    expect(visible).toEqual([{ handoffId: 'h-1', platform: 'mobile' }])
+    expect(visible).toEqual([
+      { handoffId: 'h-1', platform: 'mobile', hiddenMs: 700 }
+    ])
+  })
+
+  it('summary() reports background count + cumulative hidden time, including an open segment', () => {
+    const em = new EventManager()
+    const { doc, fire } = makeFakeDoc()
+    let t = 0
+    const tracker = trackFocusDuringHandoff(
+      em,
+      'h-sum',
+      'mobile',
+      doc,
+      undefined,
+      () => t
+    )
+
+    // First hide→show: 100 → 600 = 500ms hidden.
+    t = 100
+    doc.visibilityState = 'hidden'
+    fire('visibilitychange')
+    t = 600
+    doc.visibilityState = 'visible'
+    fire('visibilitychange')
+    expect(tracker.summary()).toEqual({
+      backgroundCount: 1,
+      backgroundedMs: 500
+    })
+
+    // Second hide, still hidden when summary() runs at t=1000 → +200 open segment.
+    t = 800
+    doc.visibilityState = 'hidden'
+    fire('visibilitychange')
+    t = 1000
+    expect(tracker.summary()).toEqual({
+      backgroundCount: 2,
+      backgroundedMs: 700
+    })
+  })
+
+  it('records an already-hidden start as a real hidden transition (pairs 1:1, counted)', () => {
+    const em = new EventManager()
+    const hidden: Hidden[] = []
+    const visible: Visible[] = []
+    em.on('pageHiddenDuringHandoff', e => hidden.push(e))
+    em.on('pageVisibleDuringHandoff', e => visible.push(e))
+
+    const { doc, fire } = makeFakeDoc()
+    doc.visibilityState = 'hidden'
+    doc.hidden = true
+    let t = 500
+    const tracker = trackFocusDuringHandoff(
+      em,
+      'h-seed',
+      'mobile',
+      doc,
+      undefined,
+      () => t
+    )
+
+    // Attaching while hidden emits a REAL pageHidden so the later visible pairs 1:1.
+    expect(hidden).toEqual([{ handoffId: 'h-seed', platform: 'mobile' }])
+    expect(visible).toEqual([])
+    expect(tracker.summary()).toEqual({ backgroundCount: 1, backgroundedMs: 0 })
+
+    // Returning at t=900 → paired pageVisible carrying the 400ms segment.
+    t = 900
+    doc.visibilityState = 'visible'
+    doc.hidden = false
+    fire('visibilitychange')
+    expect(visible).toEqual([
+      { handoffId: 'h-seed', platform: 'mobile', hiddenMs: 400 }
+    ])
   })
 
   it('treats a bfcache pageshow ON THE WINDOW as a "returned" signal', () => {
@@ -137,7 +212,13 @@ describe('trackFocusDuringHandoff', () => {
     em.on('pageVisibleDuringHandoff', e => visible.push(e))
 
     const { win, fire } = makeFakeWin()
-    const stop = trackFocusDuringHandoff(em, 'h-2c', 'mobile', undefined, win)
+    const { stop } = trackFocusDuringHandoff(
+      em,
+      'h-2c',
+      'mobile',
+      undefined,
+      win
+    )
     fire('pageshow')
 
     expect(visible).toEqual([{ handoffId: 'h-2c', platform: 'mobile' }])
@@ -150,7 +231,13 @@ describe('trackFocusDuringHandoff', () => {
     em.on('pageHiddenDuringHandoff', e => hidden.push(e))
 
     const { doc, fire } = makeFakeDoc()
-    const stop = trackFocusDuringHandoff(em, 'h-2d', 'desktop', doc, undefined)
+    const { stop } = trackFocusDuringHandoff(
+      em,
+      'h-2d',
+      'desktop',
+      doc,
+      undefined
+    )
     doc.visibilityState = 'hidden'
     fire('visibilitychange')
 
@@ -166,7 +253,7 @@ describe('trackFocusDuringHandoff', () => {
 
     const { doc, fire: fireDoc } = makeFakeDoc()
     const { win, listeners: winListeners, fire: fireWin } = makeFakeWin()
-    const stop = trackFocusDuringHandoff(em, 'h-3', 'desktop', doc, win)
+    const { stop } = trackFocusDuringHandoff(em, 'h-3', 'desktop', doc, win)
     stop()
 
     doc.visibilityState = 'hidden'
@@ -179,7 +266,7 @@ describe('trackFocusDuringHandoff', () => {
 
   it('is a no-op (no throw) when there is neither document nor window (SSR)', () => {
     const em = new EventManager()
-    const stop = trackFocusDuringHandoff(
+    const { stop } = trackFocusDuringHandoff(
       em,
       'h-4',
       'unknown',

package/src/observability/focus-tracker.ts

@@ -35,30 +35,58 @@ function resolveWindow(): FocusWindowLike | undefined {
   return win && typeof win.addEventListener === 'function' ? win : undefined
 }
 
+/** Handle returned by `trackFocusDuringHandoff`. */
+export interface FocusHandoffTracker {
+  /** Remove the visibility listeners. Always call on settle (no-op if none attached). */
+  stop: () => void
+  /**
+   * Backgrounding summary at call time: how many times the page was hidden and the
+   * cumulative hidden duration (ms) during the handoff — including an in-progress
+   * hidden segment if the handoff settles while still backgrounded.
+   */
+  summary: () => { backgroundCount: number; backgroundedMs: number }
+}
+
 /**
  * While a wallet handoff is pending, emit a FACT on every tab-visibility
  * transition — `pageHiddenDuringHandoff` when the page is backgrounded (the user
- * likely left for the wallet app), `pageVisibleDuringHandoff` when it returns
- * (including a bfcache `pageshow`, which iOS uses when coming back from a wallet).
+ * likely left for the wallet app), `pageVisibleDuringHandoff` (with the segment's
+ * `hiddenMs`) when it returns (including a bfcache `pageshow`, which iOS uses when
+ * coming back from a wallet).
  *
- * This is the raw signal behind "did the user actually app-switch to the wallet?"
- * for deep-link flows — it does NOT interpret abandonment. The listeners are
- * scoped to the single handoff: attach right after `awaitingWallet`, and the
- * returned teardown (called the instant the op settles) removes them, so the
- * page's visibility is only observed during the blind window. SSR-safe (no-op
- * when there is neither `document` nor `window`).
+ * This is the raw signal behind "did the user actually app-switch to the wallet,
+ * and for how long?" for deep-link flows — it does NOT interpret abandonment. The
+ * listeners are scoped to the single handoff: attach right after `awaitingWallet`,
+ * and `stop()` (called the instant the op settles) removes them, so the page's
+ * visibility is only observed during the blind window. SSR-safe (no-op when there
+ * is neither `document` nor `window`). `summary()` lets the handoff stamp the
+ * cumulative backgrounding onto its terminal.
  *
- * @returns a teardown that removes the listeners. Always call it (even when
- *   nothing was attached — it's a no-op then) to keep the call site symmetric.
+ * One non-transition case: if the tracker attaches while the page is ALREADY
+ * hidden (handoff initiated from a backgrounded tab), it emits an initial
+ * synthetic `pageHiddenDuringHandoff` at attach time so the eventual return pairs
+ * 1:1 and the hidden segment is counted. So `pageHiddenDuringHandoff` is "every
+ * transition into hidden, plus an already-hidden start", not strictly transitions.
  */
 export function trackFocusDuringHandoff(
   eventManager: EventManager,
   handoffId: string,
   platform: Platform,
   doc: FocusDocumentLike | undefined = resolveDocument(),
-  win: FocusWindowLike | undefined = resolveWindow()
-): () => void {
-  if (!doc && !win) return () => {}
+  win: FocusWindowLike | undefined = resolveWindow(),
+  now: () => number = Date.now
+): FocusHandoffTracker {
+  let backgroundCount = 0
+  let totalHiddenMs = 0
+  let hiddenSince: number | undefined
+
+  const summary = (): { backgroundCount: number; backgroundedMs: number } => ({
+    backgroundCount,
+    backgroundedMs:
+      totalHiddenMs + (hiddenSince !== undefined ? now() - hiddenSince : 0)
+  })
+
+  if (!doc && !win) return { stop: () => {}, summary }
 
   // One physical return can fire BOTH `pageshow` (window) and a
   // `visibilitychange`→visible (document) — an iOS bfcache restore does. Dedupe
@@ -67,12 +95,23 @@ export function trackFocusDuringHandoff(
   const emitState = (state: 'hidden' | 'visible') => {
     if (state === lastState) return
     lastState = state
-    eventManager.emit(
-      state === 'hidden'
-        ? 'pageHiddenDuringHandoff'
-        : 'pageVisibleDuringHandoff',
-      { handoffId, platform }
-    )
+    if (state === 'hidden') {
+      hiddenSince = now()
+      backgroundCount++
+      eventManager.emit('pageHiddenDuringHandoff', { handoffId, platform })
+      return
+    }
+    let hiddenMs: number | undefined
+    if (hiddenSince !== undefined) {
+      hiddenMs = now() - hiddenSince
+      totalHiddenMs += hiddenMs
+      hiddenSince = undefined
+    }
+    eventManager.emit('pageVisibleDuringHandoff', {
+      handoffId,
+      platform,
+      ...(hiddenMs !== undefined ? { hiddenMs } : {})
+    })
   }
 
   const onVisibility = () => {
@@ -89,8 +128,19 @@ export function trackFocusDuringHandoff(
   doc?.addEventListener('visibilitychange', onVisibility)
   win?.addEventListener('pageshow', onPageShow)
 
-  return () => {
-    doc?.removeEventListener('visibilitychange', onVisibility)
-    win?.removeEventListener('pageshow', onPageShow)
+  // Handoff started while ALREADY hidden (initiated from a backgrounded tab):
+  // record it as a real hidden transition so the eventual `pageVisibleDuringHandoff`
+  // pairs 1:1 and summary()/hiddenMs count the segment. `emitState`'s dedup makes
+  // the first subsequent visibilitychange→hidden a no-op.
+  if (doc?.visibilityState === 'hidden' || doc?.hidden === true) {
+    emitState('hidden')
+  }
+
+  return {
+    stop: () => {
+      doc?.removeEventListener('visibilitychange', onVisibility)
+      win?.removeEventListener('pageshow', onPageShow)
+    },
+    summary
   }
 }

package/src/observability/instrument-handoff.test.ts

@@ -47,6 +47,68 @@ describe('instrumentHandoff', () => {
     expect(end.timedOut).toBe(false)
   })
 
+  it('counts relay-socket drops seen during the handoff onto the terminal', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    const wcCtx: HandoffContext = { ...CTX, connectionMode: 'walletConnect' }
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      wcCtx,
+      async () => {
+        // The relay socket drops (and recovers) while the sign request is pending.
+        em.emit('relayDisconnected', undefined)
+        em.emit('relayReconnected', undefined)
+        em.emit('relayDisconnected', undefined)
+        return 'sig'
+      }
+    )
+    const end = seen.find(s => s.name === 'walletSucceeded')?.data as {
+      relayDropCount: number
+      backgroundCount: number
+      backgroundedMs: number
+    }
+    expect(end.relayDropCount).toBe(2)
+    // No backgrounding occurred in this test runtime.
+    expect(end.backgroundCount).toBe(0)
+    expect(end.backgroundedMs).toBe(0)
+  })
+
+  it('stops counting relay drops once the handoff settles', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    const wcCtx: HandoffContext = { ...CTX, connectionMode: 'walletConnect' }
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      wcCtx,
+      async () => 'sig'
+    )
+    // A drop after settle must be ignored (listener removed) and never throw.
+    expect(() => em.emit('relayDisconnected', undefined)).not.toThrow()
+    const end = seen.find(s => s.name === 'walletSucceeded')?.data as {
+      relayDropCount: number
+    }
+    expect(end.relayDropCount).toBe(0)
+  })
+
+  it('omits relayDropCount for non-WalletConnect handoffs (no misattribution)', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    // A WC relay flap firing during an injected handoff must NOT be attributed to it.
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      CTX,
+      async () => {
+        em.emit('relayDisconnected', undefined)
+        return 'sig'
+      }
+    )
+    const end = seen.find(s => s.name === 'walletSucceeded')?.data as {
+      relayDropCount?: number
+    }
+    // Undefined on the bus → dropped by compactUndefined on the telemetry egress.
+    expect(end.relayDropCount).toBeUndefined()
+  })
+
   it('carries targetAlreadyActive through awaitingWallet and the terminal', async () => {
     const em = new EventManager()
     const seen = record(em)

package/src/observability/instrument-handoff.ts

@@ -15,6 +15,7 @@ import {
 } from '../utils/to-wallet-error'
 import { derivePlatform, deriveWalletFlowType } from './telemetry'
 import { trackFocusDuringHandoff } from './focus-tracker'
+import { trackRelayDropsDuringHandoff } from './relay-drop-tracker'
 
 /** Routing facets known at the moment of a wallet handoff. No address, no payload. */
 export interface HandoffContext {
@@ -141,7 +142,32 @@ export async function instrumentHandoff<T>(
   // Observe page-visibility transitions ONLY while this handoff is pending — the
   // app-switch signal for deep-link flows (left for the wallet / came back). The
   // teardown in `finally` removes the listeners the instant the op settles.
-  const stopFocus = trackFocusDuringHandoff(eventManager, handoffId, platform)
+  // Pass `now` through so backgroundedMs shares the same clock as durationMs
+  // (consistent, and deterministic under an injected clock in tests).
+  const focus = trackFocusDuringHandoff(
+    eventManager,
+    handoffId,
+    platform,
+    undefined,
+    undefined,
+    now
+  )
+
+  // Count relay-socket drops seen while this handoff is pending (WalletConnect
+  // only — the tracker is a no-op for other modes so a WC relay flap isn't
+  // misattributed to an injected/TON handoff in flight at the same time).
+  const relayDrops = trackRelayDropsDuringHandoff(
+    eventManager,
+    context.connectionMode
+  )
+
+  // Backgrounding + relay-drop summary, snapshotted onto each terminal so ONE
+  // event answers "backgrounded? how long? socket dropped? recovered?".
+  // `relayDropCount` is undefined off WalletConnect so `compactUndefined` drops it.
+  const handoffMetrics = () => ({
+    ...focus.summary(),
+    ...relayDrops.summary()
+  })
 
   // Same routing facets as `awaitingWallet` so every terminal is self-describing
   // (no handoffId self-join needed to know which wallet / chain / mode it closed).
@@ -164,7 +190,8 @@ export async function instrumentHandoff<T>(
           operation: context.operation,
           durationMs: now() - start,
           timeoutMs,
-          ...routing
+          ...routing,
+          ...handoffMetrics()
         })
       }, timeoutMs)
     : undefined
@@ -177,7 +204,8 @@ export async function instrumentHandoff<T>(
       durationMs: now() - start,
       timedOut,
       timeoutMs: timedOut ? timeoutMs : undefined,
-      ...routing
+      ...routing,
+      ...handoffMetrics()
     })
     return result
   } catch (error) {
@@ -207,7 +235,8 @@ export async function instrumentHandoff<T>(
         errorCode,
         failureKind,
         source,
-        ...routing
+        ...routing,
+        ...handoffMetrics()
       })
     } else {
       eventManager.emit('walletFailed', {
@@ -220,12 +249,14 @@ export async function instrumentHandoff<T>(
         errorCode,
         failureKind,
         source,
-        ...routing
+        ...routing,
+        ...handoffMetrics()
       })
     }
     throw error
   } finally {
     if (timer) clearTimeout(timer)
-    stopFocus()
+    relayDrops.stop()
+    focus.stop()
   }
 }