@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/managers/event-manager.ts

@@ -1,4 +1,5 @@
 import type { UWCEventMap, UWCEventName, UWCEventListener } from '../events'
+import { TELEMETRY_ONLY_EVENTS } from '../events'
 
 type LegacyListener = () => void
 type UntypedListener = (data: unknown) => void
@@ -46,7 +47,10 @@ export class EventManager {
 
   emit<K extends UWCEventName>(event: K, data: UWCEventMap[K]): void {
     this.dispatch(event, data)
-    if (event !== 'change') {
+    // Telemetry-only events (logs, handoff instrumentation) describe what
+    // happened, not a state change — don't cascade them to `change`, or every
+    // log line would trigger a React re-render via legacy `subscribe()`.
+    if (event !== 'change' && !TELEMETRY_ONLY_EVENTS.has(event)) {
       this.dispatch('change', undefined as UWCEventMap['change'])
     }
   }

package/src/observability/connect-observer.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { Session } from '@meshconnect/uwc-types'
+import { EventManager } from '../managers/event-manager'
+import {
+  connectObserver,
+  MAX_REPORTED_OBSERVER_ERRORS
+} from './connect-observer'
+import type { UWCTelemetryEvent } from './telemetry'
+
+const FIXED_NOW = 1_700_000_000_000
+
+describe('connectObserver', () => {
+  it('forwards typed events to onEvent as normalized records', () => {
+    const em = new EventManager()
+    const events: UWCTelemetryEvent[] = []
+    connectObserver(
+      em,
+      { onEvent: e => events.push(e) },
+      'sess',
+      undefined,
+      () => FIXED_NOW
+    )
+
+    em.emit('connecting', { connectionMode: 'injected', walletId: 'metamask' })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      name: 'connecting',
+      operation: 'connect',
+      walletId: 'metamask',
+      sdkSessionId: 'sess',
+      timestamp: FIXED_NOW
+    })
+  })
+
+  it('a throwing correlation-id getter degrades to "no id" — the record is still delivered', () => {
+    // A broken id source is a config problem, not an observer failure: the
+    // record must not be dropped (or misattributed as "observer threw").
+    const em = new EventManager()
+    const events: UWCTelemetryEvent[] = []
+    connectObserver(
+      em,
+      { onEvent: e => events.push(e) },
+      'sess',
+      () => {
+        throw new Error('id source not ready')
+      },
+      () => FIXED_NOW
+    )
+
+    em.emit('connecting', { connectionMode: 'injected', walletId: 'metamask' })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]?.correlationId).toBeUndefined()
+  })
+
+  it('routes log to onLog (scrubbed args), not onEvent', () => {
+    const em = new EventManager()
+    const onEvent = vi.fn()
+    const onLog = vi.fn()
+    connectObserver(em, { onEvent, onLog }, 'sess')
+
+    em.emit('log', {
+      level: 'info',
+      message: 'hi',
+      args: [{ secret: 's', id: 1 }]
+    })
+
+    expect(onEvent).not.toHaveBeenCalled()
+    expect(onLog).toHaveBeenCalledTimes(1)
+    const [level, message, args] = onLog.mock.calls[0]
+    expect(level).toBe('info')
+    expect(message).toBe('hi')
+    expect((args[0] as Record<string, unknown>).secret).toBe('[Redacted]')
+    expect((args[0] as Record<string, unknown>).id).toBe(1)
+  })
+
+  it('does not forward the legacy change event', () => {
+    const em = new EventManager()
+    const onEvent = vi.fn()
+    connectObserver(em, { onEvent }, 'sess')
+    em.emit('change', undefined)
+    expect(onEvent).not.toHaveBeenCalled()
+  })
+
+  it('teardown removes every subscription', () => {
+    const em = new EventManager()
+    const onEvent = vi.fn()
+    const teardown = connectObserver(em, { onEvent }, 'sess')
+    teardown()
+    em.emit('connecting', { connectionMode: 'injected', walletId: 'x' })
+    expect(onEvent).not.toHaveBeenCalled()
+    expect(em.getListenerCount()).toBe(0)
+  })
+
+  it('does not leak the wallet address through a connected event', () => {
+    const em = new EventManager()
+    const events: UWCTelemetryEvent[] = []
+    connectObserver(em, { onEvent: e => events.push(e) }, 'sess')
+    const session = {
+      connectionMode: 'injected',
+      activeNetwork: { namespace: 'eip155', id: 'eip155:1' },
+      activeWallet: { id: 'metamask' },
+      activeAddress: '0xSECRETADDR'
+    } as unknown as Session
+    em.emit('connected', { session })
+    expect(JSON.stringify(events)).not.toContain('0xSECRETADDR')
+  })
+
+  it('a throwing observer never breaks the dispatch chain', () => {
+    const em = new EventManager()
+    connectObserver(
+      em,
+      {
+        onEvent: () => {
+          throw new Error('observer boom')
+        }
+      },
+      'sess'
+    )
+    expect(() =>
+      em.emit('connecting', { connectionMode: 'injected', walletId: 'x' })
+    ).not.toThrow()
+  })
+
+  it('stamps a consumer correlationId as its own field, sdkSessionId stays the instance id', () => {
+    const em = new EventManager()
+    const events: UWCTelemetryEvent[] = []
+    connectObserver(
+      em,
+      { onEvent: e => events.push(e) },
+      'instance-sess',
+      () => 'link-123'
+    )
+    em.emit('connecting', { connectionMode: 'injected', walletId: 'metamask' })
+    expect(events[0].sdkSessionId).toBe('instance-sess')
+    expect(events[0].correlationId).toBe('link-123')
+  })
+
+  it('reports a throwing observer via logger.debug without recursing into onLog', () => {
+    const em = new EventManager()
+    const onLog = vi.fn()
+    // Mirror the production wiring: the real logger's pre-gate tap re-emits a
+    // `log` event on this same bus. Without the recursion guard, the failure
+    // notice would loop back into the (bad) observer's onLog.
+    const debug = vi.fn((message: string, ...args: unknown[]) =>
+      em.emit('log', { level: 'debug', message, args })
+    )
+    const logger = { debug, info: vi.fn(), warn: vi.fn(), error: vi.fn() }
+    connectObserver(
+      em,
+      {
+        onEvent: () => {
+          throw new Error('unique-observer-boom')
+        },
+        onLog
+      },
+      'sess',
+      undefined,
+      Date.now,
+      logger
+    )
+
+    em.emit('connecting', { connectionMode: 'injected', walletId: 'x' })
+
+    // Reported once, via debug...
+    expect(debug).toHaveBeenCalledTimes(1)
+    expect(debug.mock.calls[0][0]).toBe('UWC observer threw')
+    // ...and the guard kept that debug log from re-entering the bad observer.
+    expect(onLog).not.toHaveBeenCalled()
+  })
+
+  it('bounds the observer-error dedup set — an evicted message can report again past the cap', () => {
+    // Same storm-guard contract as the relay/bridge dedup sets: dedup is not a
+    // permanent ledger. An observer throwing high-cardinality messages must not
+    // grow the set without bound over a long-lived instance.
+    const em = new EventManager()
+    const debug = vi.fn()
+    const logger = { debug, info: vi.fn(), warn: vi.fn(), error: vi.fn() }
+    let boom: string | undefined
+    connectObserver(
+      em,
+      {
+        onEvent: () => {
+          if (boom) throw new Error(boom)
+        }
+      },
+      'sess',
+      undefined,
+      Date.now,
+      logger
+    )
+    const fire = (message: string) => {
+      boom = message
+      em.emit('connecting', { connectionMode: 'injected', walletId: 'x' })
+    }
+
+    // Fill the set to the cap with distinct messages — each reports once.
+    for (let i = 0; i < MAX_REPORTED_OBSERVER_ERRORS; i++) fire(`err-${i}`)
+    expect(debug).toHaveBeenCalledTimes(MAX_REPORTED_OBSERVER_ERRORS)
+
+    // Still deduped while in the set.
+    fire('err-0')
+    expect(debug).toHaveBeenCalledTimes(MAX_REPORTED_OBSERVER_ERRORS)
+
+    // One more distinct message trips the cap → the set is evicted → it reports.
+    fire('over-cap')
+    expect(debug).toHaveBeenCalledTimes(MAX_REPORTED_OBSERVER_ERRORS + 1)
+
+    // err-0 was evicted, so it reports again — proving the set stays bounded.
+    fire('err-0')
+    expect(debug).toHaveBeenCalledTimes(MAX_REPORTED_OBSERVER_ERRORS + 2)
+  })
+})

