@meshconnect/uwc-core 2.7.2 → 2.7.3-snapshot.149a27e

package/src/observability/telemetry.ts

@@ -11,7 +11,8 @@ import type {
   LifecycleUnavailableReason,
   Session,
   WalletStepName,
-  WalletStepOutcome
+  WalletStepOutcome,
+  ErrorType
 } from '@meshconnect/uwc-types'
 import type { UWCEventName, UWCEventMap, UWCOperation } from '../events'
 import { UWC_CORE_VERSION } from '../version'
@@ -123,6 +124,10 @@ export interface UWCTelemetryEvent {
   targetAlreadyActive?: boolean | undefined
   /** connect only: a `silentOnly` attempt — tells a silent restore from a tapped connect. */
   silentOnly?: boolean | undefined
+  /** connect only: how the connect network was chosen — explicit, detected, or catalog order. */
+  networkSelection?: 'explicit' | 'detected' | 'catalogOrder' | undefined
+  /** connect only: secondary namespaces gathered without first-time prompts. */
+  quietSecondaries?: boolean | undefined
   /** Non-success outcomes: stringified error code when reliably known. */
   errorCode?: string | undefined
   /** Non-success outcomes: coarse cause bucket. `unknown` when not classifiable. */
@@ -218,6 +223,17 @@ export interface UWCTelemetryEvent {
    * still succeeded), so conflating the two would misreport success as failure.
    */
   stepOutcome?: WalletStepOutcome | undefined
+  /**
+   * `walletStep` only: the `name` of what a `failed` step threw (e.g.
+   * `WalletAccountError`), so a swallowed failure can be told apart in
+   * Datadog. Never the message.
+   */
+  stepErrorName?: string | undefined
+  /**
+   * `walletStep` only: `rejected` when a `failed` step was the user declining,
+   * so a declined secondary prompt can be counted apart from a wallet fault.
+   */
+  stepErrorType?: ErrorType | undefined
   /** `pageVisibleDuringHandoff` only: how long the page was hidden for that segment (ms). */
   hiddenMs?: number | undefined
   /** Handoff terminals: cumulative time the page was backgrounded during the handoff (ms). */
@@ -473,7 +489,9 @@ function buildTelemetryEvent<K extends UWCEventName>(
         walletFlowType: d.walletFlowType,
         platform: d.platform,
         targetAlreadyActive: d.targetAlreadyActive,
-        silentOnly: d.silentOnly
+        silentOnly: d.silentOnly,
+        networkSelection: d.networkSelection,
+        quietSecondaries: d.quietSecondaries
       }
     }
     case 'walletSucceeded': {
@@ -492,6 +510,8 @@ function buildTelemetryEvent<K extends UWCEventName>(
         timeoutMs: d.timeoutMs,
         targetAlreadyActive: d.targetAlreadyActive,
         silentOnly: d.silentOnly,
+        networkSelection: d.networkSelection,
+        quietSecondaries: d.quietSecondaries,
         backgroundedMs: d.backgroundedMs,
         backgroundCount: d.backgroundCount,
         relayDropCount: d.relayDropCount,
@@ -514,6 +534,8 @@ function buildTelemetryEvent<K extends UWCEventName>(
         timeoutMs: d.timeoutMs,
         targetAlreadyActive: d.targetAlreadyActive,
         silentOnly: d.silentOnly,
+        networkSelection: d.networkSelection,
+        quietSecondaries: d.quietSecondaries,
         errorCode: d.errorCode,
         failureKind: d.failureKind,
         source: d.source,
@@ -538,6 +560,8 @@ function buildTelemetryEvent<K extends UWCEventName>(
         timeoutMs: d.timeoutMs,
         targetAlreadyActive: d.targetAlreadyActive,
         silentOnly: d.silentOnly,
+        networkSelection: d.networkSelection,
+        quietSecondaries: d.quietSecondaries,
         backgroundedMs: d.backgroundedMs,
         backgroundCount: d.backgroundCount,
         relayDropCount: d.relayDropCount
@@ -555,7 +579,11 @@ function buildTelemetryEvent<K extends UWCEventName>(
         durationMs: d.durationMs,
         step: d.step,
         stepOutcome: d.outcome,
-        timeoutMs: d.timeoutMs
+        timeoutMs: d.timeoutMs,
+        // A wallet sets the name it throws, so it is scrubbed like a message.
+        stepErrorName:
+          d.errorName === undefined ? undefined : scrubMessage(d.errorName),
+        stepErrorType: d.errorType
       }
     }
     case 'walletFailed': {
@@ -574,6 +602,8 @@ function buildTelemetryEvent<K extends UWCEventName>(
         timeoutMs: d.timeoutMs,
         targetAlreadyActive: d.targetAlreadyActive,
         silentOnly: d.silentOnly,
+        networkSelection: d.networkSelection,
+        quietSecondaries: d.quietSecondaries,
         errorCode: d.errorCode,
         failureKind: d.failureKind,
         source: d.source,

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

@@ -114,11 +114,11 @@ describe('ConnectionService', () => {
     const mockProvider = {
       supportedNetworkIds: ['eip155:1']
     }
-    const network = connectionService['validateAndDetermineNetwork'](
-      'eip155:1',
-      mockProvider as any
-    )
+    const { network, selection } = connectionService[
+      'validateAndDetermineNetwork'
+    ]('eip155:1', mockProvider as any, 'injected')
     expect(network).toEqual(networks[0])
+    expect(selection).toBe('explicit')
   })
 
   it('should throw error for unknown network', () => {
@@ -128,7 +128,8 @@ describe('ConnectionService', () => {
     expect(() => {
       connectionService['validateAndDetermineNetwork'](
         'eip155:8453',
-        mockProvider as any
+        mockProvider as any,
+        'injected'
       )
     }).toThrow('Network eip155:8453 is not in the configured networks')
   })
@@ -143,7 +144,8 @@ describe('ConnectionService', () => {
     try {
       connectionService['validateAndDetermineNetwork'](
         undefined,
-        mockProvider as any
+        mockProvider as any,
+        'injected'
       )
     } catch (e) {
       thrown = e
@@ -265,6 +267,72 @@ describe('ConnectionService', () => {
       ])
     })
 
+    it('forwards quietSecondaries to the injected connector and tags the funnel with it', async () => {
+      const provider = { supportedNetworkIds: ['eip155:1'] }
+      wallets[0].extensionInjectedProvider = provider as any
+      mockConnector.connect = vi.fn().mockResolvedValue({
+        networkId: 'eip155:1',
+        address: '0x1234',
+        availableAddresses: [{ address: '0x1234', networkId: 'eip155:1' }]
+      })
+      const awaiting = vi.fn()
+      const succeeded = vi.fn()
+      eventManager.on('awaitingWallet', awaiting)
+      eventManager.on('walletSucceeded', succeeded)
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1', {
+        quietSecondaries: true
+      })
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+
+      expect(mockConnector.connect).toHaveBeenNthCalledWith(
+        1,
+        networks[0],
+        provider,
+        { quietSecondaries: true }
+      )
+      expect(mockConnector.connect).toHaveBeenNthCalledWith(
+        2,
+        networks[0],
+        provider,
+        undefined
+      )
+      expect(awaiting.mock.calls.map(([e]) => e.quietSecondaries)).toEqual([
+        true,
+        false
+      ])
+      expect(succeeded.mock.calls.map(([e]) => e.quietSecondaries)).toEqual([
+        true,
+        false
+      ])
+    })
+
+    it('forwards quietSecondaries and secondaryPromptGapMs with requiredAddresses', async () => {
+      const provider = { supportedNetworkIds: ['eip155:1'] }
+      wallets[0].extensionInjectedProvider = provider as any
+      mockConnector.connect = vi.fn().mockResolvedValue({
+        networkId: 'eip155:1',
+        address: '0x1234',
+        availableAddresses: [{ address: '0x1234', networkId: 'eip155:1' }]
+      })
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1', {
+        requiredAddresses: ['0x1234'],
+        quietSecondaries: true,
+        secondaryPromptGapMs: 1500
+      })
+
+      expect(mockConnector.connect).toHaveBeenCalledWith(
+        networks[0],
+        provider,
+        {
+          requiredAddresses: ['0x1234'],
+          quietSecondaries: true,
+          secondaryPromptGapMs: 1500
+        }
+      )
+    })
+
     it('passes no connect options when neither silentOnly nor requiredAddresses is set', async () => {
       const provider = { supportedNetworkIds: ['eip155:1'] }
       wallets[0].extensionInjectedProvider = provider as any
@@ -376,6 +444,44 @@ describe('ConnectionService', () => {
       expect(awaiting.namespace).toBe('eip155')
       expect(awaiting.chainId).toBe('eip155:1')
       expect(awaiting.handoffId).toBe(events[1].data.handoffId)
+      expect(awaiting.networkSelection).toBe('explicit')
+    })
+
+    it('auto-picks a detected namespace over an undetected first network', async () => {
+      networks.push({
+        ...networks[0],
+        id: 'tron:0x2b6653dc',
+        internalId: 2,
+        name: 'Tron',
+        namespace: 'tron',
+        networkType: 'tron'
+      } as Network)
+      // Trust mobile: catalog lists Tron first, but only EVM was detected.
+      wallets[0].extensionInjectedProvider = {
+        supportedNetworkIds: ['tron:0x2b6653dc', 'eip155:1'],
+        namespaceMetaData: {
+          tron: { injectedId: 'trustWallet.tronLink', installed: false },
+          eip155: { eip155Name: 'Trust Wallet', installed: true }
+        }
+      } as any
+      const awaiting = vi.fn()
+      eventManager.on('awaitingWallet', awaiting)
+      mockConnector.connect = vi.fn().mockResolvedValue({
+        networkId: 'eip155:1',
+        address: '0x1234',
+        availableAddresses: [{ address: '0x1234', networkId: 'eip155:1' }]
+      })
+
+      await connectionService.connect('injected', 'metamask')
+
+      expect(awaiting).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chainId: 'eip155:1',
+          namespace: 'eip155',
+          networkSelection: 'detected'
+        })
+      )
+      expect(sessionManager.getSession().activeNetwork?.id).toBe('eip155:1')
     })
 
     it('emits one stable attempt ID per connect and a different ID for the next connect', async () => {

package/src/services/connection-service.ts

@@ -5,6 +5,7 @@ import type {
   WalletMetadata,
   ConnectionMode,
   Connector,
+  ConnectorConnectOptions,
   ConnectorResult,
   SupportedProvider,
   ExtensionInjectedProvider,
@@ -18,6 +19,11 @@ import { raceAbort } from '../utils/abort'
 import { generateId } from '../utils/id'
 import { instrumentHandoff } from '../observability/instrument-handoff'
 import { attachLifecycle } from '../observability/lifecycle-bridge'
+import {
+  DEFAULT_NAMESPACE_PRIORITY,
+  type NetworkSelection,
+  pickAutoNetwork
+} from './network-selection'
 
 export interface ServiceOptions {
   signal?: AbortSignal
@@ -31,6 +37,42 @@ export interface ServiceOptions {
    * Injected mode only; see `ConnectorConnectOptions.silentOnly`.
    */
   silentOnly?: boolean
+  /**
+   * No first-time prompt for a secondary namespace (connect only). Injected
+   * mode only; see `ConnectorConnectOptions.quietSecondaries`.
+   */
+  quietSecondaries?: boolean
+  /**
+   * Wait before each secondary request that can prompt (connect only).
+   * Injected mode only; see `ConnectorConnectOptions.secondaryPromptGapMs`.
+   */
+  secondaryPromptGapMs?: number
+}
+
+/** The connector options a connect carries, or undefined when it sets none. */
+function injectedConnectOptions(
+  options: ServiceOptions | undefined
+): ConnectorConnectOptions | undefined {
+  const {
+    requiredAddresses,
+    silentOnly,
+    quietSecondaries,
+    secondaryPromptGapMs
+  } = options ?? {}
+  if (
+    !requiredAddresses &&
+    !silentOnly &&
+    !quietSecondaries &&
+    !secondaryPromptGapMs
+  ) {
+    return undefined
+  }
+  return {
+    ...(requiredAddresses ? { requiredAddresses } : {}),
+    ...(silentOnly ? { silentOnly } : {}),
+    ...(quietSecondaries ? { quietSecondaries } : {}),
+    ...(secondaryPromptGapMs ? { secondaryPromptGapMs } : {})
+  }
 }
 
 /** Sibling-namespace live-account re-read poll: absorbs the lag while a wallet
@@ -87,7 +129,9 @@ export class ConnectionService {
     private usingIntegratedBrowser: boolean,
     private eventManager: EventManager,
     // Observational wallet-response deadline for the handoff timeout marker.
-    private walletResponseTimeoutMs: number
+    private walletResponseTimeoutMs: number,
+    /** Namespace preference for an auto-picked connect network — see `pickAutoNetwork`. */
+    private preferredNamespaces: readonly Namespace[] = DEFAULT_NAMESPACE_PRIORITY
   ) {}
 
   async connect(
@@ -104,7 +148,8 @@ export class ConnectionService {
     // connect() would spuriously abort (MFS-602).
     const wallet = this.findWallet(walletId)
     const provider = this.getProviderForMode(wallet, connectionMode)
-    const network = this.validateAndDetermineNetwork(networkId, provider)
+    const { network, selection: networkSelection } =
+      this.validateAndDetermineNetwork(networkId, provider, connectionMode)
     const connector = this.getConnector(connectionMode)
     // A silent-only connect is a promise never to open wallet UI. Only the
     // injected connector can keep it — WalletConnect / TON Connect always hand
@@ -176,7 +221,9 @@ export class ConnectionService {
           connectAttemptId,
           // Lets telemetry tell a silent restore from a tapped connect: both
           // succeed the same way, and only a miss carries a distinct failureKind.
-          silentOnly: options?.silentOnly === true
+          silentOnly: options?.silentOnly === true,
+          networkSelection,
+          quietSecondaries: options?.quietSecondaries === true
         },
         async handoffId => {
           // Publish this attempt's routing for the connector's step sink.
@@ -189,8 +236,7 @@ export class ConnectionService {
               provider,
               signal,
               connectAttemptId,
-              options?.requiredAddresses,
-              options?.silentOnly
+              options
             )
           } finally {
             // Retract ONLY if we are still the published attempt. An
@@ -281,8 +327,7 @@ export class ConnectionService {
     provider: SupportedProvider,
     signal: AbortSignal,
     connectAttemptId: string,
-    requiredAddresses?: readonly string[],
-    silentOnly?: boolean
+    options?: ServiceOptions
   ): Promise<ConnectorResult> {
     // Race the connector call against the AbortSignal so a mid-flight abort
     // (e.g. user cancels the WalletConnect QR while the prompt is open)
@@ -295,12 +340,7 @@ export class ConnectionService {
           provider as
             | ExtensionInjectedProvider
             | IntegratedBrowserInjectedProvider,
-          requiredAddresses || silentOnly
-            ? {
-                ...(requiredAddresses ? { requiredAddresses } : {}),
-                ...(silentOnly ? { silentOnly } : {})
-              }
-            : undefined
+          injectedConnectOptions(options)
         ),
         signal
       )
@@ -947,9 +987,11 @@ export class ConnectionService {
 
   private validateAndDetermineNetwork(
     networkId: NetworkId | undefined,
-    provider: SupportedProvider
-  ): Network {
+    provider: SupportedProvider,
+    connectionMode: ConnectionMode
+  ): { network: Network; selection: NetworkSelection } {
     let targetNetworkId: NetworkId
+    let selection: NetworkSelection = 'explicit'
 
     if (networkId) {
       // Check if networkId is in the configured networks
@@ -968,11 +1010,16 @@ export class ConnectionService {
 
       targetNetworkId = networkId
     } else {
-      // 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)
+      // No network named: prefer a namespace detection found installed (injected
+      // only), ranked by `preferredNamespaces`; otherwise the first supported
+      // network that is also configured (catalog order).
+      const picked = pickAutoNetwork(
+        provider,
+        this.networks,
+        connectionMode,
+        this.preferredNamespaces
       )
-      if (!supportedNetwork) {
+      if (!picked) {
         // 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.
@@ -981,7 +1028,8 @@ export class ConnectionService {
           this.networks.map(n => n.id)
         )
       }
-      targetNetworkId = supportedNetwork
+      targetNetworkId = picked.networkId
+      selection = picked.selection
     }
 
     // Find and return the network object
@@ -991,7 +1039,7 @@ export class ConnectionService {
         `Network ${targetNetworkId} not found in configured networks`
       )
     }
-    return network
+    return { network, selection }
   }
 
   async disconnect(options?: ServiceOptions): Promise<void> {

package/src/services/index.ts

@@ -1,3 +1,4 @@
 export * from './connection-service'
+export * from './network-selection'
 export * from './signature-service'
 export * from './transaction-service'

package/src/services/network-selection.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+import type { Network, SupportedProvider } from '@meshconnect/uwc-types'
+import {
+  DEFAULT_NAMESPACE_PRIORITY,
+  pickAutoNetwork
+} from './network-selection'
+
+const network = (id: string, namespace: Network['namespace']): Network =>
+  ({
+    id,
+    internalId: 0,
+    name: id,
+    namespace,
+    logoUrl: '',
+    networkType: 'evm',
+    nativeCurrency: { name: '', symbol: '', decimals: 18 }
+  }) as Network
+
+const NETWORKS = [
+  network('eip155:1', 'eip155'),
+  network('eip155:81457', 'eip155'),
+  network('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'solana'),
+  network('tron:0x2b6653dc', 'tron'),
+  network('tvm:-239', 'tvm')
+]
+
+/** An injected provider whose namespaces carry detection's `installed` flag. */
+const injected = (
+  supportedNetworkIds: string[],
+  installed: Partial<Record<'eip155' | 'solana' | 'tron' | 'tvm', boolean>>
+): SupportedProvider =>
+  ({
+    supportedNetworkIds,
+    namespaceMetaData: {
+      eip155: { eip155Name: 'W', installed: installed.eip155 },
+      solana: { walletStandardName: 'W', installed: installed.solana },
+      tron: { injectedId: 'w.tron', installed: installed.tron },
+      tvm: { jsBridgeKey: 'w', installed: installed.tvm }
+    }
+  }) as unknown as SupportedProvider
+
+describe('pickAutoNetwork', () => {
+  it('skips an undetected first network (Trust mobile: Tron first, not injected)', () => {
+    const provider = injected(
+      [
+        'tron:0x2b6653dc',
+        'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+        'eip155:1'
+      ],
+      { eip155: true, solana: true, tron: false, tvm: true }
+    )
+    expect(
+      pickAutoNetwork(
+        provider,
+        NETWORKS,
+        'injected',
+        DEFAULT_NAMESPACE_PRIORITY
+      )
+    ).toEqual({ networkId: 'eip155:1', selection: 'detected' })
+  })
+
+  it('keeps catalog order within a namespace', () => {
+    const provider = injected(['eip155:81457', 'eip155:1'], { eip155: true })
+    expect(
+      pickAutoNetwork(
+        provider,
+        NETWORKS,
+        'injected',
+        DEFAULT_NAMESPACE_PRIORITY
+      )?.networkId
+    ).toBe('eip155:81457')
+  })
+
+  it('honours a caller-supplied namespace preference', () => {
+    const provider = injected(
+      ['eip155:1', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
+      { eip155: true, solana: true }
+    )
+    expect(
+      pickAutoNetwork(provider, NETWORKS, 'injected', ['solana', 'eip155'])
+    ).toEqual({
+      networkId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      selection: 'detected'
+    })
+  })
+
+  it('ranks a namespace missing from the preference list last', () => {
+    const provider = injected(['tvm:-239', 'tron:0x2b6653dc'], {
+      tvm: true,
+      tron: true
+    })
+    expect(
+      pickAutoNetwork(provider, NETWORKS, 'injected', ['tron'])?.networkId
+    ).toBe('tron:0x2b6653dc')
+  })
+
+  it('falls back to catalog order when nothing was detected (e.g. before detection)', () => {
+    const provider = injected(['tron:0x2b6653dc', 'eip155:1'], {})
+    expect(
+      pickAutoNetwork(
+        provider,
+        NETWORKS,
+        'injected',
+        DEFAULT_NAMESPACE_PRIORITY
+      )
+    ).toEqual({ networkId: 'tron:0x2b6653dc', selection: 'catalogOrder' })
+  })
+
+  it('leaves non-injected modes on catalog order even with installed flags', () => {
+    const provider = injected(['tron:0x2b6653dc', 'eip155:1'], {
+      eip155: true
+    })
+    expect(
+      pickAutoNetwork(
+        provider,
+        NETWORKS,
+        'walletConnect',
+        DEFAULT_NAMESPACE_PRIORITY
+      )
+    ).toEqual({ networkId: 'tron:0x2b6653dc', selection: 'catalogOrder' })
+  })
+
+  it('ignores supported networks that are not configured', () => {
+    const provider = injected(
+      ['eip155:999', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
+      {
+        eip155: true,
+        solana: true
+      }
+    )
+    expect(
+      pickAutoNetwork(
+        provider,
+        NETWORKS,
+        'injected',
+        DEFAULT_NAMESPACE_PRIORITY
+      )?.networkId
+    ).toBe('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+  })
+
+  it('returns undefined when no supported network is configured', () => {
+    const provider = injected(['eip155:999'], { eip155: true })
+    expect(
+      pickAutoNetwork(
+        provider,
+        NETWORKS,
+        'injected',
+        DEFAULT_NAMESPACE_PRIORITY
+      )
+    ).toBeUndefined()
+  })
+})

package/src/services/network-selection.ts

@@ -0,0 +1,86 @@
+import type {
+  ConnectionMode,
+  Namespace,
+  Network,
+  NetworkId,
+  SupportedProvider
+} from '@meshconnect/uwc-types'
+
+/**
+ * Default namespace preference for an auto-picked connect network (no
+ * `networkId` passed): EVM first, then Solana, Tron, TON, Bitcoin. A caller
+ * policy, not a correctness rule — override it with `UWCConfig.preferredNamespaces`.
+ * Same order as the namespace unions used across the connectors.
+ */
+export const DEFAULT_NAMESPACE_PRIORITY: readonly Namespace[] = [
+  'eip155',
+  'solana',
+  'tron',
+  'tvm',
+  'bip122'
+]
+
+/**
+ * How the connect network was chosen, surfaced on the hand-off telemetry:
+ * - `explicit` — the caller passed a `networkId`.
+ * - `detected` — auto-picked among namespaces whose injected provider was
+ *   detected, ranked by the namespace preference, catalog order breaking ties.
+ * - `catalogOrder` — legacy pick: the first configured network in the wallet's
+ *   `supportedNetworkIds` (non-injected modes, or nothing detected yet).
+ */
+export type NetworkSelection = 'explicit' | 'detected' | 'catalogOrder'
+
+function isNamespaceInstalled(
+  provider: SupportedProvider,
+  namespace: Namespace
+): boolean {
+  if (!('namespaceMetaData' in provider)) return false
+  const meta = provider.namespaceMetaData[
+    namespace as keyof typeof provider.namespaceMetaData
+  ] as { installed?: boolean } | undefined
+  return meta?.installed === true
+}
+
+/**
+ * Picks the network for a connect that named none. Candidates are the wallet's
+ * `supportedNetworkIds` that are also configured, in catalog order.
+ *
+ * For an injected connect where detection marked at least one candidate's
+ * namespace installed, only installed namespaces are eligible (connecting on an
+ * undetected namespace can only fail — e.g. Trust mobile has no
+ * `trustWallet.tronLink`), ranked by `preferredNamespaces`, catalog order
+ * breaking ties. Every other case keeps the legacy first-candidate pick, so
+ * WalletConnect / TON Connect and pre-detection connects are unchanged.
+ * Returns `undefined` when no candidate exists (the caller throws).
+ */
+export function pickAutoNetwork(
+  provider: SupportedProvider,
+  networks: readonly Network[],
+  connectionMode: ConnectionMode,
+  preferredNamespaces: readonly Namespace[]
+): { networkId: NetworkId; selection: NetworkSelection } | undefined {
+  const candidates = provider.supportedNetworkIds
+    .map(id => networks.find(n => n.id === id))
+    .filter((n): n is Network => n !== undefined)
+  const first = candidates[0]
+  if (!first) return undefined
+
+  if (connectionMode === 'injected') {
+    const installed = candidates.filter(n =>
+      isNamespaceInstalled(provider, n.namespace)
+    )
+    if (installed.length > 0) {
+      const rank = (namespace: Namespace) => {
+        const index = preferredNamespaces.indexOf(namespace)
+        return index === -1 ? preferredNamespaces.length : index
+      }
+      // Array.prototype.sort is stable, so equal ranks keep catalog order.
+      const [best] = [...installed].sort(
+        (a, b) => rank(a.namespace) - rank(b.namespace)
+      )
+      if (best) return { networkId: best.id, selection: 'detected' }
+    }
+  }
+
+  return { networkId: first.id, selection: 'catalogOrder' }
+}