@meshconnect/uwc-react 0.10.0 → 0.11.0-snapshot.86f6845

package/README.md

@@ -239,6 +239,17 @@ Props:
 - `usingIntegratedBrowser?: boolean` - Whether using integrated browser (default: false)
 - `walletConnectConfig?: WalletConnectConfig` - Optional WalletConnect configuration
 - `tonConnectConfig?: TonConnectConfig` - Optional TON Connect configuration (requires `manifestUrl`)
+- `tronConnectorConfig?: TronConnectorConfig` - Optional TRON connector configuration
+- `observer?: UWCObserver` - Optional telemetry sink (`onEvent`, optional `onLog`) for wallet-handoff observability; with no observer wired nothing leaves the browser
+- `logger?: Logger` / `logLevel?: LogLevel` - Optional runtime logging configuration
+- `correlationId?: string | (() => string)` - Optional id stamped on every telemetry event; pass the **getter form** for an id that resolves late (e.g. a session id)
+
+> **Read once.** The provider builds one shared connector on the first render
+> where `wallets` is non-empty, capturing `observer` / `logger` / `logLevel` /
+> `correlationId` at that instant — later prop changes are ignored. Pass a
+> stable `observer` from the first render (its `onEvent` can no-op until your
+> sink is ready), use the `correlationId` getter for late ids, and
+> `connector.setLogLevel()` for runtime level changes.
 
 ### Hooks
 

package/dist/providers/ConnectionProvider.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
-import { UniversalWalletConnector } from '@meshconnect/uwc-core';
-import type { Session, Network, WalletMetadata, WalletConnectConfig, TonConnectConfig, TronConnectorConfig } from '@meshconnect/uwc-types';
+import { UniversalWalletConnector, type UWCObserver } from '@meshconnect/uwc-core';
+import type { Session, Network, WalletMetadata, WalletConnectConfig, TonConnectConfig, TronConnectorConfig, Logger, LogLevel } from '@meshconnect/uwc-types';
 export interface ConnectionContextValue {
     /**
      * `null` when the provider is mounted without wallets. `@meshconnect/uwc-core`
@@ -25,7 +25,19 @@ interface ConnectionProviderProps {
     walletConnectConfig?: WalletConnectConfig;
     tonConnectConfig?: TonConnectConfig;
     tronConnectorConfig?: TronConnectorConfig;
+    /**
+     * Observability — forwarded to the connector (see @meshconnect/uwc-core).
+     * READ ONCE at connector construction (the first render with a non-empty
+     * wallet list); the shared singleton ignores later prop changes. Pass a
+     * stable `observer`/`logger`, prefer the getter form of `correlationId` for
+     * an id that arrives late (it is resolved per-event), and use the
+     * connector's `setLogLevel()` for runtime level changes.
+     */
+    observer?: UWCObserver;
+    logger?: Logger;
+    logLevel?: LogLevel;
+    correlationId?: string | (() => string);
 }