package/src/observability/connect-observer.ts

@@ -0,0 +1,128 @@
+import { createBoundedDedup, safeErrorMessage } from '@meshconnect/uwc-types'
+import type { Logger } from '@meshconnect/uwc-types'
+import type { EventManager } from '../managers/event-manager'
+import { UWC_EVENT_NAMES } from '../events'
+import type { UWCEventMap } from '../events'
+import { normalizeEvent, type UWCObserver } from './telemetry'
+import { scrubArgs, scrubMessage } from './scrub'
+
+/**
+ * Bridge the internal event bus to a consumer-supplied `UWCObserver`.
+ *
+ * Subscribes to every `UWCEventMap` event, normalizes each to a PII-safe
+ * `UWCTelemetryEvent`, and forwards it to `observer.onEvent`. The `log` event is
+ * routed to `observer.onLog` instead (with scrubbed args) — it's the logging
+ * channel, not a telemetry record. `change` is skipped: it's the legacy
+ * re-render cascade and carries no payload.
+ *
+ * Returns a teardown function that removes every subscription. The caller MUST
+ * invoke it on connector teardown — leaving these attached is the same listener-
+ * leak class as the historical `BridgeParent.destroy()` zombie bug.
+ *
+ * @param sdkSessionId - per-connector-instance id stamped on every record.
+ * @param getCorrelationId - resolves the optional consumer correlation id,
+ *   called per-event so an id that arrives/changes after construction is
+ *   honoured. Must not throw (the caller pre-wraps it). Defaults to `undefined`.
+ * @param now - clock injectable for deterministic tests; defaults to `Date.now`.
+ * @param logger - optional; a throwing observer is reported via `logger.debug`.
+ *   When omitted the throw is swallowed silently (the historical behaviour).
+ */
+/**
+ * Cap on distinct observer-error messages remembered for dedup. Same storm-guard
+ * contract as the relay/bridge dedup sets: bounding keeps memory flat on a
+ * long-lived instance even when a broken observer throws high-cardinality
+ * messages (e.g. embedding event data or timestamps).
+ */
+export const MAX_REPORTED_OBSERVER_ERRORS = 100
+
+export function connectObserver(
+  eventManager: EventManager,
+  observer: UWCObserver,
+  sdkSessionId: string,
+  getCorrelationId: () => string | undefined = () => undefined,
+  now: () => number = Date.now,
+  logger?: Logger
+): () => void {
+  const unsubscribers: Array<() => void> = []
+
+  // Set while we log an observer failure so the resulting `logger.debug(...)` —
+  // which re-enters the bus as a `log` event — is NOT forwarded back to the same
+  // (throwing) observer, which would recurse. One logical dispatch at a time.
+  let loggingObserverError = false
+
+  // "Once per error site": dedupe by the error's message so a wallet whose
+  // observer throws on every event logs once, not on a tight loop. Scoped to THIS
+  // connector instance (not module-global) so one connector's failures don't
+  // suppress another's; bounded so it can't grow for the instance's lifetime.
+  const observerErrorDedup = createBoundedDedup(MAX_REPORTED_OBSERVER_ERRORS)
+
+  const reportObserverError = (err: unknown): void => {
+    if (!logger) return
+    // safeErrorMessage: a poisoned getter / throwing toString on the observer's
+    // own error must not escape this reporter, and the dedup key stays bounded.
+    const key = safeErrorMessage(err)
+    if (!observerErrorDedup.firstSeen(key)) return
+    loggingObserverError = true
+    try {
+      logger.debug('UWC observer threw', err)
+    } finally {
+      loggingObserverError = false
+    }
+  }
+
+  for (const name of UWC_EVENT_NAMES) {
+    if (name === 'change') continue
+
+    if (name === 'log') {
+      unsubscribers.push(
+        eventManager.on('log', data => {
+          if (!observer.onLog) return
+          // The observer-error debug log re-enters here as a `log` event; drop it
+          // so we never forward our own failure notice back to the bad observer.
+          if (loggingObserverError) return
+          const { level, message, args } = data as UWCEventMap['log']
+          try {
+            // Scrub the message too, not just args: the message reaches the same
+            // consumer sink, so the egress contract can't rely on every internal
+            // log string staying free of dynamic (potentially sensitive) data.
+            observer.onLog(level, scrubMessage(message), scrubArgs(args))
+          } catch (err) {
+            // A throwing observer must not break the dispatch chain.
+            reportObserverError(err)
+          }
+        })
+      )
+      continue
+    }
+
+    unsubscribers.push(
+      eventManager.on(name, data => {
+        if (!observer.onEvent) return
+        // Resolve the id in its OWN guard: a throwing getter is a config
+        // problem, not an observer failure — degrade to "no id" (the getter's
+        // documented contract) instead of dropping the record.
+        let correlationId: string | undefined
+        try {
+          correlationId = getCorrelationId()
+        } catch {
+          correlationId = undefined
+        }
+        try {
+          // Normalize OUTSIDE the EventManager's own try/catch (which guards the
+          // listener, not the work the listener does), then hand off.
+          observer.onEvent(
+            normalizeEvent(name, data, sdkSessionId, now(), correlationId)
+          )
+        } catch (err) {
+          // Same: never let a bad observer break other listeners.
+          reportObserverError(err)
+        }
+      })
+    )
+  }
+
+  return () => {
+    for (const unsubscribe of unsubscribers) unsubscribe()
+    unsubscribers.length = 0
+  }
+}

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

