@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/universal-wallet-connector.ts

@@ -18,9 +18,9 @@ import type {
   EVMCapabilities,
   SignatureType,
   EIP712TypedData,
-  WalletError
+  LogLevel,
+  Logger
 } from '@meshconnect/uwc-types'
-import { WalletConnectorError } from '@meshconnect/uwc-types'
 import { InjectedConnector } from '@meshconnect/uwc-injected-connector'
 import { WalletConnectConnector } from '@meshconnect/uwc-wallet-connect-connector'
 import { TonConnectConnector } from '@meshconnect/uwc-ton-connector'
@@ -33,8 +33,22 @@ import { SignatureService } from './services/signature-service'
 import { TransactionService } from './services/transaction-service'
 import { WalletCapabilitiesService } from './services/wallet-capabilities-service'
 import { createNetworkRpcMap } from './utils/network-rpc-utils'
+import { generateId } from './utils/id'
+import {
+  toWalletError,
+  isAbortError,
+  classifyError
+} from './utils/to-wallet-error'
+import { NoCommonNetworkError } from '@meshconnect/uwc-types'
+import { createLogger, type ManagedLogger } from './logger/create-logger'
+import { connectObserver } from './observability/connect-observer'
+import type { UWCObserver } from './observability/telemetry'
+import { hasHandoffTerminal } from './observability/instrument-handoff'
 import type { UWCEventName, UWCEventListener, UWCOperation } from './events'
 
+/** Default observational wallet-response deadline (ms). Matches TON's 60s. */
+const DEFAULT_WALLET_RESPONSE_TIMEOUT_MS = 60_000
+
 /**
  * Configuration object form of the UniversalWalletConnector constructor.
  * Prefer this over the positional constructor in new code.
@@ -49,6 +63,38 @@ export interface UWCConfig {
   walletConnectConfig?: WalletConnectConfig
   tonConnectConfig?: TonConnectConfig
   tronConnectorConfig?: TronConnectorConfig
+  // ---- Observability (all optional; defaults preserve current behaviour) -----
+  /**
+   * Vendor-agnostic telemetry sink. When omitted, UWC emits NOTHING externally —
+   * zero egress is the security-first default for a sign-only wallet layer. The
+   * consumer implements the sink and wires it to their backend (Datadog/…).
+   */
+  observer?: UWCObserver
+  /**
+   * Redirect UWC's internal logging into your own logger. Receives raw
+   * `(message, ...args)` at/above `logLevel`. When omitted, a console-backed
+   * logger is used. LOCAL SINK by contract: args are NOT scrubbed here — do not
+   * wire this to a remote transport; use `observer.onLog` (scrubbed) for egress.
+   */
+  logger?: Logger
+  /** Console threshold for the default logger. Default `'warn'`. */
+  logLevel?: LogLevel
+  /**
+   * Consumer correlation id, surfaced as its OWN `correlationId` field on every
+   * telemetry record — never aliased onto the generated `sdkSessionId`, so
+   * "no id supplied" and "id == session" stay distinguishable. Supply your own
+   * (e.g. the consumer's `link_sess_id`) so UWC events join your existing
+   * telemetry in Datadog/RUM without a separate mapping. Pass a getter if the
+   * id isn't known at construction or can change; resolved per-event, and a
+   * throwing/empty getter OMITS the field for that record.
+   */
+  correlationId?: string | (() => string)
+  /**
+   * Observational wallet-response deadline (ms) for the `walletTimedOut` marker.
+   * `0` disables it. TON is always exempt (it bounds its own response). Default
+   * 60_000.
+   */
+  walletResponseTimeoutMs?: number
 }
 
 /** Common options for user-initiated async operations. */
