@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/events.ts

@@ -4,20 +4,36 @@ import type {
   WalletMetadata,
   ConnectionMode,
   WalletError,
-  EVMCapabilities
+  EVMCapabilities,
+  LogLevel,
+  WalletFlowType,
+  Platform,
+  Namespace,
+  NetworkId,
+  FailureKind,
+  ErrorSource,
+  LifecycleUnavailableReason
 } from '@meshconnect/uwc-types'
 
 /**
- * User-initiated operations that can surface through the `error` event.
+ * User-initiated operations that can surface through the `error` event. The
+ * runtime tuple is the single source of truth; the type is derived from it so a
+ * guard test can enumerate every op — and catch a new one added without handoff
+ * instrumentation — instead of relying on a hand-maintained list.
  */
-export type UWCOperation =
-  | 'connect'
-  | 'disconnect'
-  | 'switchNetwork'
-  | 'signMessage'
-  | 'sendTransaction'
-  | 'getWalletCapabilities'
-  | 'initialize'
+export const UWC_OPERATIONS = [
+  'connect',
+  'disconnect',
+  'switchNetwork',
+  'signMessage',
+  'signTypedData',
+  'sendTransaction',
+  'signSolanaTransaction',
+  'getWalletCapabilities',
+  'initialize'
+] as const
+
+export type UWCOperation = (typeof UWC_OPERATIONS)[number]
 
 /**
  * Typed event map emitted by UniversalWalletConnector.
@@ -31,8 +47,52 @@ export type UWCOperation =
 export interface UWCEventMap {
   /** Wallet detection finished; `getWallets()` now reflects which are installed. */
   ready: void
-  /** Emitted once detection finishes, with the final wallet list. */
-  walletsDetected: { wallets: WalletMetadata[] }
+  /**
+   * Emitted once detection finishes, with the final wallet list. `discovery` is a
+   * per-namespace requested-vs-matched summary (telemetry-only, non-PII counts) so
+   * "we asked for N solana wallets, matched 0" is distinguishable from "asked for
+   * none" — answers "why didn't wallet X appear?".
+   */
+  walletsDetected: {
+    wallets: WalletMetadata[]
+    discovery?:
+      | Record<string, { requested: number; matched: number }>
+      | undefined
+  }
+  /**
+   * A single namespace × connector discovery task threw. Telemetry-only — replaces
+   * the historical silent catch so a discovery failure is observable rather than
+   * vanishing. Carries the namespace + connection mode + scrubbed error; never an
+   * address or payload.
+   */
+  walletDiscoveryFailed: {
+    namespace: Namespace
+    connectionMode: ConnectionMode
+    error: WalletError
+  }
+  /**
+   * A bridge operation failed — e.g. wallet-discovery marshaling across the iframe
+   * Comlink boundary timed out or threw. Telemetry-only; replaces silent catches in
+   * `BridgeChild` so "the wallet never showed up via the bridge" (the Bitstarz
+   * class) is observable. Carries the namespace + scrubbed error; no address /
+   * payload. Deduped + benign poll-misses excluded at the source.
+   */
+  bridgeError: {
+    namespace?: Namespace | undefined
+    error: WalletError
+  }
+
+  /**
+   * The WalletConnect relay socket surfaced a transport/provider error — e.g. an
+   * abnormal close (code 3000 "JWT Token is not yet valid" when the device clock is
+   * skewed past the relay's 120s leeway). Emitted from the relayer's error event,
+   * deduped at the connector. This failure is detached from the connect() promise,
+   * so without it the error escapes the handoff funnel entirely. Telemetry-only;
+   * carries only a scrubbed message (no address / payload).
+   */
+  relayError: {
+    error: WalletError
+  }
 
   /** `connect()` has started. */
   connecting: { connectionMode: ConnectionMode; walletId: string }