@@ -0,0 +1,191 @@
+import { describe, it, expect } from 'vitest'
+import { EventManager } from '../managers/event-manager'
+import type { UWCEventMap } from '../events'
+import {
+  trackFocusDuringHandoff,
+  type FocusDocumentLike,
+  type FocusWindowLike
+} from './focus-tracker'
+
+type Hidden = UWCEventMap['pageHiddenDuringHandoff']
+type Visible = UWCEventMap['pageVisibleDuringHandoff']
+
+function makeFakeDoc() {
+  const listeners: Record<string, Array<() => void>> = {}
+  const doc: FocusDocumentLike & { visibilityState: string } = {
+    visibilityState: 'visible',
+    hidden: false,
+    addEventListener: (type, cb) => {
+      ;(listeners[type] ??= []).push(cb)
+    },
+    removeEventListener: (type, cb) => {
+      listeners[type] = (listeners[type] ?? []).filter(l => l !== cb)
+    }
+  }
+  const fire = (type: string) => {
+    for (const cb of [...(listeners[type] ?? [])]) cb()
+  }
+  return { doc, listeners, fire }
+}
+
+// `pageshow` is a WINDOW event (per the HTML spec / MDN it is "sent to a
+// Window"), so the tracker takes a window-like target too — faked separately
+// from the document so the tests exercise the real target split.
+function makeFakeWin() {
+  const listeners: Record<string, Array<() => void>> = {}
+  const win: FocusWindowLike = {
+    addEventListener: (type, cb) => {
+      ;(listeners[type] ??= []).push(cb)
+    },
+    removeEventListener: (type, cb) => {
+      listeners[type] = (listeners[type] ?? []).filter(l => l !== cb)
+    }
+  }
+  const fire = (type: string) => {
+    for (const cb of [...(listeners[type] ?? [])]) cb()
+  }
+  return { win, listeners, fire }
+}
+
+describe('trackFocusDuringHandoff', () => {
+  it('dedupes consecutive same-state emits (iOS bfcache fires pageshow AND visibilitychange)', () => {
+    // One physical return from the wallet can produce BOTH a window `pageshow`
+    // and a document `visibilitychange`→visible. Without dedup the documented
+    // hidden/visible pairing breaks to two visibles per return.
+    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: fireDoc } = makeFakeDoc()
+    const { win, fire: fireWin } = makeFakeWin()
+    trackFocusDuringHandoff(em, 'h-dup', 'mobile', doc, win)
+
+    // Leave for the wallet…
+    doc.visibilityState = 'hidden'
+    fireDoc('visibilitychange')
+    expect(hidden).toHaveLength(1)
+
+    // …and return: bfcache restore fires both signals for ONE return.
+    doc.visibilityState = 'visible'
+    fireWin('pageshow')
+    fireDoc('visibilitychange')
+    expect(visible).toHaveLength(1)
+
+    // A genuine second round-trip still emits.
+    doc.visibilityState = 'hidden'
+    fireDoc('visibilitychange')
+    expect(hidden).toHaveLength(2)
+  })
+
+  it('emits hidden then visible across a visibility round-trip', () => {
+    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()
+    const { win } = makeFakeWin()
+    trackFocusDuringHandoff(em, 'h-1', 'mobile', doc, win)
+
+    doc.visibilityState = 'hidden'
+    doc.hidden = true
+    fire('visibilitychange')
+    doc.visibilityState = 'visible'
+    doc.hidden = false
+    fire('visibilitychange')
+
+    expect(hidden).toEqual([{ handoffId: 'h-1', platform: 'mobile' }])
+    expect(visible).toEqual([{ handoffId: 'h-1', platform: 'mobile' }])
+  })
+
+  it('treats a bfcache pageshow ON THE WINDOW as a "returned" signal', () => {
+    const em = new EventManager()
+    const visible: Visible[] = []
+    em.on('pageVisibleDuringHandoff', e => visible.push(e))
+
+    const { doc } = makeFakeDoc()
+    const { win, fire: fireWin } = makeFakeWin()
+    trackFocusDuringHandoff(em, 'h-2', 'webview', doc, win)
+    fireWin('pageshow')
+
+    expect(visible).toEqual([{ handoffId: 'h-2', platform: 'webview' }])
+  })
+
+  it('does NOT rely on a document-level pageshow (a Window event never reaches document)', () => {
+    // Regression: the listener was originally attached to `document`, where
+    // real browsers never deliver `pageshow` — the fake doc masked it. The
+    // tracker must place nothing pageshow-related on the document target.
+    const em = new EventManager()
+    const visible: Visible[] = []
+    em.on('pageVisibleDuringHandoff', e => visible.push(e))
+
+    const { doc, listeners: docListeners, fire: fireDoc } = makeFakeDoc()
+    const { win } = makeFakeWin()
+    trackFocusDuringHandoff(em, 'h-2b', 'webview', doc, win)
+
+    expect(docListeners['pageshow'] ?? []).toHaveLength(0)
+    fireDoc('pageshow')
+    expect(visible).toEqual([])
+  })
+
+  it('tracks pageshow even when there is no document (window-only runtime)', () => {
+    const em = new EventManager()
+    const visible: Visible[] = []
+    em.on('pageVisibleDuringHandoff', e => visible.push(e))
+
+    const { win, fire } = makeFakeWin()
+    const stop = trackFocusDuringHandoff(em, 'h-2c', 'mobile', undefined, win)
+    fire('pageshow')
+
+    expect(visible).toEqual([{ handoffId: 'h-2c', platform: 'mobile' }])
+    expect(() => stop()).not.toThrow()
+  })
+
+  it('still tracks visibility when there is no window-like target', () => {
+    const em = new EventManager()
+    const hidden: Hidden[] = []
+    em.on('pageHiddenDuringHandoff', e => hidden.push(e))
+
+    const { doc, fire } = makeFakeDoc()
+    const stop = trackFocusDuringHandoff(em, 'h-2d', 'desktop', doc, undefined)
+    doc.visibilityState = 'hidden'
+    fire('visibilitychange')
+
+    expect(hidden).toEqual([{ handoffId: 'h-2d', platform: 'desktop' }])
+    expect(() => stop()).not.toThrow()
+  })
+
+  it('teardown removes the listeners — no events after the handoff settles', () => {
+    const em = new EventManager()
+    const all: string[] = []
+    em.on('pageHiddenDuringHandoff', () => all.push('hidden'))
+    em.on('pageVisibleDuringHandoff', () => all.push('visible'))
+
+    const { doc, fire: fireDoc } = makeFakeDoc()
+    const { win, listeners: winListeners, fire: fireWin } = makeFakeWin()
+    const stop = trackFocusDuringHandoff(em, 'h-3', 'desktop', doc, win)
+    stop()
+
+    doc.visibilityState = 'hidden'
+    fireDoc('visibilitychange')
+    fireWin('pageshow')
+
+    expect(all).toEqual([])
+    expect(winListeners['pageshow'] ?? []).toHaveLength(0)
+  })
+
+  it('is a no-op (no throw) when there is neither document nor window (SSR)', () => {
+    const em = new EventManager()
+    const stop = trackFocusDuringHandoff(
+      em,
+      'h-4',
+      'unknown',
+      undefined,
+      undefined
+    )
+    expect(() => stop()).not.toThrow()
+  })
+})

