@meshconnect/uwc-core 1.0.3 → 1.1.0

package/dist/observability/connect-observer.js

@@ -0,0 +1,115 @@
+import { createBoundedDedup, safeErrorMessage } from '@meshconnect/uwc-types';
+import { UWC_EVENT_NAMES } from '../events';
+import { normalizeEvent } from './telemetry';
+import { scrubArgs, scrubMessage } from './scrub';
+/**
+ * Bridge the internal event bus to a consumer-supplied `UWCObserver`.
+ *
+ * Subscribes to every `UWCEventMap` event, normalizes each to a PII-safe
+ * `UWCTelemetryEvent`, and forwards it to `observer.onEvent`. The `log` event is
+ * routed to `observer.onLog` instead (with scrubbed args) — it's the logging
+ * channel, not a telemetry record. `change` is skipped: it's the legacy
+ * re-render cascade and carries no payload.
+ *
+ * Returns a teardown function that removes every subscription. The caller MUST
+ * invoke it on connector teardown — leaving these attached is the same listener-
+ * leak class as the historical `BridgeParent.destroy()` zombie bug.
+ *
+ * @param sdkSessionId - per-connector-instance id stamped on every record.
+ * @param getCorrelationId - resolves the optional consumer correlation id,
+ *   called per-event so an id that arrives/changes after construction is
+ *   honoured. Must not throw (the caller pre-wraps it). Defaults to `undefined`.
+ * @param now - clock injectable for deterministic tests; defaults to `Date.now`.
+ * @param logger - optional; a throwing observer is reported via `logger.debug`.
+ *   When omitted the throw is swallowed silently (the historical behaviour).
+ */
+/**
+ * Cap on distinct observer-error messages remembered for dedup. Same storm-guard
+ * contract as the relay/bridge dedup sets: bounding keeps memory flat on a
+ * long-lived instance even when a broken observer throws high-cardinality
+ * messages (e.g. embedding event data or timestamps).
+ */
+export const MAX_REPORTED_OBSERVER_ERRORS = 100;
+export function connectObserver(eventManager, observer, sdkSessionId, getCorrelationId = () => undefined, now = Date.now, logger) {
+    const unsubscribers = [];
+    // Set while we log an observer failure so the resulting `logger.debug(...)` —
+    // which re-enters the bus as a `log` event — is NOT forwarded back to the same
+    // (throwing) observer, which would recurse. One logical dispatch at a time.
+    let loggingObserverError = false;
+    // "Once per error site": dedupe by the error's message so a wallet whose
+    // observer throws on every event logs once, not on a tight loop. Scoped to THIS
+    // connector instance (not module-global) so one connector's failures don't
+    // suppress another's; bounded so it can't grow for the instance's lifetime.
+    const observerErrorDedup = createBoundedDedup(MAX_REPORTED_OBSERVER_ERRORS);
+    const reportObserverError = (err) => {
+        if (!logger)
+            return;
+        // safeErrorMessage: a poisoned getter / throwing toString on the observer's
+        // own error must not escape this reporter, and the dedup key stays bounded.
+        const key = safeErrorMessage(err);
+        if (!observerErrorDedup.firstSeen(key))
+            return;
+        loggingObserverError = true;
+        try {
+            logger.debug('UWC observer threw', err);
+        }
+        finally {
+            loggingObserverError = false;
+        }
+    };
+    for (const name of UWC_EVENT_NAMES) {
+        if (name === 'change')
+            continue;
+        if (name === 'log') {
+            unsubscribers.push(eventManager.on('log', data => {
+                if (!observer.onLog)
+                    return;
+                // The observer-error debug log re-enters here as a `log` event; drop it
+                // so we never forward our own failure notice back to the bad observer.
+                if (loggingObserverError)
+                    return;
+                const { level, message, args } = data;
+                try {
+                    // Scrub the message too, not just args: the message reaches the same
+                    // consumer sink, so the egress contract can't rely on every internal
+                    // log string staying free of dynamic (potentially sensitive) data.
+                    observer.onLog(level, scrubMessage(message), scrubArgs(args));
+                }
+                catch (err) {
+                    // A throwing observer must not break the dispatch chain.
+                    reportObserverError(err);
+                }
+            }));
+            continue;
+        }
+        unsubscribers.push(eventManager.on(name, data => {
+            if (!observer.onEvent)
+                return;
+            // Resolve the id in its OWN guard: a throwing getter is a config
+            // problem, not an observer failure — degrade to "no id" (the getter's
+            // documented contract) instead of dropping the record.
+            let correlationId;
+            try {
+                correlationId = getCorrelationId();
+            }
+            catch {
+                correlationId = undefined;
+            }
+            try {
+                // Normalize OUTSIDE the EventManager's own try/catch (which guards the
+                // listener, not the work the listener does), then hand off.
+                observer.onEvent(normalizeEvent(name, data, sdkSessionId, now(), correlationId));
+            }
+            catch (err) {
+                // Same: never let a bad observer break other listeners.
+                reportObserverError(err);
+            }
+        }));
+    }
+    return () => {
+        for (const unsubscribe of unsubscribers)
+            unsubscribe();
+        unsubscribers.length = 0;
+    };
+}
+//# sourceMappingURL=connect-observer.js.map