@@ -57,8 +117,197 @@ export interface UWCEventMap {
   /** Wallet capabilities were refreshed. */
   capabilitiesUpdated: { capabilities: Record<string, EVMCapabilities> }
 
-  /** A user-initiated operation failed. */
-  error: { error: WalletError; operation: UWCOperation }
+  /**
+   * A user-initiated operation failed. Carries optional, telemetry-only
+   * classification (`errorCode` / `failureKind` / `source`) and, for a
+   * no-common-network connect failure, the two CAIP-2 id lists — so a PRE-wallet
+   * validation failure (which never enters the handoff funnel) is still
+   * diagnosable. The React-facing payload is still `{ error, operation }`; the
+   * rest is `undefined` for ordinary errors.
+   */
+  error: {
+    error: WalletError
+    operation: UWCOperation
+    errorCode?: string | undefined
+    failureKind?: FailureKind | undefined
+    source?: ErrorSource | undefined
+    networkMismatch?:
+      | { walletNetworkIds: string[]; configuredNetworkIds: string[] }
+      | undefined
+    /**
+     * `true` when a handoff terminal (`walletRejected`/`walletFailed`) already
+     * reported this same failure — this record is the back-compat duplicate.
+     * For failure metrics: count terminals + `error` where NOT handoffCovered;
+     * absent on pre-wallet validation failures (which have no terminal).
+     */
+    handoffCovered?: boolean | undefined
+  }
+
+  // ---- Observability (telemetry-only; see TELEMETRY_ONLY_EVENTS) -------------
+  // These describe what happened, not a state change, so they intentionally do
+  // NOT cascade to the legacy `change` channel (which drives React re-renders).
+
+  /**
+   * A line emitted through the internal `Logger`. Fires for ALL levels regardless
+   * of the console threshold so an observer can capture `debug`/`info` even when
+   * the console is quiet. `args` is scrubbed before reaching `observer.onLog`.
+   */
+  log: { level: LogLevel; message: string; args: unknown[] }
+
+  /**
+   * Emitted immediately BEFORE control is handed to the wallet for a boundary op
+   * (the moment the blind window opens). Pair with exactly one terminal event via
+   * `handoffId`. Carries no signing payload and no address — only routing facets.
+   */
+  awaitingWallet: {
+    operation: UWCOperation
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    /** CAIP namespace (eip155 | solana | tron | tvm …) — not an address. */
+    namespace?: Namespace | undefined
+    /** CAIP chain id (e.g. `eip155:1`) — not an address. */
+    chainId?: NetworkId | undefined
+    handoffId: string
+    /** Derived, best-effort flow taxonomy (heuristic — see deriveWalletFlowType). */
+    walletFlowType: WalletFlowType
+    /** Coarse runtime surface (heuristic — see derivePlatform). */
+    platform: Platform
+    /** switchNetwork only: target chain already the active one (no-op switch). */
+    targetAlreadyActive?: boolean | undefined
+  }
+
+  /** The wallet resolved the op successfully. Closes a handoff. */
+  walletSucceeded: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+    chainId?: NetworkId | undefined
+    /** A `walletTimedOut` marker fired before this terminal (late completion). */
+    timedOut: boolean
+    /** The deadline that elapsed, present only when `timedOut`. */
+    timeoutMs?: number | undefined
+    /** switchNetwork only: target chain already the active one (no-op switch). */
+    targetAlreadyActive?: boolean | undefined
+  }
+  /** The user explicitly rejected (4001 / WalletError.type === 'rejected'). Closes a handoff. */
+  walletRejected: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+    chainId?: NetworkId | undefined
+    timedOut: boolean
+    timeoutMs?: number | undefined
+    targetAlreadyActive?: boolean | undefined
+    /** Stringified error code (EIP-1193 numeric / string), when present. */
+    errorCode?: string | undefined
+    failureKind?: FailureKind | undefined
+    source?: ErrorSource | undefined
+  }
+  /** The op failed for any non-rejection reason. Closes a handoff. */
+  walletFailed: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+    error: WalletError
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+    chainId?: NetworkId | undefined
+    timedOut: boolean
+    timeoutMs?: number | undefined
+    targetAlreadyActive?: boolean | undefined
+    /** Stringified error code (EIP-1193 numeric / string), when present. */
+    errorCode?: string | undefined
+    failureKind?: FailureKind | undefined
+    source?: ErrorSource | undefined
+  }
+  /**
+   * Side marker: the deadline passed with the op still pending. OBSERVATIONAL —
+   * it does NOT reject, abort, or mutate state; the wallet may still complete and
+   * produce the real terminal. Never fires for an op that settled before the
+   * deadline. Not itself a terminal.
+   */
+  walletTimedOut: {
+    handoffId: string
+    operation: UWCOperation
+    durationMs: number
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+    chainId?: NetworkId | undefined
+    /** The deadline that elapsed (the configured marker timeout). */
+    timeoutMs: number
+    /** switchNetwork only: target chain already the active one (no-op switch). */
+    targetAlreadyActive?: boolean | undefined
+  }
+
+  // ---- Provider lifecycle (telemetry-only) ----------------------------------
+  // Post-connect changes the wallet reports on its own (the user switched account
+  // or chain IN the wallet, the wallet disconnected, a session expired). Address
+  // is DROPPED at the connector boundary; these carry routing facets only.
+
+  /** The wallet's active account/list changed. Signals THAT it changed, not which. */
+  walletAccountChanged: {
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+  }
+  /**
+   * The wallet switched chain on its own. Deduped against the echo of a
+   * UWC-initiated `switchNetwork` (which already surfaces via `networkSwitched`).
+   */
+  walletChainChanged: {
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+    chainId?: NetworkId | undefined
+  }
+  /** The wallet disconnected the session from its side. */
+  walletDisconnected: {
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+  }
+  /** A WalletConnect / TON session expired. */
+  walletSessionExpired: {
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+  }
+  /**
+   * Lifecycle telemetry could not be attached for this connection — emitted once
+   * so analytics can tell "genuinely silent" from "never wired". Carries WHY +
+   * whether the runtime is the direct page or the production iframe.
+   */
+  lifecycleTelemetryUnavailable: {
+    reason: LifecycleUnavailableReason
+    connectionMode: ConnectionMode
+    walletId?: string | undefined
+    namespace?: Namespace | undefined
+    runtime: 'direct' | 'iframe'
+  }
+
+  /**
+   * The page was backgrounded (tab hidden / app-switched) while a wallet handoff
+   * was still pending. Telemetry-only. On mobile this usually means the user
+   * left for the wallet app — a deep-link round-trip in progress, not an
+   * abandonment. UWC emits the raw FACT only; never an interpreted "abandoned".
+   */
+  pageHiddenDuringHandoff: { handoffId: string; platform: Platform }
+  /**
+   * The page became visible again (returned from the wallet / bfcache restore)
+   * while a handoff was still pending. Pairs with `pageHiddenDuringHandoff` to
+   * bracket an app-switch — consecutive same-state transitions are deduped per
+   * handoff (a bfcache restore can fire both `pageshow` and `visibilitychange`
+   * for one physical return). Telemetry-only.
+   */
+  pageVisibleDuringHandoff: { handoffId: string; platform: Platform }
 
   /**
    * Back-compat catch-all. Fires after every other event above.
@@ -67,7 +316,70 @@ export interface UWCEventMap {
   change: void
 }
 
+/**
+ * Events that describe telemetry rather than a state change. `EventManager.emit`
+ * skips the legacy `change` cascade for these so high-frequency logging / handoff
+ * instrumentation can't trigger React re-renders through `subscribe()`.
+ */
+export const TELEMETRY_ONLY_EVENTS: ReadonlySet<UWCEventName> = new Set([
+  'log',
+  'awaitingWallet',
+  'walletSucceeded',
+  'walletRejected',
+  'walletFailed',
+  'walletTimedOut',
+  'walletDiscoveryFailed',
+  'bridgeError',
+  'relayError',
+  'walletAccountChanged',
+  'walletChainChanged',
+  'walletDisconnected',
+  'walletSessionExpired',
+  'lifecycleTelemetryUnavailable',
+  'pageHiddenDuringHandoff',
+  'pageVisibleDuringHandoff'
+])
+
 export type UWCEventName = keyof UWCEventMap
 export type UWCEventListener<K extends UWCEventName> = (
   data: UWCEventMap[K]
 ) => void
