@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/services/connection-service.test.ts

@@ -8,6 +8,8 @@ import type {
   ConnectionMode,
   Connector
 } from '@meshconnect/uwc-types'
+import { NoCommonNetworkError } from '@meshconnect/uwc-types'
+import type { WalletLifecycleEvent } from '@meshconnect/uwc-types'
 
 describe('ConnectionService', () => {
   let connectionService: ConnectionService
@@ -81,7 +83,8 @@ describe('ConnectionService', () => {
       sessionManager,
       connectors,
       false,
-      eventManager
+      eventManager,
+      60_000
     )
   })
 
@@ -123,6 +126,28 @@ describe('ConnectionService', () => {
     }).toThrow('Network eip155:8453 is not in the configured networks')
   })
 
+  it('throws a typed NoCommonNetworkError with both CAIP-2 lists (delta A)', () => {
+    // No networkId arg → the auto-select branch. The wallet supports only a
+    // chain that isn't configured, so there is no overlap: the #1 prod failure.
+    const mockProvider = {
+      supportedNetworkIds: ['solana:101', 'tron:0x2b6653dc']
+    }
+    let thrown: unknown
+    try {
+      connectionService['validateAndDetermineNetwork'](
+        undefined,
+        mockProvider as any
+      )
+    } catch (e) {
+      thrown = e
+    }
+    expect(thrown).toBeInstanceOf(NoCommonNetworkError)
+    const err = thrown as NoCommonNetworkError
+    expect(err.walletNetworkIds).toEqual(['solana:101', 'tron:0x2b6653dc'])
+    // configuredNetworkIds is whatever the suite configured (includes eip155:1).
+    expect(err.configuredNetworkIds).toContain('eip155:1')
+  })
+
   it('should get connector by mode', () => {
     const connector = connectionService['getConnector']('injected')
     expect(connector).toBe(mockConnector)
@@ -193,6 +218,70 @@ describe('ConnectionService', () => {
       expect(connectingListener).not.toHaveBeenCalled()
     })
 
+    it('does NOT emit awaitingWallet when validation throws (pre-wallet failure stays out of the funnel)', async () => {
+      const awaiting = vi.fn()
+      const failed = vi.fn()
+      eventManager.on('awaitingWallet', awaiting)
+      eventManager.on('walletFailed', failed)
+
+      await expect(
+        connectionService.connect('injected', 'no-such-wallet', 'eip155:1')
+      ).rejects.toThrow()
+
+      expect(awaiting).not.toHaveBeenCalled()
+      expect(failed).not.toHaveBeenCalled()
+    })
+
+    it('emits awaitingWallet + walletSucceeded around the wallet call, with resolved facets', async () => {
+      wallets[0].extensionInjectedProvider = {
+        supportedNetworkIds: ['eip155:1']
+      } as any
+      const events: Array<{ name: string; data: any }> = []
+      eventManager.on('awaitingWallet', d =>
+        events.push({ name: 'awaitingWallet', data: d })
+      )
+      eventManager.on('walletSucceeded', d =>
+        events.push({ name: 'walletSucceeded', data: d })
+      )
+      mockConnector.connect = vi.fn().mockResolvedValue({
+        networkId: 'eip155:1',
+        address: '0x1234',
+        availableAddresses: [{ address: '0x1234', networkId: 'eip155:1' }]
+      })
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+
+      expect(events.map(e => e.name)).toEqual([
+        'awaitingWallet',
+        'walletSucceeded'
+      ])
+      const awaiting = events[0].data
+      expect(awaiting.operation).toBe('connect')
+      expect(awaiting.namespace).toBe('eip155')
+      expect(awaiting.chainId).toBe('eip155:1')
+      expect(awaiting.handoffId).toBe(events[1].data.handoffId)
+    })
+
+    it('emits awaitingWallet + walletFailed when the connector call throws', async () => {
+      wallets[0].extensionInjectedProvider = {
+        supportedNetworkIds: ['eip155:1']
+      } as any
+      const awaiting = vi.fn()
+      const failed = vi.fn()
+      eventManager.on('awaitingWallet', awaiting)
+      eventManager.on('walletFailed', failed)
+      mockConnector.connect = vi
+        .fn()
+        .mockRejectedValue(new Error('wallet exploded'))
+
+      await expect(
+        connectionService.connect('injected', 'metamask', 'eip155:1')
+      ).rejects.toThrow('wallet exploded')
+
+      expect(awaiting).toHaveBeenCalledTimes(1)
+      expect(failed).toHaveBeenCalledTimes(1)
+    })
+
     it('rejects mid-flight when AbortSignal fires during connector.connect', async () => {
       wallets[0].extensionInjectedProvider = {
         supportedNetworkIds: ['eip155:1']
@@ -604,4 +693,175 @@ describe('ConnectionService', () => {
       expect(connectionService['activeConnector']).toBeNull()
     })
   })
+
+  describe('lifecycle wiring (P2)', () => {
+    beforeEach(() => {
+      wallets[0].extensionInjectedProvider = {
+        supportedNetworkIds: ['eip155:1']
+      } as any
+      mockConnector.connect = vi.fn().mockResolvedValue({
+        networkId: 'eip155:1',
+        address: '0x1234',
+        availableAddresses: [{ address: '0x1234', networkId: 'eip155:1' }]
+      })
+    })
+
+    it('subscribes to connector lifecycle after connect and tears down on disconnect', async () => {
+      let emit: ((e: WalletLifecycleEvent) => void) | undefined
+      let receivedContext: unknown
+      let unsubbed = false
+      mockConnector.onLifecycleEvent = (
+        l: (e: WalletLifecycleEvent) => void,
+        context: unknown
+      ) => {
+        emit = l
+        receivedContext = context
+        return () => {
+          unsubbed = true
+        }
+      }
+      const accounts: unknown[] = []
+      eventManager.on('walletAccountChanged', d => accounts.push(d))
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      emit?.({ type: 'accountChanged' })
+      expect(accounts).toHaveLength(1)
+      // The core TELLS the connector which session it is attaching for — the
+      // connector must never infer it from ambient state.
+      expect(receivedContext).toEqual({
+        connectionMode: 'injected',
+        namespace: 'eip155',
+        walletId: 'metamask'
+      })
+
+      await connectionService.disconnect()
+      expect(unsubbed).toBe(true)
+    })
+
+    it('teardownLifecycle() releases the subscription without disconnecting (the dispose path)', async () => {
+      let emit: ((e: WalletLifecycleEvent) => void) | undefined
+      let unsubCount = 0
+      mockConnector.onLifecycleEvent = (
+        l: (e: WalletLifecycleEvent) => void
+      ) => {
+        emit = l
+        return () => {
+          unsubCount++
+        }
+      }
+      const accounts: unknown[] = []
+      eventManager.on('walletAccountChanged', d => accounts.push(d))
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      emit?.({ type: 'accountChanged' })
+      expect(accounts).toHaveLength(1)
+
+      // dispose() takes THIS path, not disconnect() — the live provider listeners
+      // must still be released, or they leak (the zombie-listener bug class).
+      connectionService.teardownLifecycle()
+      expect(unsubCount).toBe(1)
+
+      // Idempotent: a later disconnect() (which also tears down) is a safe no-op.
+      connectionService.teardownLifecycle()
+      expect(unsubCount).toBe(1)
+    })
+
+    it('emits lifecycleTelemetryUnavailable when the connector cannot observe', async () => {
+      // mockConnector has no onLifecycleEvent in this case.
+      const unavail: unknown[] = []
+      eventManager.on('lifecycleTelemetryUnavailable', d => unavail.push(d))
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+
+      expect(unavail).toHaveLength(1)
+    })
+
+    it('reattachLifecycle() swaps the subscription for the current session (cross-namespace switch path)', async () => {
+      // After a cross-namespace switchNetwork the live provider changes; the
+      // façade calls this so lifecycle follows the ACTIVE namespace instead of
+      // staying pinned to the connect-time provider.
+      const subscribers: Array<(e: WalletLifecycleEvent) => void> = []
+      let unsubCount = 0
+      mockConnector.onLifecycleEvent = (
+        l: (e: WalletLifecycleEvent) => void
+      ) => {
+        subscribers.push(l)
+        return () => {
+          unsubCount++
+        }
+      }
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      expect(subscribers).toHaveLength(1)
+
+      connectionService.reattachLifecycle()
+
+      // Old subscription released, a fresh one attached — never two live at once.
+      expect(unsubCount).toBe(1)
+      expect(subscribers).toHaveLength(2)
+    })
+
+    it('releases activeConnector when an abort lands AFTER the wallet settled (post-funnel gap)', async () => {
+      // raceAbort covers aborts DURING the wallet call; this covers the window
+      // between the funnel resolving and the trailing throwIfAborted. The
+      // half-attached connector must be released, or a later caller reads a
+      // stale connection URI from an attempt that never became a session.
+      const controller = new AbortController()
+      mockConnector.connect = vi.fn().mockResolvedValue({
+        networkId: 'eip155:1',
+        address: '0x1234',
+        availableAddresses: []
+      })
+      mockConnector.getConnectionURI = vi.fn().mockReturnValue('uri://stale')
+      // walletSucceeded is emitted synchronously after the wallet settles and
+      // before the post-funnel abort check — abort exactly in that window.
+      eventManager.on('walletSucceeded', () => controller.abort())
+
+      await expect(
+        connectionService.connect('injected', 'metamask', 'eip155:1', {
+          signal: controller.signal
+        })
+      ).rejects.toMatchObject({ name: 'AbortError' })
+
+      expect(connectionService.getConnectionURI()).toBeUndefined()
+      // And the session was never mutated by the aborted attempt.
+      expect(sessionManager.getSession().activeWallet).toBeNull()
+    })
+
+    it('reattachLifecycle() seeds echo suppression for the just-active chain', async () => {
+      // The reattach happens AFTER a switch completed, so the fresh lifecycle
+      // closure never saw that switch's bus events — without a seed, the new
+      // namespace's provider echo would surface as a wallet-initiated change.
+      const subscribers: Array<(e: WalletLifecycleEvent) => void> = []
+      mockConnector.onLifecycleEvent = (
+        l: (e: WalletLifecycleEvent) => void
+      ) => {
+        subscribers.push(l)
+        return () => {}
+      }
+      const seen: unknown[] = []
+      eventManager.on('walletChainChanged', d => seen.push(d))
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      connectionService.reattachLifecycle()
+
+      // The re-attached provider echoes the just-completed switch → suppressed…
+      subscribers[1]!({ type: 'chainChanged', chainId: 'eip155:1' })
+      expect(seen).toHaveLength(0)
+
+      // …and consumed: a later same-chain change is genuine and surfaces.
+      subscribers[1]!({ type: 'chainChanged', chainId: 'eip155:1' })
+      expect(seen).toHaveLength(1)
+    })
+
+    it('reattachLifecycle() is a safe no-op when nothing is connected', () => {
+      const unavail: unknown[] = []
+      eventManager.on('lifecycleTelemetryUnavailable', d => unavail.push(d))
+
+      expect(() => connectionService.reattachLifecycle()).not.toThrow()
+
+      // No connection → no lifecycle evaluation, so no "unavailable" noise.
+      expect(unavail).toHaveLength(0)
+    })
+  })
 })

package/src/services/connection-service.ts

@@ -1,6 +1,7 @@
 import type {
   Network,
   NetworkId,
+  Namespace,
   WalletMetadata,
   ConnectionMode,
   Connector,
@@ -10,9 +11,12 @@ import type {
   IntegratedBrowserInjectedProvider,
   TonConnectWalletProvider
 } from '@meshconnect/uwc-types'
+import { NoCommonNetworkError } from '@meshconnect/uwc-types'
 import type { SessionManager } from '../managers/session-manager'
 import type { EventManager } from '../managers/event-manager'
 import { raceAbort } from '../utils/abort'
+import { instrumentHandoff } from '../observability/instrument-handoff'
+import { attachLifecycle } from '../observability/lifecycle-bridge'
 
 export interface ServiceOptions {
   signal?: AbortSignal
@@ -20,6 +24,8 @@ export interface ServiceOptions {
 
 export class ConnectionService {
   private activeConnector: Connector | null = null
+  /** Tears down the post-connect lifecycle subscription; set while connected. */
+  private lifecycleTeardown: (() => void) | undefined
 
   constructor(
     private networks: Network[],
@@ -27,7 +33,9 @@ export class ConnectionService {
     private sessionManager: SessionManager,
     private connectors: Map<ConnectionMode, Connector>,
     private usingIntegratedBrowser: boolean,
-    private eventManager: EventManager
+    private eventManager: EventManager,
+    // Observational wallet-response deadline for the handoff timeout marker.
+    private walletResponseTimeoutMs: number
   ) {}
 
   async connect(
@@ -60,46 +68,67 @@ export class ConnectionService {
 
     let result
     try {
-      // Race the connector call against the AbortSignal so a mid-flight abort
-      // (e.g. user cancels the WalletConnect QR while the prompt is open)
-      // rejects the caller's await promptly. The underlying wallet prompt
-      // itself can't be cancelled, but the dapp UI is no longer blocked on it.
-      if (connectionMode === 'injected') {
-        result = await raceAbort(
-          connector.connect(
-            network,
-            provider as
-              | ExtensionInjectedProvider
-              | IntegratedBrowserInjectedProvider
-          ),
-          options?.signal
-        )
-      } else if (
-        connectionMode === 'tonConnect' ||
-        connectionMode === 'walletConnect'
-      ) {
-        result = await raceAbort(
-          this.connectWithURIPoll(
-            connector,
-            network,
-            provider,
-            connectionMode,
-            options?.signal
-          ),
-          options?.signal
-        )
-      } else {
-        throw new Error(`Unsupported connection mode: ${connectionMode}`)
-      }
+      // Instrument the wallet hand-off HERE — after validation + the `connecting`
+      // emit — so `awaitingWallet` marks the real wallet boundary. A pre-wallet
+      // lookup/validation failure throws above and never enters the funnel. The
+      // resolved `network` gives accurate namespace/chainId facets.
+      result = await instrumentHandoff(
+        {
+          eventManager: this.eventManager,
+          timeoutMs: this.walletResponseTimeoutMs,
+          signal: options?.signal
+        },
+        {
+          operation: 'connect',
+          connectionMode,
+          walletId,
+          namespace: network.namespace,
+          chainId: network.id
+        },
+        async () => {
+          // Race the connector call against the AbortSignal so a mid-flight abort
+          // (e.g. user cancels the WalletConnect QR while the prompt is open)
+          // rejects the caller's await promptly. The underlying wallet prompt
+          // itself can't be cancelled, but the dapp UI is no longer blocked on it.
+          if (connectionMode === 'injected') {
+            return await raceAbort(
+              connector.connect(
+                network,
+                provider as
+                  | ExtensionInjectedProvider
+                  | IntegratedBrowserInjectedProvider
+              ),
+              options?.signal
+            )
+          } else if (
+            connectionMode === 'tonConnect' ||
+            connectionMode === 'walletConnect'
+          ) {
+            return await raceAbort(
+              this.connectWithURIPoll(
+                connector,
+                network,
+                provider,
+                connectionMode,
+                options?.signal
+              ),
+              options?.signal
+            )
+          } else {
+            throw new Error(`Unsupported connection mode: ${connectionMode}`)
+          }
+        }
+      )
+      // Belt-and-suspenders: if the signal fired between raceAbort resolving
+      // and this point, still bail before mutating session. Inside the try so
+      // the half-attached connector is released on this late abort too — a
+      // stale activeConnector would keep serving the aborted attempt's URI.
+      options?.signal?.throwIfAborted()
     } catch (error) {
       this.activeConnector = null
       throw error
     }
 
-    // Belt-and-suspenders: if the signal fired between raceAbort resolving
-    // and this point, still bail before mutating session.
-    options?.signal?.throwIfAborted()
-
     // Filter available addresses to only include those for configured networks
     const filteredAvailableAddresses = result.availableAddresses.filter(addr =>
       this.networks.some(n => n.id === addr.networkId)
@@ -120,6 +149,99 @@ export class ConnectionService {
     const session = this.sessionManager.getSession()
     this.eventManager.emit('connected', { session })
     this.eventManager.emit('sessionChanged', { session })
+
+    // Observe post-connect wallet lifecycle (account/chain switch in the wallet,
+    // disconnect, expiry) from the live provider — telemetry only, never changes
+    // connection behaviour. Torn down on disconnect.
+    this.attachLifecycle(connectionMode, wallet.id, network.namespace)
+  }
+
+  /** Wire the active connector's lifecycle stream onto the bus (or signal absence). */
+  private attachLifecycle(
+    connectionMode: ConnectionMode,
+    walletId: string,
+    namespace: Namespace,
+    initialSwitch?: { chainId: NetworkId; at: number }
+  ): void {
+    this.teardownLifecycle()
+    const connector = this.activeConnector
+    this.lifecycleTeardown = attachLifecycle({
+      eventManager: this.eventManager,
+      // Reattach-after-switch only: seed echo suppression, because the fresh
+      // subscription never saw the completed switch's bus events.
+      ...(initialSwitch && { initialSwitch }),
+      // The context names the session being attached FOR — the connector routes
+      // by it (never by its own ambient state, which is ambiguous when the
+      // secondary-namespace gather left several live surfaces).
+      subscribe: connector?.onLifecycleEvent
+        ? listener =>
+            connector.onLifecycleEvent!(listener, {
+              connectionMode,
+              namespace,
+              walletId
+            })
+        : undefined,
+      getRouting: () => {
+        const s = this.sessionManager.getSession()
+        return {
+          connectionMode: s.connectionMode ?? connectionMode,
+          walletId: s.activeWallet?.id ?? walletId,
+          namespace: s.activeNetwork?.namespace ?? namespace
+        }
+      },
+      connectionMode,
+      walletId,
+      namespace,
+      // The bridge child sets this when UWC runs inside the Link iframe; it tells
+      // a `lifecycleTelemetryUnavailable` consumer whether lifecycle was silent on
+      // the direct page or (expected, pending P3) over the production bridge.
+      runtime:
+        (globalThis as { UWCBridgeChildInitialized?: boolean })
+          .UWCBridgeChildInitialized === true
+          ? 'iframe'
+          : 'direct'
+    })
+  }
+
+  /**
+   * Remove the active provider-lifecycle subscription (EIP-1193 `.on` / wallet-
+   * adapter / SignClient listeners) WITHOUT disconnecting the wallet. Idempotent.
+   * Exposed so a full `dispose()` that bypasses `disconnect()` still releases these
+   * listeners — leaving them attached is the zombie-listener class this layer
+   * exists to prevent.
+   */
+  teardownLifecycle(): void {
+    this.lifecycleTeardown?.()
+    this.lifecycleTeardown = undefined
+  }
+
+  /**
+   * Re-evaluate the lifecycle source for the CURRENT session. Used after a
+   * cross-namespace switchNetwork: the live provider changes with the namespace,
+   * so the connect-time subscription would keep observing the old namespace's
+   * provider and label its events with the new session's routing. Tears the old
+   * subscription down and re-attaches against the active session's facets.
+   * Safe no-op when nothing is connected.
+   */
+  reattachLifecycle(): void {
+    const session = this.sessionManager.getSession()
+    if (
+      !this.activeConnector ||
+      !session.connectionMode ||
+      !session.activeWallet ||
+      !session.activeNetwork
+    ) {
+      return
+    }
+    this.attachLifecycle(
+      session.connectionMode,
+      session.activeWallet.id,
+      session.activeNetwork.namespace,
+      // The reattach follows a JUST-completed switch to the now-active chain —
+      // arm echo suppression for it so the new provider's echo isn't mistaken
+      // for a wallet-initiated change (one-shot, same as bus-armed switches).
+      { chainId: session.activeNetwork.id, at: Date.now() }
+    )
   }
 
   private async connectWithURIPoll(
@@ -264,8 +386,12 @@ export class ConnectionService {
         this.networks.some(n => n.id === id)
       )
       if (!supportedNetwork) {
-        throw new Error(
-          'No common supported network found between wallet and configured networks'
+        // The #1 production connection failure. Throw a typed, self-describing
+        // error carrying both CAIP-2 id lists (non-PII) so telemetry can tell a
+        // metadata gap from a client-config mistake — see NoCommonNetworkError.
+        throw new NoCommonNetworkError(
+          provider.supportedNetworkIds,
+          this.networks.map(n => n.id)
         )
       }
       targetNetworkId = supportedNetwork
@@ -283,6 +409,9 @@ export class ConnectionService {
 
   async disconnect(options?: ServiceOptions): Promise<void> {
     options?.signal?.throwIfAborted()
+    // Remove the lifecycle listeners first so a provider 'disconnect' fired during
+    // teardown doesn't re-enter as a wallet-initiated `walletDisconnected`.
+    this.teardownLifecycle()
     try {
       if (
         this.activeConnector &&

package/src/services/network-switch-service.test.ts

@@ -84,7 +84,8 @@ describe('NetworkSwitchService', () => {
       sessionManager,
       connectors,
       false,
-      eventManager
+      eventManager,
+      60_000
     )
   })
 
@@ -184,4 +185,53 @@ describe('NetworkSwitchService', () => {
       "Wallet 'metamask' does not have a provider for injected mode"
     )
   })
+
+  it('does NOT emit awaitingWallet when validation throws (no active wallet)', async () => {
+    const awaiting = vi.fn()
+    eventManager.on('awaitingWallet', awaiting)
+
+    await expect(
+      networkSwitchService.switchNetwork('eip155:1')
+    ).rejects.toThrow()
+
+    expect(awaiting).not.toHaveBeenCalled()
+  })
+
+  it('emits awaitingWallet + walletSucceeded around the wallet switch call', async () => {
+    sessionManager.updateSession({
+      connectionMode: 'injected',
+      activeWallet: {
+        id: 'metamask',
+        name: 'MetaMask',
+        metadata: {
+          icon: 'test',
+          downloadUrl: 'test',
+          supportedChains: ['eip155:1', 'eip155:137']
+        },
+        extensionInjectedProvider: {
+          supportedNetworkIds: ['eip155:1', 'eip155:137']
+        }
+      } as any
+    })
+    mockConnector.switchNetwork = vi.fn().mockResolvedValue({
+      address: '0xabc',
+      availableAddresses: [{ address: '0xabc', networkId: 'eip155:137' }]
+    })
+    const events: Array<{ name: string; data: any }> = []
+    eventManager.on('awaitingWallet', d =>
+      events.push({ name: 'awaitingWallet', data: d })
+    )
+    eventManager.on('walletSucceeded', d =>
+      events.push({ name: 'walletSucceeded', data: d })
+    )
+
+    await networkSwitchService.switchNetwork('eip155:137')
+
+    expect(events.map(e => e.name)).toEqual([
+      'awaitingWallet',
+      'walletSucceeded'
+    ])
+    expect(events[0].data.operation).toBe('switchNetwork')
+    expect(events[0].data.chainId).toBe('eip155:137')
+  })
 })