@@ -75,6 +121,12 @@ export class UniversalWalletConnector {
   private usingIntegratedBrowser: boolean
   private detectionComplete = false
   private networkRpcMap: NetworkRpcMap
+  private logger: ManagedLogger
+  /** Per-instance correlation id stamped on every telemetry record. */
+  private readonly sdkSessionId: string = generateId()
+  private walletResponseTimeoutMs: number
+  /** Tears down the observer subscriptions; set only when an observer is wired. */
+  private observerTeardown: (() => void) | undefined
 
   /**
    * Recommended entry point: returns the shared instance, creating it on the
@@ -152,14 +204,54 @@ export class UniversalWalletConnector {
       tronConnectorConfig: configuredTronConnectorConfig
     } = config
 
+    // Observability seam — wire the event bus, logger, and (optional) observer
+    // FIRST so even construction-time logs/events are captured. `sdkSessionId` is
+    // already assigned as a field initializer.
+    this.eventManager = new EventManager()
+    this.walletResponseTimeoutMs =
+      config.walletResponseTimeoutMs ?? DEFAULT_WALLET_RESPONSE_TIMEOUT_MS
+    this.logger = createLogger({
+      level: config.logLevel ?? 'warn',
+      sink: config.logger,
+      // Pre-gate tap → typed `log` event → observer.onLog. Fires for all levels
+      // regardless of the console threshold.
+      onLog: (level, message, args) =>
+        this.eventManager.emit('log', { level, message, args })
+    })
+    if (config.observer) {
+      // Resolve the OPTIONAL consumer correlation id per-event so a consumer can
+      // align it to their own session key (e.g. link_sess_id). It is kept
+      // separate from the always-present generated `sdkSessionId` — never aliased
+      // — so a record can distinguish "no consumer id" from "id == session". A
+      // missing/empty value or a throwing getter yields `undefined` (no fallback).
+      const cid = config.correlationId
+      const getCorrelationId: () => string | undefined =
+        typeof cid === 'function'
+          ? () => {
+              try {
+                return cid() || undefined
+              } catch {
+                return undefined
+              }
+            }
+          : () => cid
+      this.observerTeardown = connectObserver(
+        this.eventManager,
+        config.observer,
+        this.sdkSessionId,
+        getCorrelationId,
+        Date.now,
+        this.logger
+      )
+    }
+
     // Track instance creation and warn on duplicates
     UniversalWalletConnector.instanceCount++
     if (
       UniversalWalletConnector.instanceCount > 1 &&
       !UniversalWalletConnector.hasWarnedAboutMultipleInstances
     ) {
-      // eslint-disable-next-line no-console
-      console.error(
+      this.logger.error(
         `⚠️ WARNING: Multiple instances of UniversalWalletConnector detected (${UniversalWalletConnector.instanceCount} instances). ` +
           'This can lead to state inconsistencies and unexpected behavior. ' +
           'Please ensure you create only one instance and reuse it throughout your application. ' +
@@ -197,7 +289,14 @@ export class UniversalWalletConnector {
       this.wallets,
       configuredTonConnectConfig,
       configuredTronConnectorConfig,
-      networks
+      networks,
+      // Surface BridgeChild discovery failures (the Bitstarz "wallet never
+      // appeared via the bridge" class) as a telemetry event.
+      info =>
+        this.eventManager.emit('bridgeError', {
+          namespace: info.namespace as Namespace,
+          error: { type: 'unknown', message: info.message }
+        })
     )
     this.connectors.set('injected', this.injectedConnector)
 
@@ -214,35 +313,51 @@ export class UniversalWalletConnector {
         'walletConnect',
         new WalletConnectConnector(
           configuredWalletConnectConfig,
-          this.networkRpcMap
+          this.networkRpcMap,
+          // Surface relay-socket failures (e.g. code 3000 JWT clock skew) that are
+          // detached from the connect handoff, as a telemetry event.
+          (error: unknown) =>
+            this.eventManager.emit('relayError', {
+              error: {
+                type: 'unknown',
+                message: error instanceof Error ? error.message : String(error)
+              }
+            })
         )
       )
     }
 
     this.sessionManager = new SessionManager()
-    this.eventManager = new EventManager()
     this.connectionService = new ConnectionService(
       networks,
       this.wallets,
       this.sessionManager,
       this.connectors,
       configuredUsingIntegratedBrowser,
-      this.eventManager
+      this.eventManager,
+      this.walletResponseTimeoutMs
     )
     this.networkSwitchService = new NetworkSwitchService(
       networks,
       this.sessionManager,
       this.connectors,
       configuredUsingIntegratedBrowser,
-      this.eventManager
+      this.eventManager,
+      this.walletResponseTimeoutMs
     )
     this.signatureService = new SignatureService(
       this.sessionManager,
-      this.connectors
+      this.connectors,
+      configuredUsingIntegratedBrowser,
+      this.eventManager,
+      this.walletResponseTimeoutMs
     )
     this.transactionService = new TransactionService(
       this.sessionManager,
-      this.connectors
+      this.connectors,
+      configuredUsingIntegratedBrowser,
+      this.eventManager,
+      this.walletResponseTimeoutMs
     )
     this.walletCapabilitiesService = new WalletCapabilitiesService(
       networks,
@@ -288,7 +403,7 @@ export class UniversalWalletConnector {
       // call, not the sum.
       const detectionTasks: Promise<void>[] = []
       for (const namespace of namespaces) {
-        for (const [, connector] of this.connectors) {
+        for (const [connectionMode, connector] of this.connectors) {
           if (typeof connector.getAvailableWallets !== 'function') continue
           detectionTasks.push(
             Promise.resolve()
@@ -303,8 +418,17 @@ export class UniversalWalletConnector {
                   this.applyDetectedWallet(namespace as Namespace, d)
                 }
               })
-              .catch(() => {
-                // Silently handle errors for individual connector/namespace combinations
+              .catch(error => {
+                // Was a silent catch — now a telemetry signal so a discovery
+                // failure (the "why didn't wallet X appear?" class) is observable
+                // rather than vanishing. STILL swallowed for control flow: one
+                // namespace × connector failing must not abort the others or
+                // reject detection.
+                this.eventManager.emit('walletDiscoveryFailed', {
+                  namespace: namespace as Namespace,
+                  connectionMode,
+                  error: toWalletError(error)
+                })
               })
           )
         }
@@ -317,7 +441,13 @@ export class UniversalWalletConnector {
       // Mark detection as complete
       this.detectionComplete = true
 
-      this.eventManager.emit('walletsDetected', { wallets: this.wallets })
+      // Per-namespace requested-vs-matched summary (counts only, non-PII) so a
+      // dashboard can tell "asked for N solana wallets, matched 0" (a metadata /
+      // config problem) from "asked for none".
+      this.eventManager.emit('walletsDetected', {
+        wallets: this.wallets,
+        discovery: this.summarizeDiscovery(namespaces)
+      })
       this.eventManager.emit('ready', undefined)
     } catch (error) {
       this.detectionComplete = true
@@ -459,6 +589,37 @@ export class UniversalWalletConnector {
     }
   }
 
+  /**
+   * Per-namespace requested-vs-matched counts after detection. `requested` =
+   * configured wallets that declared the namespace; `matched` = those now marked
+   * installed. Counts only — never a wallet id or address. Feeds `walletsDetected`
+   * so a dashboard can answer "asked for N, matched 0?".
+   */
+  private summarizeDiscovery(
+    namespaces: Set<string>
+  ): Record<string, { requested: number; matched: number }> {
+    const pickProvider = (w: WalletMetadata) =>
+      this.usingIntegratedBrowser
+        ? w.integratedBrowserInjectedProvider
+        : w.extensionInjectedProvider
+
+    const summary: Record<string, { requested: number; matched: number }> = {}
+    for (const namespace of namespaces) {
+      let requested = 0
+      let matched = 0
+      for (const wallet of this.wallets) {
+        const nsMeta = pickProvider(wallet)?.namespaceMetaData?.[
+          namespace as Namespace
+        ] as { installed?: boolean } | undefined
+        if (!nsMeta) continue
+        requested++
+        if (nsMeta.installed) matched++
+      }
+      summary[namespace] = { requested, matched }
+    }
+    return summary
+  }
+
   getSession() {
     return this.sessionManager.getSession()
   }
@@ -518,6 +679,9 @@ export class UniversalWalletConnector {
     options?: OperationOptions
   ): Promise<void> {
     try {
+      // Hand-off instrumentation lives in ConnectionService.connect (emitted
+      // after validation, at the real wallet boundary) — not here, so pre-wallet
+      // validation failures don't pollute the funnel.
       await this.connectionService.connect(
         connectionMode,
         walletId,
@@ -525,7 +689,7 @@ export class UniversalWalletConnector {
         options
       )
     } catch (error) {
-      this.emitError(error, 'connect')
+      this.emitError(error, 'connect', options?.signal)
       throw error
     }
   }
@@ -538,7 +702,7 @@ export class UniversalWalletConnector {
     try {
       await this.connectionService.disconnect(options)
     } catch (error) {
-      this.emitError(error, 'disconnect')
+      this.emitError(error, 'disconnect', options?.signal)
       throw error
     }
   }
@@ -547,10 +711,23 @@ export class UniversalWalletConnector {
     networkId: NetworkId,
     options?: OperationOptions
   ): Promise<void> {
+    // Captured before the switch so a cross-namespace move is detectable after.
+    const previousNamespace =
+      this.sessionManager.getSession().activeNetwork?.namespace
     try {
+      // Hand-off instrumentation lives in NetworkSwitchService.switchNetwork
+      // (emitted after validation, at the real wallet boundary).
       await this.networkSwitchService.switchNetwork(networkId, options)
+      // A cross-namespace switch changes the live provider, so the connect-time
+      // lifecycle subscription would keep observing the OLD namespace's provider
+      // and label its events with the new session's routing. Re-evaluate it.
+      const nextNamespace =
+        this.sessionManager.getSession().activeNetwork?.namespace
+      if (nextNamespace !== undefined && nextNamespace !== previousNamespace) {
+        this.connectionService.reattachLifecycle()
+      }
     } catch (error) {
-      this.emitError(error, 'switchNetwork')
+      this.emitError(error, 'switchNetwork', options?.signal)
       throw error
     }
   }
@@ -569,40 +746,12 @@ export class UniversalWalletConnector {
     message: string,
     options?: OperationOptions
   ): Promise<SignatureType> {
-    const session = this.sessionManager.getSession()
-
-    if (!session.activeWallet) {
-      throw new Error('No active wallet')
-    }
-
-    if (!session.connectionMode) {
-      throw new Error('No active connection')
-    }
-
     try {
-      // Get the provider from the active wallet based on connection mode
-      let provider
-      if (session.connectionMode === 'injected') {
-        provider = this.usingIntegratedBrowser
-          ? session.activeWallet.integratedBrowserInjectedProvider
-          : session.activeWallet.extensionInjectedProvider
-      } else if (session.connectionMode === 'walletConnect') {
-        provider = session.activeWallet.walletConnectProvider
-      } else if (session.connectionMode === 'tonConnect') {
-        return await this.signatureService.signMessage(
-          message,
-          undefined,
-          options
-        )
-      }
-
-      if (!provider) {
-        throw new Error('No provider available for the active wallet')
-      }
-
-      return await this.signatureService.signMessage(message, provider, options)
+      // Validation + funnel instrumentation live in SignatureService (after
+      // validation, at the real wallet boundary) — same layering as connect.
+      return await this.signatureService.signMessage(message, options)
     } catch (error) {
-      this.emitError(error, 'signMessage')
+      this.emitError(error, 'signMessage', options?.signal)
       throw error
     }
   }
@@ -616,34 +765,13 @@ export class UniversalWalletConnector {
    * @returns A promise that resolves to the 65-byte hex signature (0x-prefixed)
    */
   async signTypedData(typedData: EIP712TypedData): Promise<string> {
-    const session = this.sessionManager.getSession()
-
-    if (!session.activeWallet) {
-      throw new Error('No active wallet')
-    }
-
-    if (!session.connectionMode) {
-      throw new Error('No active connection')
-    }
-
-    if (session.connectionMode === 'tonConnect') {
-      throw new Error('signTypedData is not supported for TON wallets')
-    }
-
-    // Resolve the injected provider from the active wallet. WalletConnect
-    // resolves its own provider inside the connector, so it stays undefined here.
-    let provider
-    if (session.connectionMode === 'injected') {
-      provider = this.usingIntegratedBrowser
-        ? session.activeWallet.integratedBrowserInjectedProvider
-        : session.activeWallet.extensionInjectedProvider
-
-      if (!provider) {
-        throw new Error('No provider available for the active wallet')
-      }
+    try {
+      // Validation + funnel instrumentation live in SignatureService.
+      return await this.signatureService.signTypedData(typedData)
+    } catch (error) {
+      this.emitError(error, 'signTypedData')
+      throw error
     }
-
-    return await this.signatureService.signTypedData(typedData, provider)
   }
 
   /**
@@ -656,44 +784,12 @@ export class UniversalWalletConnector {
     request: TransactionRequest,
     options?: OperationOptions
   ): Promise<TransactionResult> {
-    const session = this.sessionManager.getSession()
-
-    if (!session.activeWallet) {
-      throw new Error('No active wallet')
-    }
-
-    if (!session.connectionMode) {
-      throw new Error('No active connection')
-    }
-
     try {
-      // Get the provider from the active wallet based on connection mode
-      let provider
-      if (session.connectionMode === 'injected') {
-        provider = this.usingIntegratedBrowser
-          ? session.activeWallet.integratedBrowserInjectedProvider
-          : session.activeWallet.extensionInjectedProvider
-      } else if (session.connectionMode === 'walletConnect') {
-        provider = session.activeWallet.walletConnectProvider
-      } else if (session.connectionMode === 'tonConnect') {
-        return await this.transactionService.sendTransaction(
-          request,
-          undefined,
-          options
-        )
-      }
-
-      if (!provider) {
-        throw new Error('No provider available for the active wallet')
-      }
-
-      return await this.transactionService.sendTransaction(
-        request,
-        provider,
-        options
-      )
+      // Validation + funnel instrumentation live in TransactionService (after
+      // validation, at the real wallet boundary) — same layering as connect.
+      return await this.transactionService.sendTransaction(request, options)
     } catch (error) {
-      this.emitError(error, 'sendTransaction')
+      this.emitError(error, 'sendTransaction', options?.signal)
       throw error
     }
   }
@@ -704,25 +800,15 @@ export class UniversalWalletConnector {
    * tonConnect doesn't implement it.
    */
   async signSolanaTransaction(serializedTx: Uint8Array): Promise<Uint8Array> {
-    const session = this.sessionManager.getSession()
-
-    if (!session.activeWallet) {
-      throw new Error('No active wallet')
-    }
-
-    if (!session.connectionMode) {
-      throw new Error('No active connection')
-    }
-
-    // The active connector must implement the optional signSolanaTransactionBytes.
-    const connector = this.connectors.get(session.connectionMode)
-    if (!connector?.signSolanaTransactionBytes) {
-      throw new Error(
-        `signSolanaTransaction is not supported for connection mode "${session.connectionMode}"`
+    try {
+      // Validation + funnel instrumentation live in TransactionService.
+      return await this.transactionService.signSolanaTransactionBytes(
+        serializedTx
       )
+    } catch (error) {
+      this.emitError(error, 'signSolanaTransaction')
+      throw error
     }
-
-    return await connector.signSolanaTransactionBytes(serializedTx)
   }
 
   /**
@@ -744,7 +830,7 @@ export class UniversalWalletConnector {
         options
       )
     } catch (error) {
-      this.emitError(error, 'getWalletCapabilities')
+      this.emitError(error, 'getWalletCapabilities', options?.signal)
       throw error
     }
   }
@@ -809,22 +895,73 @@ export class UniversalWalletConnector {
     return session.activeWalletCapabilities
   }
 
+  /**
+   * Set the console log threshold at runtime (e.g. from a support toggle). The
+   * global `window.UWC_DEBUG` override still takes precedence for ad-hoc triage.
+   */
+  setLogLevel(level: LogLevel): void {
+    this.logger.setLevel(level)
+  }
+
+  /**
+   * Release observer subscriptions and clear all event listeners. Call on full
+   * teardown / logout to avoid leaking listeners across connector lifecycles.
+   */
+  dispose(): void {
+    this.observerTeardown?.()
+    this.observerTeardown = undefined
+    // Release any live provider-lifecycle listeners on a connected session —
+    // `dispose()` can be called without a prior `disconnect()`, and leaving the
+    // EIP-1193/adapter `.on` handlers attached is the zombie-listener leak this
+    // method's contract promises to prevent.
+    this.connectionService.teardownLifecycle()
+    this.eventManager.clearAllListeners()
+    // Full teardown: if this was the shared singleton, clear the static refs too
+    // so a later getInstance()/new starts clean — otherwise getInstance() would
+    // hand back this now-listener-less instance, and the instance-count warning
+    // would mis-fire on the next construction.
+    if (UniversalWalletConnector.instance === this) {
+      UniversalWalletConnector.resetInstance()
+    }
+  }
+
   // ---- private helpers ----
 
-  private emitError(error: unknown, operation: UWCOperation): void {
+  private emitError(
+    error: unknown,
+    operation: UWCOperation,
+    signal?: AbortSignal
+  ): void {
     // Intentional cancellations (AbortSignal.throwIfAborted, fetch abort,
     // DOMException) should NOT surface as wallet errors — the caller already
-    // knows it asked to abort. Skip emission so error telemetry stays clean.
-    if (error instanceof Error && error.name === 'AbortError') {
+    // knows it asked to abort. Uses the same name+signal check as
+    // `instrumentHandoff`, so both a DOMException abort (not an `Error`
+    // subclass in every runtime) AND a custom `abort(reason)` — whose rejection
+    // value carries the caller's own name — are skipped consistently.
+    if (isAbortError(error) || signal?.aborted) {
       return
     }
-    const walletError: WalletError =
-      error instanceof WalletConnectorError
-        ? { type: error.type, message: error.message }
-        : {
-            type: 'unknown',
-            message: error instanceof Error ? error.message : String(error)
-          }
-    this.eventManager.emit('error', { error: walletError, operation })
+    // Classify here too so a PRE-wallet validation failure — which never enters
+    // the handoff funnel (no awaitingWallet/terminal) — still carries
+    // failureKind/source/errorCode in telemetry. The #1 prod connection error,
+    // `no_common_network`, lands here; forward its two CAIP-2 id lists.
+    const { errorCode, failureKind, source } = classifyError(error)
+    this.eventManager.emit('error', {
+      error: toWalletError(error),
+      operation,
+      errorCode,
+      failureKind,
+      source,
+      // A handoff terminal already reported this failure — mark this record as
+      // the back-compat duplicate so metrics can count terminals + uncovered
+      // errors without double-counting.
+      ...(hasHandoffTerminal(error) && { handoffCovered: true }),
+      ...(error instanceof NoCommonNetworkError && {
+        networkMismatch: {
+          walletNetworkIds: error.walletNetworkIds,
+          configuredNetworkIds: error.configuredNetworkIds
+        }
+      })
+    })
   }
 }

package/src/utils/id.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest'
+import { generateId } from './id'
+
+describe('generateId', () => {
+  it('produces unique values', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => generateId()))
+    expect(ids.size).toBe(1000)
+  })
+
+  it('produces a non-empty string', () => {
+    const id = generateId()
+    expect(typeof id).toBe('string')
+    expect(id.length).toBeGreaterThan(0)
+  })
+})

package/src/utils/id.ts

@@ -0,0 +1,48 @@
+/**
+ * Generate a correlation id (RFC-4122 v4 when available).
+ *
+ * Used for the per-instance `sdkSessionId` and per-handoff `handoffId` — both are
+ * opaque correlation tokens, never derived from wallet data (no address, no key).
+ * Prefers the native `crypto.randomUUID()` (browsers + Node ≥ 16); falls back to a
+ * `crypto.getRandomValues`-backed v4, and finally to a timestamp + monotonic
+ * counter only in environments that expose neither. Correlation ids need to be
+ * collision-resistant enough to pair a start event with its terminal — NOT
+ * cryptographically unpredictable — so the last-resort branch uses no PRNG.
+ */
+// Monotonic counter for the no-crypto fallback: guarantees per-process uniqueness
+// without any pseudo-random generator (correlation ids need uniqueness, not
+// unpredictability — and a counter is strictly more collision-resistant here).
+let fallbackCounter = 0
+
+export function generateId(): string {
+  const c = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined
+
+  if (c?.randomUUID) {
+    return c.randomUUID()
+  }
+
+  if (c?.getRandomValues) {
+    const bytes = c.getRandomValues(new Uint8Array(16))
+    // Set the version (4) and variant (10xx) bits per RFC 4122 §4.4.
+    bytes[6] = (bytes[6]! & 0x0f) | 0x40
+    bytes[8] = (bytes[8]! & 0x3f) | 0x80
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0'))
+    return (
+      hex.slice(0, 4).join('') +
+      '-' +
+      hex.slice(4, 6).join('') +
+      '-' +
+      hex.slice(6, 8).join('') +
+      '-' +
+      hex.slice(8, 10).join('') +
+      '-' +
+      hex.slice(10, 16).join('')
+    )
+  }
+
+  // Last-resort fallback (no Web Crypto). Timestamp + monotonic counter keeps
+  // ids unique within the process without a PRNG. Sufficient for correlation.
+  return (
+    'uwc-' + Date.now().toString(36) + '-' + (fallbackCounter++).toString(36)
+  )
+}