+
+/**
+ * Runtime list of every event name. The `Record<UWCEventName, true>` literal
+ * forces this to stay exhaustive — adding an event to `UWCEventMap` without
+ * listing it here is a compile error — so the observer bridge can never silently
+ * drop a new event.
+ */
+const EVENT_NAME_FLAGS: Record<UWCEventName, true> = {
+  ready: true,
+  walletsDetected: true,
+  walletDiscoveryFailed: true,
+  bridgeError: true,
+  relayError: true,
+  connecting: true,
+  connected: true,
+  disconnected: true,
+  connectionUri: true,
+  sessionChanged: true,
+  networkSwitching: true,
+  networkSwitched: true,
+  capabilitiesUpdated: true,
+  error: true,
+  log: true,
+  awaitingWallet: true,
+  walletSucceeded: true,
+  walletRejected: true,
+  walletFailed: true,
+  walletTimedOut: true,
+  walletAccountChanged: true,
+  walletChainChanged: true,
+  walletDisconnected: true,
+  walletSessionExpired: true,
+  lifecycleTelemetryUnavailable: true,
+  pageHiddenDuringHandoff: true,
+  pageVisibleDuringHandoff: true,
+  change: true
+}
+
+export const UWC_EVENT_NAMES = Object.keys(EVENT_NAME_FLAGS) as UWCEventName[]