package/src/observability/focus-tracker.ts

@@ -0,0 +1,96 @@
+import type { Platform } from '@meshconnect/uwc-types'
+import type { EventManager } from '../managers/event-manager'
+
+/**
+ * Minimal `document` surface this tracker touches. Declared locally (rather than
+ * relying on the DOM lib) so the module is SSR-safe and trivially testable with a
+ * fake — no jsdom required.
+ */
+export interface FocusDocumentLike {
+  visibilityState?: string
+  hidden?: boolean
+  addEventListener(type: string, listener: () => void): void
+  removeEventListener(type: string, listener: () => void): void
+}
+
+/**
+ * Minimal `window` surface for the `pageshow` listener. Separate from
+ * `FocusDocumentLike` because the two events have different targets:
+ * `visibilitychange` fires on `document`, while `pageshow` is a WINDOW event
+ * (HTML spec / MDN: "sent to a Window") — a document-level listener would never
+ * fire in a real browser.
+ */
+export interface FocusWindowLike {
+  addEventListener(type: string, listener: () => void): void
+  removeEventListener(type: string, listener: () => void): void
+}
+
+function resolveDocument(): FocusDocumentLike | undefined {
+  const doc = (globalThis as { document?: FocusDocumentLike }).document
+  return doc && typeof doc.addEventListener === 'function' ? doc : undefined
+}
+
+function resolveWindow(): FocusWindowLike | undefined {
+  const win = (globalThis as { window?: FocusWindowLike }).window
+  return win && typeof win.addEventListener === 'function' ? win : undefined
+}
+
+/**
+ * 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).
+ *
+ * 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`).
+ *
+ * @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.
+ */
+export function trackFocusDuringHandoff(
+  eventManager: EventManager,
+  handoffId: string,
+  platform: Platform,
+  doc: FocusDocumentLike | undefined = resolveDocument(),
+  win: FocusWindowLike | undefined = resolveWindow()
+): () => void {
+  if (!doc && !win) return () => {}
+
+  // One physical return can fire BOTH `pageshow` (window) and a
+  // `visibilitychange`→visible (document) — an iOS bfcache restore does. Dedupe
+  // consecutive same-state emits so the hidden/visible events actually pair.
+  let lastState: 'hidden' | 'visible' | undefined
+  const emitState = (state: 'hidden' | 'visible') => {
+    if (state === lastState) return
+    lastState = state
+    eventManager.emit(
+      state === 'hidden'
+        ? 'pageHiddenDuringHandoff'
+        : 'pageVisibleDuringHandoff',
+      { handoffId, platform }
+    )
+  }
+
+  const onVisibility = () => {
+    const hidden = doc?.visibilityState === 'hidden' || doc?.hidden === true
+    emitState(hidden ? 'hidden' : 'visible')
+  }
+  // `pageshow` fires on a bfcache restore (returning from the wallet app on iOS),
+  // a "came back" signal `visibilitychange` doesn't always deliver. It targets
+  // the WINDOW — attaching it to `document` would silently never fire.
+  const onPageShow = () => {
+    emitState('visible')
+  }
+
+  doc?.addEventListener('visibilitychange', onVisibility)
+  win?.addEventListener('pageshow', onPageShow)
+
+  return () => {
+    doc?.removeEventListener('visibilitychange', onVisibility)
+    win?.removeEventListener('pageshow', onPageShow)
+  }
+}