package/dist/observability/connect-observer.js.map

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

package/dist/observability/focus-tracker.d.ts

@@ -0,0 +1,42 @@
+import type { Platform } from '@meshconnect/uwc-types';
+import type { EventManager } from '../managers/event-manager';
+/**
+ * Minimal `document` surface this tracker touches. Declared locally (rather than
+ * relying on the DOM lib) so the module is SSR-safe and trivially testable with a
+ * fake — no jsdom required.
+ */
+export interface FocusDocumentLike {
+    visibilityState?: string;
+    hidden?: boolean;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+/**
+ * Minimal `window` surface for the `pageshow` listener. Separate from
+ * `FocusDocumentLike` because the two events have different targets:
+ * `visibilitychange` fires on `document`, while `pageshow` is a WINDOW event
+ * (HTML spec / MDN: "sent to a Window") — a document-level listener would never
+ * fire in a real browser.
+ */
+export interface FocusWindowLike {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+/**
+ * While a wallet handoff is pending, emit a FACT on every tab-visibility
+ * transition — `pageHiddenDuringHandoff` when the page is backgrounded (the user
+ * likely left for the wallet app), `pageVisibleDuringHandoff` when it returns
+ * (including a bfcache `pageshow`, which iOS uses when coming back from a wallet).
+ *
+ * This is the raw signal behind "did the user actually app-switch to the wallet?"
+ * for deep-link flows — it does NOT interpret abandonment. The listeners are
+ * scoped to the single handoff: attach right after `awaitingWallet`, and the
+ * returned teardown (called the instant the op settles) removes them, so the
+ * page's visibility is only observed during the blind window. SSR-safe (no-op
+ * when there is neither `document` nor `window`).
+ *
+ * @returns a teardown that removes the listeners. Always call it (even when
+ *   nothing was attached — it's a no-op then) to keep the call site symmetric.
+ */
+export declare function trackFocusDuringHandoff(eventManager: EventManager, handoffId: string, platform: Platform, doc?: FocusDocumentLike | undefined, win?: FocusWindowLike | undefined): () => void;
+//# sourceMappingURL=focus-tracker.d.ts.map

package/dist/observability/focus-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-tracker.d.ts","sourceRoot":"","sources":["../../src/observability/focus-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAC1D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAC9D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAC1D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAC9D;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,GAAG,GAAE,iBAAiB,GAAG,SAA6B,EACtD,GAAG,GAAE,eAAe,GAAG,SAA2B,GACjD,MAAM,IAAI,CAoCZ"}

package/dist/observability/focus-tracker.js

@@ -0,0 +1,57 @@
+function resolveDocument() {
+    const doc = globalThis.document;
+    return doc && typeof doc.addEventListener === 'function' ? doc : undefined;
+}
+function resolveWindow() {
+    const win = globalThis.window;
+    return win && typeof win.addEventListener === 'function' ? win : undefined;
+}
+/**
+ * While a wallet handoff is pending, emit a FACT on every tab-visibility
+ * transition — `pageHiddenDuringHandoff` when the page is backgrounded (the user
+ * likely left for the wallet app), `pageVisibleDuringHandoff` when it returns
+ * (including a bfcache `pageshow`, which iOS uses when coming back from a wallet).
+ *
+ * This is the raw signal behind "did the user actually app-switch to the wallet?"
+ * for deep-link flows — it does NOT interpret abandonment. The listeners are
+ * scoped to the single handoff: attach right after `awaitingWallet`, and the
+ * returned teardown (called the instant the op settles) removes them, so the
+ * page's visibility is only observed during the blind window. SSR-safe (no-op
+ * when there is neither `document` nor `window`).
+ *
+ * @returns a teardown that removes the listeners. Always call it (even when
+ *   nothing was attached — it's a no-op then) to keep the call site symmetric.
+ */
+export function trackFocusDuringHandoff(eventManager, handoffId, platform, doc = resolveDocument(), win = resolveWindow()) {
+    if (!doc && !win)
+        return () => { };
+    // One physical return can fire BOTH `pageshow` (window) and a
+    // `visibilitychange`→visible (document) — an iOS bfcache restore does. Dedupe
+    // consecutive same-state emits so the hidden/visible events actually pair.
+    let lastState;
+    const emitState = (state) => {
+        if (state === lastState)
+            return;
+        lastState = state;
+        eventManager.emit(state === 'hidden'
+            ? 'pageHiddenDuringHandoff'
+            : 'pageVisibleDuringHandoff', { handoffId, platform });
+    };
+    const onVisibility = () => {
+        const hidden = doc?.visibilityState === 'hidden' || doc?.hidden === true;
+        emitState(hidden ? 'hidden' : 'visible');
+    };
+    // `pageshow` fires on a bfcache restore (returning from the wallet app on iOS),
+    // a "came back" signal `visibilitychange` doesn't always deliver. It targets
+    // the WINDOW — attaching it to `document` would silently never fire.
+    const onPageShow = () => {
+        emitState('visible');
+    };
+    doc?.addEventListener('visibilitychange', onVisibility);
+    win?.addEventListener('pageshow', onPageShow);
+    return () => {
+        doc?.removeEventListener('visibilitychange', onVisibility);
+        win?.removeEventListener('pageshow', onPageShow);
+    };
+}
+//# sourceMappingURL=focus-tracker.js.map

package/dist/observability/focus-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-tracker.js","sourceRoot":"","sources":["../../src/observability/focus-tracker.ts"],"names":[],"mappings":"AA2BA,SAAS,eAAe;IACtB,MAAM,GAAG,GAAI,UAA+C,CAAC,QAAQ,CAAA;IACrE,OAAO,GAAG,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5E,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,GAAG,GAAI,UAA2C,CAAC,MAAM,CAAA;IAC/D,OAAO,GAAG,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CACrC,YAA0B,EAC1B,SAAiB,EACjB,QAAkB,EAClB,MAAqC,eAAe,EAAE,EACtD,MAAmC,aAAa,EAAE;IAElD,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IAEjC,8DAA8D;IAC9D,8EAA8E;IAC9E,2EAA2E;IAC3E,IAAI,SAA2C,CAAA;IAC/C,MAAM,SAAS,GAAG,CAAC,KAA2B,EAAE,EAAE;QAChD,IAAI,KAAK,KAAK,SAAS;YAAE,OAAM;QAC/B,SAAS,GAAG,KAAK,CAAA;QACjB,YAAY,CAAC,IAAI,CACf,KAAK,KAAK,QAAQ;YAChB,CAAC,CAAC,yBAAyB;YAC3B,CAAC,CAAC,0BAA0B,EAC9B,EAAE,SAAS,EAAE,QAAQ,EAAE,CACxB,CAAA;IACH,CAAC,CAAA;IAED,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,MAAM,MAAM,GAAG,GAAG,EAAE,eAAe,KAAK,QAAQ,IAAI,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;QACxE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC1C,CAAC,CAAA;IACD,gFAAgF;IAChF,6EAA6E;IAC7E,qEAAqE;IACrE,MAAM,UAAU,GAAG,GAAG,EAAE;QACtB,SAAS,CAAC,SAAS,CAAC,CAAA;IACtB,CAAC,CAAA;IAED,GAAG,EAAE,gBAAgB,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAA;IACvD,GAAG,EAAE,gBAAgB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;IAE7C,OAAO,GAAG,EAAE;QACV,GAAG,EAAE,mBAAmB,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAA;QAC1D,GAAG,EAAE,mBAAmB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;IAClD,CAAC,CAAA;AACH,CAAC"}

package/dist/observability/instrument-handoff.d.ts

@@ -0,0 +1,54 @@
+import type { ConnectionMode, Namespace, NetworkId, Session } from '@meshconnect/uwc-types';
+import type { EventManager } from '../managers/event-manager';
+import type { UWCOperation } from '../events';
+/** Routing facets known at the moment of a wallet handoff. No address, no payload. */
+export interface HandoffContext {
+    operation: UWCOperation;
+    connectionMode: ConnectionMode;
+    walletId?: string | undefined;
+    namespace?: Namespace | undefined;
+    chainId?: NetworkId | undefined;
+    /** switchNetwork only: target chain already the active one (no-op switch). */
+    targetAlreadyActive?: boolean | undefined;
+}
+/** Build handoff routing facets from the active session (no address). */
+export declare function sessionHandoffContext(operation: UWCOperation, session: Session): HandoffContext;
+/** Whether this thrown value already produced a handoff terminal. */
+export declare function hasHandoffTerminal(error: unknown): boolean;
+export interface InstrumentHandoffOptions {
+    eventManager: EventManager;
+    /**
+     * Deadline after which `walletTimedOut` fires as a SIDE marker (never rejects).
+     * `0` disables the marker. `tonConnect` is always skipped — TON bounds its own
+     * wallet response internally, so a second observational timer would be noise.
+     */
+    timeoutMs: number;
+    /**
+     * The caller's cancellation signal, when the op accepts one. Consulted in the
+     * catch path: a rejection observed while the signal is aborted is treated as
+     * the cancellation itself (no terminal) even when the rejection value is a
+     * custom `abort(reason)` — which is NOT an AbortError by name.
+     */
+    signal?: AbortSignal | undefined;
+    /** Clock injectable for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Instrument one wallet-boundary op so the blind window is measured.
+ *
+ * Emits `awaitingWallet` immediately (before the await that hands control to the
+ * wallet), then exactly one terminal — `walletSucceeded` (success),
+ * `walletRejected` (explicit user no), or `walletFailed` (any other error) — all
+ * carrying the same `handoffId` and a `durationMs`. An intentional abort emits no
+ * terminal (the caller cancelled; it isn't a wallet outcome) — services check
+ * their signal AFTER this wrapper returns, so a wallet op that settled before
+ * the abort still records its truthful terminal first.
+ *
+ * A non-cancelling `walletTimedOut` marker fires if the deadline passes while the
+ * op is still pending; it is cleared the instant the op settles, so a fast op
+ * never false-fires it, and it NEVER rejects/aborts/mutates state — the wrapped
+ * promise stays the single terminal source of truth. This is a deliberate
+ * deviation from TON's cancelling `withWalletResponseTimeout`.
+ */
+export declare function instrumentHandoff<T>(options: InstrumentHandoffOptions, context: HandoffContext, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=instrument-handoff.d.ts.map

package/dist/observability/instrument-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument-handoff.d.ts","sourceRoot":"","sources":["../../src/observability/instrument-handoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,SAAS,EACT,OAAO,EACR,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAW7C,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,YAAY,CAAA;IACvB,cAAc,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACjC,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC/B,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC1C;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,OAAO,GACf,cAAc,CAQhB;AAmBD,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM1D;AAQD,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IAChC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAmHZ"}

package/dist/observability/instrument-handoff.js

@@ -0,0 +1,173 @@
+import { generateId } from '../utils/id';
+import { classifyError, isAbortError, isUserRejection, toWalletError } from '../utils/to-wallet-error';
+import { derivePlatform, deriveWalletFlowType } from './telemetry';
+import { trackFocusDuringHandoff } from './focus-tracker';
+/** Build handoff routing facets from the active session (no address). */
+export function sessionHandoffContext(operation, session) {
+    return {
+        operation,
+        connectionMode: session.connectionMode ?? 'injected',
+        walletId: session.activeWallet?.id,
+        namespace: session.activeNetwork?.namespace,
+        chainId: session.activeNetwork?.id ?? undefined
+    };
+}
+/**
+ * Errors that already produced a funnel terminal (`walletRejected` /
+ * `walletFailed`). `emitError` reads this to tag its back-compat `error` record
+ * as `handoffCovered`, so a dashboard can count wallet failures from terminals
+ * and pre-wallet failures from `error` without double-counting. A WeakSet keyed
+ * on the error object — no mutation of the thrown value, and entries die with
+ * the error.
+ *
+ * DOCUMENTED GAP: a WeakSet cannot hold primitives. A wallet that rejects with
+ * a bare string/number still produces its terminal, but the façade's `error`
+ * record can't be marked — that failure double-counts under the "terminals +
+ * uncovered `error`" metric. Accepted: EIP-1193 requires object errors, and
+ * wrapping the thrown value to make it markable would mutate what the caller
+ * receives.
+ */
+const handoffTerminalErrors = new WeakSet();
+/** Whether this thrown value already produced a handoff terminal. */
+export function hasHandoffTerminal(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        handoffTerminalErrors.has(error));
+}
+function markHandoffTerminal(error) {
+    if (typeof error === 'object' && error !== null) {
+        handoffTerminalErrors.add(error);
+    }
+}
+/**
+ * Instrument one wallet-boundary op so the blind window is measured.
+ *
+ * Emits `awaitingWallet` immediately (before the await that hands control to the
+ * wallet), then exactly one terminal — `walletSucceeded` (success),
+ * `walletRejected` (explicit user no), or `walletFailed` (any other error) — all
+ * carrying the same `handoffId` and a `durationMs`. An intentional abort emits no
+ * terminal (the caller cancelled; it isn't a wallet outcome) — services check
+ * their signal AFTER this wrapper returns, so a wallet op that settled before
+ * the abort still records its truthful terminal first.
+ *
+ * A non-cancelling `walletTimedOut` marker fires if the deadline passes while the
+ * op is still pending; it is cleared the instant the op settles, so a fast op
+ * never false-fires it, and it NEVER rejects/aborts/mutates state — the wrapped
+ * promise stays the single terminal source of truth. This is a deliberate
+ * deviation from TON's cancelling `withWalletResponseTimeout`.
+ */
+export async function instrumentHandoff(options, context, fn) {
+    const { eventManager, timeoutMs } = options;
+    const now = options.now ?? Date.now;
+    const handoffId = generateId();
+    const platform = derivePlatform();
+    const start = now();
+    // Flipped by the observational timeout timer; rides every terminal so a late
+    // completion is distinguishable from a fast one without a handoffId self-join.
+    let timedOut = false;
+    eventManager.emit('awaitingWallet', {
+        operation: context.operation,
+        connectionMode: context.connectionMode,
+        walletId: context.walletId,
+        namespace: context.namespace,
+        chainId: context.chainId,
+        handoffId,
+        walletFlowType: deriveWalletFlowType(context.connectionMode, platform),
+        platform,
+        ...(context.targetAlreadyActive !== undefined && {
+            targetAlreadyActive: context.targetAlreadyActive
+        })
+    });
+    // Observe page-visibility transitions ONLY while this handoff is pending — the
+    // app-switch signal for deep-link flows (left for the wallet / came back). The
+    // teardown in `finally` removes the listeners the instant the op settles.
+    const stopFocus = trackFocusDuringHandoff(eventManager, handoffId, platform);
+    // Same routing facets as `awaitingWallet` so every terminal is self-describing
+    // (no handoffId self-join needed to know which wallet / chain / mode it closed).
+    const routing = {
+        connectionMode: context.connectionMode,
+        walletId: context.walletId,
+        namespace: context.namespace,
+        chainId: context.chainId,
+        ...(context.targetAlreadyActive !== undefined && {
+            targetAlreadyActive: context.targetAlreadyActive
+        })
+    };
+    const shouldTime = timeoutMs > 0 && context.connectionMode !== 'tonConnect';
+    const timer = shouldTime
+        ? setTimeout(() => {
+            timedOut = true;
+            eventManager.emit('walletTimedOut', {
+                handoffId,
+                operation: context.operation,
+                durationMs: now() - start,
+                timeoutMs,
+                ...routing
+            });
+        }, timeoutMs)
+        : undefined;
+    try {
+        const result = await fn();
+        eventManager.emit('walletSucceeded', {
+            handoffId,
+            operation: context.operation,
+            durationMs: now() - start,
+            timedOut,
+            timeoutMs: timedOut ? timeoutMs : undefined,
+            ...routing
+        });
+        return result;
+    }
+    catch (error) {
+        // Caller-driven cancellation isn't a wallet outcome — leave it unterminated,
+        // mirroring the façade's `emitError` AbortError skip. Checked BEFORE rejection
+        // is safe: real user rejections surface as WalletConnectorError{rejected} or
+        // EIP-1193 4001 (see isUserRejection), never as an AbortError — within UWC's
+        // dependency surface AbortError is produced only by the caller's AbortSignal.
+        // The signal covers `abort(customReason)`, whose rejection value carries the
+        // caller's own name; a real wallet failure that lands while the caller has
+        // already aborted is intentionally folded into the cancellation — the caller
+        // walked away, so the outcome no longer describes a user-visible interaction.
+        if (isAbortError(error) || options.signal?.aborted)
+            throw error;
+        const durationMs = now() - start;
+        const { errorCode, failureKind, source } = classifyError(error);
+        // Either branch below emits a terminal for this error — record that so the
+        // façade's back-compat `error` event can mark itself as a duplicate.
+        markHandoffTerminal(error);
+        if (isUserRejection(error)) {
+            eventManager.emit('walletRejected', {
+                handoffId,
+                operation: context.operation,
+                durationMs,
+                timedOut,
+                timeoutMs: timedOut ? timeoutMs : undefined,
+                errorCode,
+                failureKind,
+                source,
+                ...routing
+            });
+        }
+        else {
+            eventManager.emit('walletFailed', {
+                handoffId,
+                operation: context.operation,
+                durationMs,
+                error: toWalletError(error),
+                timedOut,
+                timeoutMs: timedOut ? timeoutMs : undefined,
+                errorCode,
+                failureKind,
+                source,
+                ...routing
+            });
+        }
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        stopFocus();
+    }
+}
+//# sourceMappingURL=instrument-handoff.js.map

package/dist/observability/instrument-handoff.js.map

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

package/dist/observability/lifecycle-bridge.d.ts

@@ -0,0 +1,69 @@
+import type { WalletLifecycleEvent, ConnectionMode, Namespace, NetworkId } from '@meshconnect/uwc-types';
+import type { EventManager } from '../managers/event-manager';
+/** Routing facets stamped on every lifecycle event. No address. */
+export interface LifecycleRouting {
+    connectionMode: ConnectionMode;
+    walletId?: string | undefined;
+    namespace?: Namespace | undefined;
+}
+/**
+ * Hard ceiling on lifecycle emissions per attachment. Every other telemetry
+ * sink this layer added is bounded (relay / bridge / observer-error dedup sets
+ * cap at 100); a provider looping `chainChanged`/`accountsChanged` must not be
+ * the one unbounded path to the observer. A legitimate session stays far below
+ * this; a storming provider goes silent instead of driving egress cost.
+ */
+export declare const MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT = 100;
+export interface AttachLifecycleOptions {
+    eventManager: EventManager;
+    /**
+     * The active connector's `onLifecycleEvent` (already bound). `undefined` when the
+     * connector can't observe lifecycle at all; the value it returns is `undefined`
+     * when THIS session can't be observed (e.g. no live `.on`). Either way the
+     * bridge emits `lifecycleTelemetryUnavailable` and becomes a no-op.
+     */
+    subscribe: ((l: (e: WalletLifecycleEvent) => void) => (() => void) | undefined) | undefined;
+    /** Resolved per-event so a mid-session account/chain change is reflected. */
+    getRouting: () => LifecycleRouting;
+    connectionMode: ConnectionMode;
+    namespace?: Namespace | undefined;
+    walletId?: string | undefined;
+    /** Direct page vs production iframe — stamped on `lifecycleTelemetryUnavailable`. */
+    runtime?: 'direct' | 'iframe';
+    /**
+     * Window (ms) within which a wallet `chainChanged` is treated as the echo of a
+     * UWC-initiated `switchNetwork` and suppressed. Default 3000.
+     */
+    echoWindowMs?: number;
+    /**
+     * Seed for echo suppression when (re)attaching right AFTER a UWC-initiated
+     * switch completed (the cross-namespace reattach path): the fresh closure
+     * never saw that switch's `awaitingWallet`/`networkSwitched`, so the new
+     * provider's echo would otherwise surface as wallet-initiated. Same one-shot
+     * consume semantics as a bus-armed switch.
+     */
+    initialSwitch?: {
+        chainId: NetworkId;
+        at: number;
+    } | undefined;
+    now?: () => number;
+}
+/**
+ * Bridge a connector's PII-safe `WalletLifecycleEvent` stream onto the event bus
+ * as `walletAccountChanged` / `walletChainChanged` / `walletDisconnected` /
+ * `walletSessionExpired`.
+ *
+ * Two correctness concerns are handled here:
+ *  - **Echo suppression.** When UWC drives a `switchNetwork`, the wallet emits its
+ *    own `chainChanged` for the same chain — that's already captured by UWC's
+ *    `networkSwitched` / the switch handoff, so re-emitting it as a wallet-
+ *    initiated `walletChainChanged` would double-count. We watch the bus for
+ *    `networkSwitched` and drop a matching `chainChanged` inside `echoWindowMs`.
+ *  - **Availability is signal.** If the connector can't observe lifecycle, we emit
+ *    `lifecycleTelemetryUnavailable` ONCE so a dashboard can tell "silent" from
+ *    "unwired".
+ *
+ * @returns a teardown that removes the connector subscription AND the bus watcher.
+ */
+export declare function attachLifecycle(opts: AttachLifecycleOptions): () => void;
+//# sourceMappingURL=lifecycle-bridge.d.ts.map

package/dist/observability/lifecycle-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-bridge.d.ts","sourceRoot":"","sources":["../../src/observability/lifecycle-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,SAAS,EAEV,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;CAClC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,MAAM,CAAA;AAEtD,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;;OAKG;IACH,SAAS,EACL,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,oBAAoB,KAAK,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC,GACpE,SAAS,CAAA;IACb,6EAA6E;IAC7E,UAAU,EAAE,MAAM,gBAAgB,CAAA;IAClC,cAAc,EAAE,cAAc,CAAA;IAC9B,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,qFAAqF;IACrF,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,SAAS,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IAC9D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,IAAI,CA2IxE"}