package/src/index.ts

@@ -9,4 +9,14 @@ export type {
   UWCEventListener,
   UWCOperation
 } from './events'
+export {
+  createLogger,
+  type ManagedLogger,
+  type CreateLoggerOptions
+} from './logger/create-logger'
+export {
+  TELEMETRY_SCHEMA_VERSION,
+  type UWCObserver,
+  type UWCTelemetryEvent
+} from './observability/telemetry'
 export { toBaseUnits } from './utils/to-base-units'

package/src/logger/create-logger.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import type { Logger } from '@meshconnect/uwc-types'
+import { createLogger } from './create-logger'
+
+function makeSink(): Logger & { calls: Record<string, unknown[][]> } {
+  const calls: Record<string, unknown[][]> = {
+    debug: [],
+    info: [],
+    warn: [],
+    error: []
+  }
+  return {
+    calls,
+    debug: (...a) => calls.debug.push(a),
+    info: (...a) => calls.info.push(a),
+    warn: (...a) => calls.warn.push(a),
+    error: (...a) => calls.error.push(a)
+  }
+}
+
+describe('createLogger', () => {
+  afterEach(() => {
+    delete (globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG
+    vi.restoreAllMocks()
+  })
+
+  it('gates the console sink by level (default warn)', () => {
+    const sink = makeSink()
+    const log = createLogger({ sink })
+    log.debug('d')
+    log.info('i')
+    log.warn('w')
+    log.error('e')
+    expect(sink.calls.debug).toHaveLength(0)
+    expect(sink.calls.info).toHaveLength(0)
+    expect(sink.calls.warn).toHaveLength(1)
+    expect(sink.calls.error).toHaveLength(1)
+  })
+
+  it('fires onLog for EVERY level, pre-gate (even below the console threshold)', () => {
+    const onLog = vi.fn()
+    const sink = makeSink()
+    const log = createLogger({ level: 'error', sink, onLog })
+    log.debug('d', 1)
+    log.error('e')
+    // onLog sees both; the sink only sees error.
+    expect(onLog).toHaveBeenCalledTimes(2)
+    expect(onLog).toHaveBeenNthCalledWith(1, 'debug', 'd', [1])
+    expect(sink.calls.debug).toHaveLength(0)
+    expect(sink.calls.error).toHaveLength(1)
+  })
+
+  it('passes raw (message, ...args) to a custom sink — no ISO prefix', () => {
+    const sink = makeSink()
+    const log = createLogger({ level: 'debug', sink })
+    log.warn('hello', { a: 1 })
+    expect(sink.calls.warn[0]).toEqual(['hello', { a: 1 }])
+  })
+
+  it('formats with an ISO/level prefix for the default console sink', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const log = createLogger({ level: 'warn' })
+    log.warn('boom', 42)
+    const firstArg = spy.mock.calls[0]?.[0] as string
+    expect(firstArg).toMatch(/WARN: boom$/)
+    expect(spy.mock.calls[0]?.[1]).toBe(42)
+  })
+
+  it('setLevel changes the threshold at runtime', () => {
+    const sink = makeSink()
+    const log = createLogger({ level: 'error', sink })
+    log.info('before')
+    expect(sink.calls.info).toHaveLength(0)
+    log.setLevel('debug')
+    log.info('after')
+    expect(sink.calls.info).toHaveLength(1)
+    expect(log.getLevel()).toBe('debug')
+  })
+
+  it('honours the global UWC_DEBUG override (true ⇒ debug) without recreation', () => {
+    const sink = makeSink()
+    const log = createLogger({ level: 'error', sink })
+    log.debug('hidden')
+    expect(sink.calls.debug).toHaveLength(0)
+    ;(globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG = true
+    log.debug('shown')
+    expect(sink.calls.debug).toHaveLength(1)
+  })
+
+  it('a string UWC_DEBUG override only lowers the threshold, never raises it', () => {
+    const sink = makeSink()
+    const log = createLogger({ level: 'debug', sink })
+    ;(globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG = 'error'
+    // configured=debug, override=error → effective stays debug (min of the two).
+    log.debug('still shown')
+    expect(sink.calls.debug).toHaveLength(1)
+  })
+
+  it('ignores an inherited-key UWC_DEBUG override (e.g. "toString") — gating stays intact', () => {
+    const sink = makeSink()
+    const log = createLogger({ level: 'warn', sink })
+    // `'toString' in LEVEL_WEIGHT` is true via the prototype chain; treating it
+    // as a level would compute Math.min(fn, number) = NaN and hold the gate
+    // open for EVERY level. Garbage input must stay inert instead.
+    ;(globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG = 'toString'
+    log.debug('hidden')
+    log.info('hidden')
+    expect(sink.calls.debug).toHaveLength(0)
+    expect(sink.calls.info).toHaveLength(0)
+    log.warn('shown')
+    expect(sink.calls.warn).toHaveLength(1)
+  })
+
+  it('swallows a throwing onLog so the log call never breaks', () => {
+    const sink = makeSink()
+    const log = createLogger({
+      level: 'warn',
+      sink,
+      onLog: () => {
+        throw new Error('sink boom')
+      }
+    })
+    expect(() => log.warn('ok')).not.toThrow()
+    expect(sink.calls.warn).toHaveLength(1)
+  })
+})

package/src/logger/create-logger.ts

@@ -0,0 +1,112 @@
+import type { LogLevel, Logger } from '@meshconnect/uwc-types'
+
+const LEVEL_WEIGHT: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+}
+
+/** The logger returned by `createLogger`, with runtime-tunable level controls. */
+export interface ManagedLogger extends Logger {
+  /** Lower/raise the console threshold at runtime (e.g. from a support toggle). */
+  setLevel(level: LogLevel): void
+  /** The currently configured threshold (ignores the global override). */
+  getLevel(): LogLevel
+}
+
+export interface CreateLoggerOptions {
+  /** Console threshold. Default `'warn'` — UWC stays quiet unless asked. */
+  level?: LogLevel | undefined
+  /**
+   * Pre-gate tap: invoked for EVERY log line regardless of the console threshold.
+   * The observer bridge subscribes here so `debug`/`info` reach remote telemetry
+   * even when the console is silent. Throws are swallowed — a bad sink must not
+   * break a log call.
+   */
+  onLog?:
+    | ((level: LogLevel, message: string, args: unknown[]) => void)
+    | undefined
+  /**
+   * Output sink for gated lines. When provided (e.g. a consumer's own logger), it
+   * receives the RAW `(message, ...args)` so it can apply its own formatting. When
+   * omitted, the default `console` sink is used with an ISO/level prefix.
+   */
+  sink?: Logger | undefined
+}
+
+/**
+ * Resolve the effective console threshold, honouring a runtime global override so
+ * an issue can be triaged in a wallet's in-app browser WITHOUT a redeploy:
+ *
+ *   window.UWC_DEBUG = true        // surface everything (debug)
+ *   window.UWC_DEBUG = 'info'      // surface info and above
+ *
+ * The override only ever LOWERS the threshold (shows more) — it can't hide logs a
+ * consumer explicitly opted into. Re-read on every call so toggling it mid-session
+ * takes effect immediately. SSR/Node-safe via the `globalThis` guard.
+ */
+function resolveWeight(configured: LogLevel): number {
+  if (typeof globalThis !== 'undefined') {
+    const override = (globalThis as { UWC_DEBUG?: unknown }).UWC_DEBUG
+    if (override === true) return LEVEL_WEIGHT.debug
+    // Own-property check, not `in`: the prototype chain would accept keys like
+    // 'toString', whose "weight" is a function → NaN → the gate never closes.
+    if (
+      typeof override === 'string' &&
+      Object.prototype.hasOwnProperty.call(LEVEL_WEIGHT, override)
+    ) {
+      return Math.min(
+        LEVEL_WEIGHT[override as LogLevel],
+        LEVEL_WEIGHT[configured]
+      )
+    }
+  }
+  return LEVEL_WEIGHT[configured]
+}
+
+/**
+ * Console-backed, level-gated logger. ~zero-dep. Two seams:
+ *  - `onLog` fires pre-gate (all levels) → drives the observer.
+ *  - the console sink fires only at/above the threshold.
+ */
+export function createLogger(options: CreateLoggerOptions = {}): ManagedLogger {
+  let configured: LogLevel = options.level ?? 'warn'
+  const customSink = options.sink
+
+  const emit = (level: LogLevel, message: string, args: unknown[]): void => {
+    // Pre-gate tap first — observability must not depend on the console threshold.
+    if (options.onLog) {
+      try {
+        options.onLog(level, message, args)
+      } catch {
+        // A failing sink must never break the caller's log statement.
+      }
+    }
+    if (LEVEL_WEIGHT[level] < resolveWeight(configured)) return
+    // Same contract as the `onLog` tap above: the sink (a consumer logger or the
+    // console) must never break the caller's log statement if it throws.
+    try {
+      if (customSink) {
+        customSink[level](message, ...args)
+      } else {
+        const line = `[${new Date().toISOString()}] ${level.toUpperCase()}: ${message}`
+        // eslint-disable-next-line no-console -- this IS the default console sink
+        console[level](line, ...args)
+      }
+    } catch {
+      // Swallowed by design — a broken sink is not the caller's problem.
+    }
+  }
+
+  return {
+    debug: (message, ...args) => emit('debug', message, args),
+    info: (message, ...args) => emit('info', message, args),
+    warn: (message, ...args) => emit('warn', message, args),
+    error: (message, ...args) => emit('error', message, args),
+    setLevel: level => {
+      configured = level
+    },
+    getLevel: () => configured
+  }
+}

package/src/managers/event-manager.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest'
 import { EventManager } from './event-manager'
+import { TELEMETRY_ONLY_EVENTS, UWC_EVENT_NAMES } from '../events'
 
 describe('EventManager', () => {
   let eventManager: EventManager
@@ -140,5 +141,59 @@ describe('EventManager', () => {
       eventManager.emit('change', undefined)
       expect(count).toBe(1)
     })
+
+    it('telemetry-only events do NOT cascade to the legacy change channel', () => {
+      let changeCount = 0
+      eventManager.subscribe(() => {
+        changeCount++
+      })
+      eventManager.emit('log', { level: 'debug', message: 'x', args: [] })
+      eventManager.emit('walletTimedOut', {
+        handoffId: 'h',
+        operation: 'signMessage',
+        durationMs: 1,
+        connectionMode: 'injected',
+        timeoutMs: 1000
+      })
+      // Neither should have triggered a re-render via `change`.
+      expect(changeCount).toBe(0)
+    })
+
+    it('state-change events still cascade to change alongside telemetry events', () => {
+      let changeCount = 0
+      eventManager.subscribe(() => {
+        changeCount++
+      })
+      eventManager.emit('log', { level: 'debug', message: 'x', args: [] })
+      eventManager.emit('disconnected', undefined)
+      expect(changeCount).toBe(1)
+    })
+
+    // Classification guard: a new bus event must be CONSCIOUSLY categorized.
+    // `TELEMETRY_ONLY_EVENTS` is a hand-maintained Set (not compile-enforced like
+    // EVENT_NAME_FLAGS), so an event added to the map but forgotten there would
+    // silently cascade to `change` and trigger React re-renders. This partition
+    // fails on that omission — forcing the author to declare telemetry vs state.
+    it('every bus event is classified as telemetry-only or state-change', () => {
+      const stateChangeEvents = [
+        'ready',
+        'walletsDetected',
+        'connecting',
+        'connected',
+        'disconnected',
+        'connectionUri',
+        'sessionChanged',
+        'networkSwitching',
+        'networkSwitched',
+        'capabilitiesUpdated',
+        'error'
+      ]
+      const classified = new Set<string>([
+        ...TELEMETRY_ONLY_EVENTS,
+        ...stateChangeEvents,
+        'change'
+      ])
+      expect([...classified].sort()).toEqual([...UWC_EVENT_NAMES].sort())
+    })
   })
 })