-export declare function ConnectionProvider({ children, networks, wallets, usingIntegratedBrowser, walletConnectConfig, tonConnectConfig, tronConnectorConfig }: ConnectionProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ConnectionProvider({ children, networks, wallets, usingIntegratedBrowser, walletConnectConfig, tonConnectConfig, tronConnectorConfig, observer, logger, logLevel, correlationId }: ConnectionProviderProps): import("react/jsx-runtime").JSX.Element;
 export { ConnectionContext };
 //# sourceMappingURL=ConnectionProvider.d.ts.map

package/dist/providers/ConnectionProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConnectionProvider.d.ts","sourceRoot":"","sources":["../../src/providers/ConnectionProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA6C,MAAM,OAAO,CAAA;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,KAAK,EACV,OAAO,EACP,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,wBAAwB,CAAA;AAwB/B,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAAA;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,QAAA,MAAM,iBAAiB,8CAAqD,CAAA;AAE5E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;IACzC,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CAC1C;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,sBAA8B,EAC9B,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACpB,EAAE,uBAAuB,2CAmDzB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"ConnectionProvider.d.ts","sourceRoot":"","sources":["../../src/providers/ConnectionProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA6C,MAAM,OAAO,CAAA;AACjE,OAAO,EACL,wBAAwB,EAExB,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EACV,OAAO,EACP,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,MAAM,EACN,QAAQ,EACT,MAAM,wBAAwB,CAAA;AAkC/B,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAAA;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,QAAA,MAAM,iBAAiB,8CAAqD,CAAA;AAE5E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;IACzC,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;CACxC;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,sBAA8B,EAC9B,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,aAAa,EACd,EAAE,uBAAuB,2CAkFzB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/providers/ConnectionProvider.js

@@ -3,6 +3,11 @@ import React, { createContext, useEffect, useState } from 'react';
 import { UniversalWalletConnector } from '@meshconnect/uwc-core';
 // Guard against double initialization
 let sharedConnector = null;
+// What the singleton captured at construction — kept to diagnose the one
+// silent failure mode: an observability prop that ARRIVES on a later render
+// is ignored, and without a warning telemetry just never fires.
+let capturedObservability = null;
+let warnedLateObservability = false;
 /**
  * Session served before any wallet is connected — and while the provider is
  * mounted without wallets (a wallet-less session; see `connector` below). Every
@@ -22,14 +27,60 @@ const EMPTY_SESSION = {
     availableAddresses: []
 };
 const ConnectionContext = createContext(null);
-export function ConnectionProvider({ children, networks, wallets, usingIntegratedBrowser = false, walletConnectConfig, tonConnectConfig, tronConnectorConfig }) {
+export function ConnectionProvider({ children, networks, wallets, usingIntegratedBrowser = false, walletConnectConfig, tonConnectConfig, tronConnectorConfig, observer, logger, logLevel, correlationId }) {
     // Core rejects an empty wallet list, so only construct once there is at least
     // one wallet. A wallet-less session keeps `connector` null; the effect below
     // adopts the connector if wallets arrive later (async catalog population).
     if (!sharedConnector && wallets.length > 0) {
-        sharedConnector = new UniversalWalletConnector(networks, wallets, usingIntegratedBrowser, walletConnectConfig, tonConnectConfig, tronConnectorConfig);
+        // Build the config object conditionally — under exactOptionalPropertyTypes an
+        // explicit `undefined` can't be assigned to an optional field.
+        const config = { networks, wallets, usingIntegratedBrowser };
+        if (walletConnectConfig)
+            config.walletConnectConfig = walletConnectConfig;
+        if (tonConnectConfig)
+            config.tonConnectConfig = tonConnectConfig;
+        if (tronConnectorConfig)
+            config.tronConnectorConfig = tronConnectorConfig;
+        if (observer)
+            config.observer = observer;
+        if (logger)
+            config.logger = logger;
+        if (logLevel)
+            config.logLevel = logLevel;
+        if (correlationId !== undefined)
+            config.correlationId = correlationId;
+        sharedConnector = new UniversalWalletConnector(config);
+        capturedObservability = {
+            hadObserver: !!observer,
+            hadLogger: !!logger,
+            hadLogLevel: !!logLevel,
+            hadCorrelationId: correlationId !== undefined
+        };
     }
     const connector = sharedConnector;
+    // Diagnose the read-once footgun: an observability prop supplied only AFTER
+    // the shared connector was built is silently ignored — warn once instead of
+    // letting telemetry die with no signal. Props that were present at
+    // construction are fine (the captured values keep flowing). Runs in an
+    // effect: a render must stay side-effect free.
+    useEffect(() => {
+        if (!connector || !capturedObservability || warnedLateObservability)
+            return;
+        const late = [];
+        if (observer && !capturedObservability.hadObserver)
+            late.push('observer');
+        if (logger && !capturedObservability.hadLogger)
+            late.push('logger');
+        if (logLevel && !capturedObservability.hadLogLevel)
+            late.push('logLevel');
+        if (correlationId !== undefined && !capturedObservability.hadCorrelationId)
+            late.push('correlationId');
+        if (late.length > 0) {
+            warnedLateObservability = true;
+            console.warn(`[uwc-react] ConnectionProvider received ${late.join(', ')} after the shared connector was constructed — these props are read once and the late value is ignored. ` +
+                'Pass them from the first render with a non-empty wallet list (observer/logger may be stable no-op shells until your sink is ready; correlationId supports a getter for late ids).');
+        }
+    }, [connector, observer, logger, logLevel, correlationId]);
     const [session, setSession] = useState(() => connector?.getSession() ?? EMPTY_SESSION);
     const [isReady, setIsReady] = useState(() => connector?.isReady() ?? false);
     useEffect(() => {

package/dist/providers/ConnectionProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConnectionProvider.js","sourceRoot":"","sources":["../../src/providers/ConnectionProvider.tsx"],"names":[],"mappings":";AAAA,OAAO,KAAK,EAAE,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAUhE,sCAAsC;AACtC,IAAI,eAAe,GAAoC,IAAI,CAAA;AAE3D;;;;;;GAMG;AACH,MAAM,aAAa,GAAY;IAC7B,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;IACnB,wBAAwB,EAAE,IAAI;IAC9B,+BAA+B,EAAE,IAAI;IACrC,aAAa,EAAE,IAAI;IACnB,SAAS,EAAE,IAAI;IACf,iBAAiB,EAAE,EAAE;IACrB,YAAY,EAAE,IAAI;IAClB,kBAAkB,EAAE,EAAE;CACvB,CAAA;AAkBD,MAAM,iBAAiB,GAAG,aAAa,CAAgC,IAAI,CAAC,CAAA;AAY5E,MAAM,UAAU,kBAAkB,CAAC,EACjC,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,sBAAsB,GAAG,KAAK,EAC9B,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACK;IACxB,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,IAAI,CAAC,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,eAAe,GAAG,IAAI,wBAAwB,CAC5C,QAAQ,EACR,OAAO,EACP,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,CACpB,CAAA;IACH,CAAC;IAED,MAAM,SAAS,GAAG,eAAe,CAAA;IAEjC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CACpC,GAAG,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,aAAa,CAC/C,CAAA;IACD,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,KAAK,CAAC,CAAA;IAE3E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,SAAS;YAAE,OAAM;QAEtB,0EAA0E;QAC1E,6DAA6D;QAC7D,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAA;QAClC,UAAU,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAA;QAE/B,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE;YAC3C,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAA;YAClC,UAAU,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAA;QACjC,CAAC,CAAC,CAAA;QAEF,OAAO,WAAW,CAAA;IACpB,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAA;IAEf,MAAM,KAAK,GAA2B;QACpC,SAAS;QACT,OAAO;QACP,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,OAAO;QACrD,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,QAAQ;QACxD,OAAO;KACR,CAAA;IAED,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACrC,QAAQ,GACkB,CAC9B,CAAA;AACH,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"ConnectionProvider.js","sourceRoot":"","sources":["../../src/providers/ConnectionProvider.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshconnect/uwc-react",
-  "version": "0.10.0",
+  "version": "0.11.0-snapshot.86f6845",
   "description": "React hooks and components for Universal Wallet Connector",
   "type": "module",
   "main": "dist/index.js",
@@ -16,8 +16,8 @@
     "src"
   ],
   "dependencies": {
-    "@meshconnect/uwc-types": "0.16.1",
-    "@meshconnect/uwc-core": "1.0.2"
+    "@meshconnect/uwc-core": "1.1.0-snapshot.86f6845",
+    "@meshconnect/uwc-types": "0.17.0-snapshot.86f6845"
   },
   "peerDependencies": {
     "react": "^18.0.0",

package/src/providers/ConnectionProvider.singleton.test.tsx

@@ -159,13 +159,223 @@ describe('ConnectionProvider singleton behavior', () => {
       )
     })
 
-    // Constructor signature: (networks, wallets, usingIntegratedBrowser,
-    // walletConnectConfig, tonConnectConfig, tronConnectorConfig)
+    // Constructor now receives a single UWCConfig object (config-object form),
+    // so the provider can also forward the observability fields.
     expect(ctorArgs.length).toBe(1)
-    expect(ctorArgs[0]?.[5]).toBe(tronConnectorConfig)
+    expect(ctorArgs[0]?.[0]?.tronConnectorConfig).toBe(tronConnectorConfig)
 
     await act(async () => {
       root.unmount()
     })
   })
+
+  it('forwards the observer to the UniversalWalletConnector config', async () => {
+    const ctorArgs: unknown[][] = []
+    vi.doMock('@meshconnect/uwc-core', () => {
+      class UniversalWalletConnector {
+        constructor(...args: unknown[]) {
+          ctorArgs.push(args)
+        }
+        getSession() {
+          return {
+            isConnected: false,
+            walletId: undefined,
+            networkId: undefined
+          }
+        }
+        isReady() {
+          return true
+        }
+        subscribe() {
+          return () => {}
+        }
+        getWallets() {
+          return []
+        }
+        getNetworks() {
+          return []
+        }
+      }
+      return { UniversalWalletConnector }
+    })
+
+    const { ConnectionProvider } = await import('./ConnectionProvider')
+    const observer = { onEvent: () => {} }
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    const root = createRoot(container)
+
+    await act(async () => {
+      root.render(
+        <ConnectionProvider
+          networks={[]}
+          wallets={TEST_WALLETS}
+          observer={observer}
+        >
+          <div />
+        </ConnectionProvider>
+      )
+    })
+
+    expect(ctorArgs.length).toBe(1)
+    expect((ctorArgs[0]?.[0] as { observer?: unknown })?.observer).toBe(
+      observer
+    )
+
+    await act(async () => {
+      root.unmount()
+    })
+  })
+
+  it('forwards logger, logLevel and correlationId (including the empty string) to the config', async () => {
+    const ctorArgs: unknown[][] = []
+    vi.doMock('@meshconnect/uwc-core', () => {
+      class UniversalWalletConnector {
+        constructor(...args: unknown[]) {
+          ctorArgs.push(args)
+        }
+        getSession() {
+          return {
+            isConnected: false,
+            walletId: undefined,
+            networkId: undefined
+          }
+        }
+        isReady() {
+          return true
+        }
+        subscribe() {
+          return () => {}
+        }
+        getWallets() {
+          return []
+        }
+        getNetworks() {
+          return []
+        }
+      }
+      return { UniversalWalletConnector }
+    })
+
+    const { ConnectionProvider } = await import('./ConnectionProvider')
+    const logger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {}
+    }
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    const root = createRoot(container)
+
+    await act(async () => {
+      root.render(
+        <ConnectionProvider
+          networks={[]}
+          wallets={TEST_WALLETS}
+          logger={logger}
+          logLevel="debug"
+          correlationId=""
+        >
+          <div />
+        </ConnectionProvider>
+      )
+    })
+
+    expect(ctorArgs.length).toBe(1)
+    const config = ctorArgs[0]?.[0] as {
+      logger?: unknown
+      logLevel?: unknown
+      correlationId?: unknown
+    }
+    expect(config?.logger).toBe(logger)
+    expect(config?.logLevel).toBe('debug')
+    // '' must forward: the guard is deliberately `!== undefined`, not
+    // truthiness — an empty-string correlation id is a valid consumer value.
+    expect(config?.correlationId).toBe('')
+
+    await act(async () => {
+      root.unmount()
+    })
+  })
+
+  it('warns once (from an effect, not render) when an observability prop arrives after construction', async () => {
+    vi.doMock('@meshconnect/uwc-core', () => {
+      class UniversalWalletConnector {
+        getSession() {
+          return {
+            isConnected: false,
+            walletId: undefined,
+            networkId: undefined
+          }
+        }
+        isReady() {
+          return true
+        }
+        subscribe() {
+          return () => {}
+        }
+        getWallets() {
+          return []
+        }
+        getNetworks() {
+          return []
+        }
+      }
+      return { UniversalWalletConnector }
+    })
+
+    const { ConnectionProvider } = await import('./ConnectionProvider')
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    const root = createRoot(container)
+
+    // First render: connector constructed WITHOUT an observer.
+    await act(async () => {
+      root.render(
+        <ConnectionProvider networks={[]} wallets={TEST_WALLETS}>
+          <div />
+        </ConnectionProvider>
+      )
+    })
+    expect(warnSpy).not.toHaveBeenCalled()
+
+    // Late observer: read-once means it is ignored — must warn, exactly once
+    // across re-renders.
+    const observer = { onEvent: () => {} }
+    await act(async () => {
+      root.render(
+        <ConnectionProvider
+          networks={[]}
+          wallets={TEST_WALLETS}
+          observer={observer}
+        >
+          <div />
+        </ConnectionProvider>
+      )
+    })
+    await act(async () => {
+      root.render(
+        <ConnectionProvider
+          networks={[]}
+          wallets={TEST_WALLETS}
+          observer={observer}
+        >
+          <div />
+        </ConnectionProvider>
+      )
+    })
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0]?.[0]).toContain('observer')
+
+    warnSpy.mockRestore()
+    await act(async () => {
+      root.unmount()
+    })
+  })
 })

package/src/providers/ConnectionProvider.tsx

@@ -1,16 +1,32 @@
 import React, { createContext, useEffect, useState } from 'react'
-import { UniversalWalletConnector } from '@meshconnect/uwc-core'
+import {
+  UniversalWalletConnector,
+  type UWCConfig,
+  type UWCObserver
+} from '@meshconnect/uwc-core'
 import type {
   Session,
   Network,
   WalletMetadata,
   WalletConnectConfig,
   TonConnectConfig,
-  TronConnectorConfig
+  TronConnectorConfig,
+  Logger,
+  LogLevel
 } from '@meshconnect/uwc-types'
 
 // Guard against double initialization
 let sharedConnector: UniversalWalletConnector | null = null
+// What the singleton captured at construction — kept to diagnose the one
+// silent failure mode: an observability prop that ARRIVES on a later render
+// is ignored, and without a warning telemetry just never fires.
+let capturedObservability: {
+  hadObserver: boolean
+  hadLogger: boolean
+  hadLogLevel: boolean
+  hadCorrelationId: boolean
+} | null = null
+let warnedLateObservability = false
 
 /**
  * Session served before any wallet is connected — and while the provider is
@@ -57,6 +73,18 @@ interface ConnectionProviderProps {
   walletConnectConfig?: WalletConnectConfig
   tonConnectConfig?: TonConnectConfig
   tronConnectorConfig?: TronConnectorConfig
+  /**
+   * Observability — forwarded to the connector (see @meshconnect/uwc-core).
+   * READ ONCE at connector construction (the first render with a non-empty
+   * wallet list); the shared singleton ignores later prop changes. Pass a
+   * stable `observer`/`logger`, prefer the getter form of `correlationId` for
+   * an id that arrives late (it is resolved per-event), and use the
+   * connector's `setLogLevel()` for runtime level changes.
+   */
+  observer?: UWCObserver
+  logger?: Logger
+  logLevel?: LogLevel
+  correlationId?: string | (() => string)
 }
 
 export function ConnectionProvider({
@@ -66,24 +94,59 @@ export function ConnectionProvider({
   usingIntegratedBrowser = false,
   walletConnectConfig,
   tonConnectConfig,
-  tronConnectorConfig
+  tronConnectorConfig,
+  observer,
+  logger,
+  logLevel,
+  correlationId
 }: ConnectionProviderProps) {
   // Core rejects an empty wallet list, so only construct once there is at least
   // one wallet. A wallet-less session keeps `connector` null; the effect below
   // adopts the connector if wallets arrive later (async catalog population).
   if (!sharedConnector && wallets.length > 0) {
-    sharedConnector = new UniversalWalletConnector(
-      networks,
-      wallets,
-      usingIntegratedBrowser,
-      walletConnectConfig,
-      tonConnectConfig,
-      tronConnectorConfig
-    )
+    // Build the config object conditionally — under exactOptionalPropertyTypes an
+    // explicit `undefined` can't be assigned to an optional field.
+    const config: UWCConfig = { networks, wallets, usingIntegratedBrowser }
+    if (walletConnectConfig) config.walletConnectConfig = walletConnectConfig
+    if (tonConnectConfig) config.tonConnectConfig = tonConnectConfig
+    if (tronConnectorConfig) config.tronConnectorConfig = tronConnectorConfig
+    if (observer) config.observer = observer
+    if (logger) config.logger = logger
+    if (logLevel) config.logLevel = logLevel
+    if (correlationId !== undefined) config.correlationId = correlationId
+    sharedConnector = new UniversalWalletConnector(config)
+    capturedObservability = {
+      hadObserver: !!observer,
+      hadLogger: !!logger,
+      hadLogLevel: !!logLevel,
+      hadCorrelationId: correlationId !== undefined
+    }
   }
 
   const connector = sharedConnector
 
+  // Diagnose the read-once footgun: an observability prop supplied only AFTER
+  // the shared connector was built is silently ignored — warn once instead of
+  // letting telemetry die with no signal. Props that were present at
+  // construction are fine (the captured values keep flowing). Runs in an
+  // effect: a render must stay side-effect free.
+  useEffect(() => {
+    if (!connector || !capturedObservability || warnedLateObservability) return
+    const late: string[] = []
+    if (observer && !capturedObservability.hadObserver) late.push('observer')
+    if (logger && !capturedObservability.hadLogger) late.push('logger')
+    if (logLevel && !capturedObservability.hadLogLevel) late.push('logLevel')
+    if (correlationId !== undefined && !capturedObservability.hadCorrelationId)
+      late.push('correlationId')
+    if (late.length > 0) {
+      warnedLateObservability = true
+      console.warn(
+        `[uwc-react] ConnectionProvider received ${late.join(', ')} after the shared connector was constructed — these props are read once and the late value is ignored. ` +
+          'Pass them from the first render with a non-empty wallet list (observer/logger may be stable no-op shells until your sink is ready; correlationId supports a getter for late ids).'
+      )
+    }
+  }, [connector, observer, logger, logLevel, correlationId])
+
   const [session, setSession] = useState<Session>(
     () => connector?.getSession() ?? EMPTY_SESSION
   )