@meshconnect/uwc-core 1.0.3 → 1.1.0

package/dist/observability/telemetry.js

@@ -0,0 +1,373 @@
+import { UWC_CORE_VERSION } from '../version';
+import { scrubMessage } from './scrub';
+/**
+ * Telemetry record schema version. Bump on any breaking change to the
+ * `UWCTelemetryEvent` shape so a downstream consumer can branch on it.
+ */
+export const TELEMETRY_SCHEMA_VERSION = 1;
+/**
+ * Egress bounds for `networkMismatch`. `walletNetworkIds` comes from catalog
+ * wallet metadata (`provider.supportedNetworkIds`), not live wallet input — but
+ * it is unbounded upstream, so cap cardinality and element length here as
+ * defense-in-depth. Elements are NOT scrubbed: a legitimate
+ * `solana:<32-char-base58-ref>` CAIP-2 id would be eaten by the base58 rule.
+ */
+const MAX_NETWORK_MISMATCH_IDS = 20;
+const MAX_NETWORK_ID_LENGTH = 64;
+function capNetworkMismatch(mismatch) {
+    if (!mismatch)
+        return undefined;
+    const cap = (ids) => ids
+        .slice(0, MAX_NETWORK_MISMATCH_IDS)
+        .map(id => id.slice(0, MAX_NETWORK_ID_LENGTH));
+    return {
+        walletNetworkIds: cap(mismatch.walletNetworkIds),
+        configuredNetworkIds: cap(mismatch.configuredNetworkIds)
+    };
+}
+/**
+ * Best-effort coarse runtime surface. HEURISTIC — user agents lie and in-app
+ * browsers are hard to detect; treat `webview` as a hint, not a guarantee.
+ * Never returns the raw UA (PII / high-cardinality).
+ */
+export function derivePlatform() {
+    if (typeof navigator === 'undefined' || !navigator.userAgent)
+        return 'unknown';
+    const ua = navigator.userAgent;
+    const isIOS = /iPhone|iPad|iPod/i.test(ua);
+    const isAndroid = /Android/i.test(ua);
+    // Android in-app browsers tag the UA with `; wv`; iOS WKWebViews lack `Safari`.
+    const isWebview = (isAndroid && /; wv\)/i.test(ua)) || (isIOS && !/Safari/i.test(ua));
+    if (isWebview)
+        return 'webview';
+    if (isIOS || isAndroid)
+        return 'mobile';
+    return 'desktop';
+}
+/**
+ * Derive the flow taxonomy from connection mode + surface. HEURISTIC — UWC does
+ * not always know whether a WalletConnect handoff used a deeplink vs a QR scan;
+ * we infer from the platform (mobile ⇒ deeplink, desktop ⇒ QR), matching link-v2's
+ * historical intent. Consumers with better context may override downstream.
+ */
+export function deriveWalletFlowType(connectionMode, platform) {
+    const isDesktop = platform === 'desktop';
+    switch (connectionMode) {
+        case 'injected':
+            // Injected on a phone almost always means we're inside a wallet's browser.
+            return isDesktop ? 'browser_extension_flow' : 'in_wallet_browser_flow';
+        case 'walletConnect':
+            return isDesktop
+                ? 'wallet_connect_qr_flow'
+                : 'wallet_connect_deep_link_flow';
+        case 'tonConnect':
+            return isDesktop ? 'ton_connect_qr_flow' : 'ton_connect_deep_link_flow';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Per-namespace address coverage for a session — telemetry-only, non-PII
+ * (namespace names + counts, never an address). Derived purely from the session:
+ * `availableNetworks` is the connected wallet's supported networks already
+ * filtered to the session's configured set, and `availableAddresses` is what the
+ * connect actually gathered, so `missing` is precise per-connect (no cross-wallet
+ * discovery join that could false-positive on a different installed wallet).
+ *
+ * `missing` is the observable symptom of a dropped secondary-namespace gather:
+ * the wallet supports the namespace for a configured network, but no address for
+ * it came back.
+ */
+function summarizeAddressCoverage(session) {
+    // Defensive `?? []`: this runs on the wallet path, so a partial/malformed
+    // session must never throw here (a real session always has both arrays).
+    const addressNamespaces = {};
+    const present = new Set();
+    for (const { networkId } of session.availableAddresses ?? []) {
+        const namespace = networkId.split(':')[0];
+        if (!namespace)
+            continue;
+        present.add(namespace);
+        addressNamespaces[namespace] = (addressNamespaces[namespace] ?? 0) + 1;
+    }
+    const supported = new Set((session.availableNetworks ?? []).map(n => n.namespace));
+    const missing = [...supported].filter(namespace => !present.has(namespace));
+    return { addressNamespaces, missing };
+}
+/**
+ * Map a raw `UWCEventMap` event to its PII-safe `UWCTelemetryEvent`.
+ *
+ * Per-event allow-listing: only known-safe fields are copied. Payloads carrying a
+ * `Session`/`Network` (which include the wallet address) are reduced to
+ * `namespace` + `chainId` + `walletId`. Unknown/noisy payloads collapse to just
+ * the name. `error.message` is scrubbed.
+ */
+function buildTelemetryEvent(name, data, sdkSessionId, now, correlationId) {
+    // `correlationId` is added to the key only when supplied — never aliased to
+    // `sdkSessionId`, so a consumer can tell "I gave no id" from "id == session".
+    const base = {
+        schemaVersion: TELEMETRY_SCHEMA_VERSION,
+        uwcVersion: UWC_CORE_VERSION,
+        name,
+        sdkSessionId,
+        timestamp: now,
+        ...(correlationId !== undefined ? { correlationId } : {})
+    };
+    switch (name) {
+        case 'connecting': {
+            const d = data;
+            return {
+                ...base,
+                operation: 'connect',
+                connectionMode: d.connectionMode,
+                walletId: d.walletId
+            };
+        }
+        case 'connected':
+        case 'sessionChanged': {
+            const d = data;
+            const session = d.session;
+            const { addressNamespaces, missing } = summarizeAddressCoverage(session);
+            return {
+                ...base,
+                connectionMode: session.connectionMode ?? undefined,
+                namespace: session.activeNetwork?.namespace,
+                chainId: session.activeNetwork?.id,
+                walletId: session.activeWallet?.id,
+                addressNamespaces,
+                ...(missing.length > 0 && { missingNamespaces: missing })
+            };
+        }
+        case 'networkSwitched': {
+            const d = data;
+            return {
+                ...base,
+                operation: 'switchNetwork',
+                namespace: d.network.namespace,
+                chainId: d.network.id
+            };
+        }
+        case 'connectionUri': {
+            // Carry the mode but NEVER the URI itself (a relay/pairing string).
+            const d = data;
+            return { ...base, connectionMode: d.connectionMode };
+        }
+        case 'error': {
+            const d = data;
+            return {
+                ...base,
+                operation: d.operation,
+                error: { type: d.error.type, message: scrubMessage(d.error.message) },
+                // Telemetry-only classification — undefined for ordinary errors, set for
+                // pre-wallet validation failures (e.g. no_common_network) that never
+                // reach the handoff funnel.
+                errorCode: d.errorCode,
+                failureKind: d.failureKind,
+                source: d.source,
+                networkMismatch: capNetworkMismatch(d.networkMismatch),
+                handoffCovered: d.handoffCovered
+            };
+        }
+        case 'awaitingWallet': {
+            const d = data;
+            return {
+                ...base,
+                operation: d.operation,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace,
+                chainId: d.chainId,
+                handoffId: d.handoffId,
+                walletFlowType: d.walletFlowType,
+                platform: d.platform,
+                targetAlreadyActive: d.targetAlreadyActive
+            };
+        }
+        case 'walletSucceeded': {
+            const d = data;
+            return {
+                ...base,
+                operation: d.operation,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace,
+                chainId: d.chainId,
+                handoffId: d.handoffId,
+                durationMs: d.durationMs,
+                timedOut: d.timedOut,
+                timeoutMs: d.timeoutMs,
+                targetAlreadyActive: d.targetAlreadyActive
+            };
+        }
+        case 'walletRejected': {
+            const d = data;
+            return {
+                ...base,
+                operation: d.operation,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace,
+                chainId: d.chainId,
+                handoffId: d.handoffId,
+                durationMs: d.durationMs,
+                timedOut: d.timedOut,
+                timeoutMs: d.timeoutMs,
+                targetAlreadyActive: d.targetAlreadyActive,
+                errorCode: d.errorCode,
+                failureKind: d.failureKind,
+                source: d.source
+            };
+        }
+        case 'walletTimedOut': {
+            const d = data;
+            return {
+                ...base,
+                operation: d.operation,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace,
+                chainId: d.chainId,
+                handoffId: d.handoffId,
+                durationMs: d.durationMs,
+                timeoutMs: d.timeoutMs,
+                targetAlreadyActive: d.targetAlreadyActive
+            };
+        }
+        case 'walletFailed': {
+            const d = data;
+            return {
+                ...base,
+                operation: d.operation,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace,
+                chainId: d.chainId,
+                handoffId: d.handoffId,
+                durationMs: d.durationMs,
+                timedOut: d.timedOut,
+                timeoutMs: d.timeoutMs,
+                targetAlreadyActive: d.targetAlreadyActive,
+                errorCode: d.errorCode,
+                failureKind: d.failureKind,
+                source: d.source,
+                error: { type: d.error.type, message: scrubMessage(d.error.message) }
+            };
+        }
+        case 'capabilitiesUpdated': {
+            const d = data;
+            // Summarize to per-chain lists of the capability names that are not
+            // 'unsupported'. Compact + non-PII (chain ids + bounded feature names).
+            const capabilities = {};
+            for (const [chainId, caps] of Object.entries(d.capabilities)) {
+                const enabled = Object.entries(caps)
+                    .filter(([, cap]) => cap && cap.status !== 'unsupported')
+                    .map(([feature]) => feature);
+                if (enabled.length > 0)
+                    capabilities[chainId] = enabled;
+            }
+            return { ...base, capabilities };
+        }
+        case 'walletsDetected': {
+            const d = data;
+            // Carry only the compact requested-vs-matched summary; never the wallet list.
+            return { ...base, ...(d.discovery ? { discovery: d.discovery } : {}) };
+        }
+        case 'walletDiscoveryFailed': {
+            const d = data;
+            return {
+                ...base,
+                connectionMode: d.connectionMode,
+                namespace: d.namespace,
+                error: { type: d.error.type, message: scrubMessage(d.error.message) }
+            };
+        }
+        case 'pageHiddenDuringHandoff':
+        case 'pageVisibleDuringHandoff': {
+            const d = data;
+            return { ...base, handoffId: d.handoffId, platform: d.platform };
+        }
+        case 'bridgeError': {
+            const d = data;
+            return {
+                ...base,
+                namespace: d.namespace,
+                source: 'bridge',
+                failureKind: 'bridge_error',
+                error: { type: d.error.type, message: scrubMessage(d.error.message) }
+            };
+        }
+        case 'relayError': {
+            const d = data;
+            // A relay-socket transport failure (WalletConnect only). The scrubbed message
+            // carries the diagnostic detail (e.g. "code: 3000 (JWT ... not yet valid)").
+            return {
+                ...base,
+                connectionMode: 'walletConnect',
+                source: 'provider',
+                failureKind: 'network_error',
+                error: { type: d.error.type, message: scrubMessage(d.error.message) }
+            };
+        }
+        case 'walletAccountChanged':
+        case 'walletDisconnected':
+        case 'walletSessionExpired': {
+            const d = data;
+            return {
+                ...base,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace
+            };
+        }
+        case 'walletChainChanged': {
+            const d = data;
+            return {
+                ...base,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace,
+                chainId: d.chainId
+            };
+        }
+        case 'lifecycleTelemetryUnavailable': {
+            const d = data;
+            return {
+                ...base,
+                connectionMode: d.connectionMode,
+                walletId: d.walletId,
+                namespace: d.namespace,
+                reason: d.reason,
+                runtime: d.runtime
+            };
+        }
+        default:
+            // ready / disconnected / networkSwitching / change / log — name only
+            // (log goes via onLog).
+            return base;
+    }
+}
+/**
+ * Drop keys whose value is `undefined` so a record never carries a
+ * present-but-undefined optional (e.g. `errorCode: undefined` on a non-error
+ * event), which would make `'errorCode' in event` misleading. Shallow by design:
+ * nested objects (`error`, `networkMismatch`, `discovery`, `capabilities`,
+ * `addressNamespaces`) are only ever built with defined values.
+ */
+function compactUndefined(event) {
+    const record = event;
+    const out = {};
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Normalize a bus event into a PII-safe `UWCTelemetryEvent`, dropping undefined
+ * optionals so the emitted shape is consistent across event kinds.
+ */
+export function normalizeEvent(name, data, sdkSessionId, now, correlationId) {
+    return compactUndefined(buildTelemetryEvent(name, data, sdkSessionId, now, correlationId));
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/observability/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/observability/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/services/connection-service.d.ts

@@ -11,9 +11,31 @@ export declare class ConnectionService {
     private connectors;
     private usingIntegratedBrowser;
     private eventManager;
+    private walletResponseTimeoutMs;
     private activeConnector;
-    constructor(networks: Network[], wallets: WalletMetadata[], sessionManager: SessionManager, connectors: Map<ConnectionMode, Connector>, usingIntegratedBrowser: boolean, eventManager: EventManager);
+    /** Tears down the post-connect lifecycle subscription; set while connected. */
+    private lifecycleTeardown;
+    constructor(networks: Network[], wallets: WalletMetadata[], sessionManager: SessionManager, connectors: Map<ConnectionMode, Connector>, usingIntegratedBrowser: boolean, eventManager: EventManager, walletResponseTimeoutMs: number);
     connect(connectionMode: ConnectionMode, walletId: string, networkId?: NetworkId, options?: ServiceOptions): Promise<void>;
+    /** Wire the active connector's lifecycle stream onto the bus (or signal absence). */
+    private attachLifecycle;
+    /**
+     * 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;
+    /**
+     * 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;
     private connectWithURIPoll;
     private getConnector;
     private findWallet;

package/dist/services/connection-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-service.d.ts","sourceRoot":"","sources":["../../src/services/connection-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,cAAc,EACd,cAAc,EACd,SAAS,EAMV,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAG7D,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,sBAAsB;IAC9B,OAAO,CAAC,YAAY;IARtB,OAAO,CAAC,eAAe,CAAyB;gBAGtC,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,cAAc,EAAE,EACzB,cAAc,EAAE,cAAc,EAC9B,UAAU,EAAE,GAAG,CAAC,cAAc,EAAE,SAAS,CAAC,EAC1C,sBAAsB,EAAE,OAAO,EAC/B,YAAY,EAAE,YAAY;IAG9B,OAAO,CACX,cAAc,EAAE,cAAc,EAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;YAuFF,kBAAkB;IAqDhC,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,kBAAkB;IA2C1B,OAAO,CAAC,2BAA2B;IA6C7B,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzD,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAiBtC,UAAU,IAAI,cAAc,EAAE;IAI9B,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI;IAI9C,WAAW,IAAI,OAAO,EAAE;IAIxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;CAiBjC"}
+{"version":3,"file":"connection-service.d.ts","sourceRoot":"","sources":["../../src/services/connection-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EAET,cAAc,EACd,cAAc,EACd,SAAS,EAMV,MAAM,wBAAwB,CAAA;AAE/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAK7D,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,qBAAa,iBAAiB;IAM1B,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,sBAAsB;IAC9B,OAAO,CAAC,YAAY;IAEpB,OAAO,CAAC,uBAAuB;IAZjC,OAAO,CAAC,eAAe,CAAyB;IAChD,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB,CAA0B;gBAGzC,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,cAAc,EAAE,EACzB,cAAc,EAAE,cAAc,EAC9B,UAAU,EAAE,GAAG,CAAC,cAAc,EAAE,SAAS,CAAC,EAC1C,sBAAsB,EAAE,OAAO,EAC/B,YAAY,EAAE,YAAY,EAE1B,uBAAuB,EAAE,MAAM;IAGnC,OAAO,CACX,cAAc,EAAE,cAAc,EAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAiHhB,qFAAqF;IACrF,OAAO,CAAC,eAAe;IA8CvB;;;;;;OAMG;IACH,iBAAiB,IAAI,IAAI;IAKzB;;;;;;;OAOG;IACH,iBAAiB,IAAI,IAAI;YAqBX,kBAAkB;IAqDhC,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,kBAAkB;IA2C1B,OAAO,CAAC,2BAA2B;IAiD7B,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBzD,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAiBtC,UAAU,IAAI,cAAc,EAAE;IAI9B,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI;IAI9C,WAAW,IAAI,OAAO,EAAE;IAIxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;CAiBjC"}

package/dist/services/connection-service.js

@@ -1,4 +1,7 @@
+import { NoCommonNetworkError } from '@meshconnect/uwc-types';
 import { raceAbort } from '../utils/abort';
+import { instrumentHandoff } from '../observability/instrument-handoff';
+import { attachLifecycle } from '../observability/lifecycle-bridge';
 export class ConnectionService {
     networks;
     wallets;
@@ -6,14 +9,20 @@ export class ConnectionService {
     connectors;
     usingIntegratedBrowser;
     eventManager;
+    walletResponseTimeoutMs;
     activeConnector = null;
-    constructor(networks, wallets, sessionManager, connectors, usingIntegratedBrowser, eventManager) {
+    /** Tears down the post-connect lifecycle subscription; set while connected. */
+    lifecycleTeardown;
+    constructor(networks, wallets, sessionManager, connectors, usingIntegratedBrowser, eventManager, 
+    // Observational wallet-response deadline for the handoff timeout marker.
+    walletResponseTimeoutMs) {
         this.networks = networks;
         this.wallets = wallets;
         this.sessionManager = sessionManager;
         this.connectors = connectors;
         this.usingIntegratedBrowser = usingIntegratedBrowser;
         this.eventManager = eventManager;
+        this.walletResponseTimeoutMs = walletResponseTimeoutMs;
     }
     async connect(connectionMode, walletId, networkId, options) {
         options?.signal?.throwIfAborted();
@@ -33,28 +42,46 @@ export class ConnectionService {
         this.activeConnector = connector;
         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), 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), 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));
         this.sessionManager.updateSession({
@@ -69,6 +96,82 @@ 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). */
+    attachLifecycle(connectionMode, walletId, namespace, initialSwitch) {
+        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
+                .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() {
+        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() {
+        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() });
     }
     async connectWithURIPoll(connector, network, provider, connectionMode, signal) {
         const connectPromise = connector.connect(network, provider);
@@ -170,7 +273,10 @@ export class ConnectionService {
             // Use the first supported network that exists in both wallet and configured networks
             const supportedNetwork = provider.supportedNetworkIds.find(id => 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;
         }
@@ -183,6 +289,9 @@ export class ConnectionService {
     }
     async disconnect(options) {
         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 &&
                 typeof this.activeConnector.disconnect === 'function') {