@enbox/browser 0.3.71 → 0.3.72

package/dist/types/ui/connect-modal.d.ts

@@ -96,8 +96,9 @@ export interface ConnectModalOptions {
     /** Preferred method on open; overrides the remembered choice. */
     preferredMethod?: ConnectMethod;
     /**
-     * Remember the successful method + wallet in localStorage and pre-shape
-     * the next session accordingly.
+     * Remember the successful method + wallet in localStorage. Refreshes reuse
+     * the route saved for their delegate DID; new connections use the latest
+     * successful route as a convenience.
      * @default true
      */
     rememberChoice?: boolean;
@@ -105,6 +106,13 @@ export interface ConnectModalOptions {
     appName?: string;
     /** Icon URL of the requesting application. */
     appIcon?: string;
+    /**
+     * Stable application identifier hint available to the wallet during approval.
+     * Defaults to the browser's canonical origin.
+     */
+    applicationId?: string;
+    /** Wallet profile DID that a refresh must renew. */
+    expectedProviderDid?: string;
     /**
      * Relay base URL override for the phone path. When omitted, each wallet's
      * `connectServerUrl` is discovered from its `/.well-known/enbox-connect`
@@ -134,15 +142,7 @@ export interface ConnectModalDeps {
     /** Runs one relay handshake (phone path). */
     runRelay: typeof runRelayConnect;
     /** Runs one popup handshake (browser path); must open the popup synchronously. */
-    runPopup: (options: {
-        walletUrl: string;
-        permissionRequests: ConnectPermissionRequest[];
-        appName: string;
-        appIcon?: string;
-        timeoutMs?: number;
-        delegatePortableDid?: PortableDid;
-        requestType?: ConnectRequestType;
-    }) => Promise<ConnectResult | undefined>;
+    runPopup: typeof runPopupConnect;
     /** Resolves a wallet origin to its relay `connectServerUrl` (or undefined). */
     discoverConnectServerUrl: (walletOrigin: string) => Promise<string | undefined>;
     /** Validates a pasted custom wallet URL. */
@@ -158,6 +158,18 @@ export interface ConnectModalDeps {
  * same machinery the wallet selector uses for custom-URL validation).
  */
 export declare function discoverWalletConnectServerUrl(walletOrigin: string): Promise<string | undefined>;
+/** Runs one popup handshake without collapsing early-close into a denial. */
+declare function runPopupConnect(options: {
+    walletUrl: string;
+    permissionRequests: ConnectPermissionRequest[];
+    appName: string;
+    appIcon?: string;
+    applicationId?: string;
+    timeoutMs?: number;
+    delegatePortableDid?: PortableDid;
+    requestType?: ConnectRequestType;
+    expectedProviderDid?: string;
+}): Promise<ConnectResult | undefined>;
 /**
  * Opens the connect modal and resolves when the session ends.
  *
@@ -167,4 +179,5 @@ export declare function discoverWalletConnectServerUrl(walletOrigin: string): Pr
  *         user dismisses the error.
  */
 export declare function runConnectModal(options: ConnectModalOptions): Promise<ConnectResult | undefined>;
+export {};
 //# sourceMappingURL=connect-modal.d.ts.map

package/dist/types/ui/connect-modal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect-modal.d.ts","sourceRoot":"","sources":["../../../src/ui/connect-modal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connect-modal.d.ts","sourceRoot":"","sources":["../../../src/ui/connect-modal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,aAAa,EAAoB,MAAM,gBAAgB,CAAC;AAYpH,OAAO,EAA8B,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAEzF,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAkChD,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,qBAAqB;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAEvC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,oEAAoE;IACpE,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAE5B,mEAAmE;IACnE,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAeD,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IAEzB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uDAAuD;IACvD,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAE1B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAElC,iEAAiE;IACjE,eAAe,CAAC,EAAE,aAAa,CAAC;IAEhC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,oDAAoD;IACpD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAE1B,2DAA2D;IAC3D,kBAAkB,EAAE,wBAAwB,EAAE,CAAC;IAE/C,yCAAyC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAClC;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,eAAe,CAAC;IAEjC,kFAAkF;IAClF,QAAQ,EAAE,OAAO,eAAe,CAAC;IAEjC,+EAA+E;IAC/E,wBAAwB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEhF,4CAA4C;IAC5C,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAExD,gFAAgF;IAChF,QAAQ,EAAE,MAAM,OAAO,CAAC;IAExB,6CAA6C;IAC7C,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC,GAAG,SAAS,CAAC;CAC1E;AAED;;;;GAIG;AACH,wBAAsB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEtG;AAED,6EAA6E;AAC7E,iBAAe,eAAe,CAAC,OAAO,EAAE;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,wBAAwB,EAAE,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAClC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAmBrC;AAmKD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAo5BhG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/browser",
-  "version": "0.3.71",
+  "version": "0.3.72",
   "description": "Enbox tools and features to use in the browser",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -66,15 +66,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@enbox/agent": "0.8.40",
-    "@enbox/api": "0.6.79",
-    "@enbox/auth": "0.6.86",
+    "@enbox/agent": "0.8.41",
+    "@enbox/api": "0.6.80",
+    "@enbox/auth": "0.6.87",
     "@enbox/common": "0.1.6",
-    "@enbox/connect": "0.1.20",
+    "@enbox/connect": "0.1.21",
     "@enbox/crypto": "0.1.9",
     "@enbox/dids": "0.1.10",
-    "@enbox/dwn-sdk-js": "0.4.24",
-    "@enbox/protocols": "0.2.106"
+    "@enbox/dwn-sdk-js": "0.4.25",
+    "@enbox/protocols": "0.2.107"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.6",

package/src/browser-connect-handler.ts

@@ -107,6 +107,12 @@ export interface BrowserConnectHandlerOptions {
    */
   appIcon?: string;
 
+  /**
+   * Stable application identifier hint available to the wallet during approval.
+   * Defaults to the browser's canonical origin.
+   */
+  applicationId?: string;
+
   /**
    * Preferred connect method on open: `'phone'` (QR / deep link via the
    * relay) or `'browser'` (wallet popup on this device). Overrides the
@@ -116,8 +122,9 @@ export interface BrowserConnectHandlerOptions {
   preferredMethod?: ConnectMethod;
 
   /**
-   * Remember the successful method + wallet in localStorage and pre-shape
-   * the next connect session accordingly.
+   * Remember the successful method + wallet in localStorage. Refreshes reuse
+   * the route saved for their delegate DID; new connections use the latest
+   * successful route as a convenience.
    * @default true
    */
   rememberChoice?: boolean;
@@ -176,6 +183,7 @@ export function BrowserConnectHandler(
     timeout,
     appName,
     appIcon,
+    applicationId,
     preferredMethod,
     rememberChoice,
     connectServerUrl,
@@ -188,6 +196,7 @@ export function BrowserConnectHandler(
       permissionRequests: ConnectPermissionRequest[];
       delegatePortableDid?: PortableDid;
       requestType?: ConnectRequestType;
+      expectedProviderDid?: string;
     }): Promise<ConnectResult | undefined> {
       return runConnectModal({
         wallets,
@@ -196,12 +205,14 @@ export function BrowserConnectHandler(
         rememberChoice,
         appName,
         appIcon             : appIcon ?? `${window.location.origin}/favicon.ico`,
+        applicationId,
         connectServerUrl,
         relayWalletPath,
         timeout,
         theme,
         mode                : params.requestType,
         delegatePortableDid : params.delegatePortableDid,
+        expectedProviderDid : params.expectedProviderDid,
         permissionRequests  : params.permissionRequests,
       });
     },

package/src/relay-connect-runner.ts

@@ -66,6 +66,9 @@ export interface RelayConnectOptions {
   /** Optional icon URL for the app, shown in the wallet consent UI. */
   appIcon?: string;
 
+  /** Stable application identifier hint available to the wallet during approval. */
+  applicationId?: string;
+
   /** Optional client/environment metadata for wallet session display. */
   clientMetadata?: ConnectClientMetadata;
 
@@ -78,6 +81,9 @@ export interface RelayConnectOptions {
   /** User-facing request purpose. Absent means a normal connect. */
   requestType?: ConnectRequestType;
 
+  /** Wallet profile DID that a refresh must renew. */
+  expectedProviderDid?: string;
+
   /** Total milliseconds to poll the relay for a wallet response. */
   timeoutMs?: number;
 
@@ -193,10 +199,12 @@ export async function runRelayConnect(options: RelayConnectOptions): Promise<Con
     clientDid           : clientDid.uri,
     appName             : options.appName,
     appIcon             : options.appIcon,
+    applicationId       : options.applicationId,
     clientMetadata      : options.clientMetadata,
     permissionRequests  : options.permissionRequests,
     delegateDid         : options.delegatePortableDid?.uri,
     requestType         : options.requestType,
+    expectedProviderDid : options.expectedProviderDid,
     supportedDidMethods : ['did:dht', 'did:jwk'],
     nonce,
     state,
@@ -243,6 +251,7 @@ export async function runRelayConnect(options: RelayConnectOptions): Promise<Con
       nonce,
       state,
       pin,
+      expectedProviderDid : options.expectedProviderDid,
       delegatePortableDid : options.delegatePortableDid,
       confirmComplete     : transport.confirmComplete?.bind(transport),
     });
@@ -274,6 +283,7 @@ async function attemptPinOpen(params: {
   nonce: string;
   state: string;
   pin: string;
+  expectedProviderDid: string | undefined;
   delegatePortableDid: PortableDid | undefined;
   confirmComplete: (() => Promise<void>) | undefined;
 }): Promise<PinAttemptOutcome> {
@@ -281,8 +291,13 @@ async function attemptPinOpen(params: {
     const response = await openResponse({
       jwe                 : params.responseCiphertext,
       recipientPrivateKey : params.responsePrivateKey,
-      expected            : { clientDid: params.clientDid, nonce: params.nonce, state: params.state },
-      pin                 : params.pin,
+      expected            : {
+        clientDid   : params.clientDid,
+        nonce       : params.nonce,
+        state       : params.state,
+        providerDid : params.expectedProviderDid,
+      },
+      pin: params.pin,
     });
 
     const delegatePortableDid = resolveDelegatePortableDid({

package/src/ui/connect-modal.ts

@@ -59,6 +59,12 @@ export type ConnectMethod = 'phone' | 'browser';
 /** localStorage key remembering the last successful method + wallet. */
 const LAST_CHOICE_STORAGE_KEY = 'enbox:connect:lastChoice';
 
+/** localStorage key remembering the exact wallet route for each delegate/profile pair. */
+const SESSION_CHOICES_STORAGE_KEY = 'enbox:connect:sessionChoices';
+
+/** Bounds local reconnect provenance retained by one dapp origin. */
+const MAX_SESSION_CHOICES = 20;
+
 /**
  * Safety margin subtracted from the relay pointer TTL before re-minting.
  *
@@ -168,8 +174,9 @@ export interface ConnectModalOptions {
   preferredMethod?: ConnectMethod;
 
   /**
-   * Remember the successful method + wallet in localStorage and pre-shape
-   * the next session accordingly.
+   * Remember the successful method + wallet in localStorage. Refreshes reuse
+   * the route saved for their delegate DID; new connections use the latest
+   * successful route as a convenience.
    * @default true
    */
   rememberChoice?: boolean;
@@ -180,6 +187,15 @@ export interface ConnectModalOptions {
   /** Icon URL of the requesting application. */
   appIcon?: string;
 
+  /**
+   * Stable application identifier hint available to the wallet during approval.
+   * Defaults to the browser's canonical origin.
+   */
+  applicationId?: string;
+
+  /** Wallet profile DID that a refresh must renew. */
+  expectedProviderDid?: string;
+
   /**
    * Relay base URL override for the phone path. When omitted, each wallet's
    * `connectServerUrl` is discovered from its `/.well-known/enbox-connect`
@@ -216,15 +232,7 @@ export interface ConnectModalDeps {
   runRelay: typeof runRelayConnect;
 
   /** Runs one popup handshake (browser path); must open the popup synchronously. */
-  runPopup: (options: {
-    walletUrl: string;
-    permissionRequests: ConnectPermissionRequest[];
-    appName: string;
-    appIcon?: string;
-    timeoutMs?: number;
-    delegatePortableDid?: PortableDid;
-    requestType?: ConnectRequestType;
-  }) => Promise<ConnectResult | undefined>;
+  runPopup: typeof runPopupConnect;
 
   /** Resolves a wallet origin to its relay `connectServerUrl` (or undefined). */
   discoverConnectServerUrl: (walletOrigin: string) => Promise<string | undefined>;
@@ -254,9 +262,11 @@ async function runPopupConnect(options: {
   permissionRequests: ConnectPermissionRequest[];
   appName: string;
   appIcon?: string;
+  applicationId?: string;
   timeoutMs?: number;
   delegatePortableDid?: PortableDid;
   requestType?: ConnectRequestType;
+  expectedProviderDid?: string;
 }): Promise<ConnectResult | undefined> {
   // The transport constructor calls `window.open` synchronously — callers
   // must invoke this inside the user-gesture call stack.
@@ -269,10 +279,12 @@ async function runPopupConnect(options: {
   return await client.connect({
     appName             : options.appName,
     appIcon             : options.appIcon,
+    applicationId       : options.applicationId,
     clientMetadata      : collectBrowserClientMetadata(),
     permissionRequests  : options.permissionRequests,
     delegatePortableDid : options.delegatePortableDid,
     requestType         : options.requestType,
+    expectedProviderDid : options.expectedProviderDid,
   });
 }
 
@@ -301,6 +313,12 @@ interface LastChoice {
   walletUrl: string;
 }
 
+/** Stable reconnect provenance for one delegated app session. */
+interface SessionChoice extends LastChoice {
+  delegateDid: string;
+  providerDid: string;
+}
+
 function readLastChoice(storage: ConnectModalDeps['storage']): LastChoice | undefined {
   try {
     const raw = storage?.getItem(LAST_CHOICE_STORAGE_KEY);
@@ -321,6 +339,78 @@ function writeLastChoice(storage: ConnectModalDeps['storage'], choice: LastChoic
   } catch { /* best effort */ }
 }
 
+function isSessionChoice(value: unknown): value is SessionChoice {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const choice = value as Partial<SessionChoice>;
+  return (choice.method === 'phone' || choice.method === 'browser')
+    && isValidRememberedWalletUrl(choice.walletUrl)
+    && typeof choice.delegateDid === 'string'
+    && choice.delegateDid.length > 0
+    && typeof choice.providerDid === 'string'
+    && choice.providerDid.length > 0;
+}
+
+function readSessionChoices(storage: ConnectModalDeps['storage']): SessionChoice[] {
+  try {
+    const raw = storage?.getItem(SESSION_CHOICES_STORAGE_KEY);
+    if (raw === null || raw === undefined) {
+      return [];
+    }
+    const parsed = JSON.parse(raw) as unknown;
+    return Array.isArray(parsed) ? parsed.filter(isSessionChoice).slice(-MAX_SESSION_CHOICES) : [];
+  } catch {
+    return [];
+  }
+}
+
+function readSessionChoice(
+  storage: ConnectModalDeps['storage'],
+  delegateDid: string | undefined,
+  expectedProviderDid: string | undefined,
+): SessionChoice | undefined {
+  if (delegateDid === undefined) {
+    return undefined;
+  }
+  const choices = readSessionChoices(storage);
+  for (let index = choices.length - 1; index >= 0; index--) {
+    const choice = choices[index];
+    if (choice.delegateDid === delegateDid
+      && (expectedProviderDid === undefined || choice.providerDid === expectedProviderDid)) {
+      return choice;
+    }
+  }
+  return undefined;
+}
+
+function writeSessionChoice(storage: ConnectModalDeps['storage'], choice: SessionChoice): void {
+  try {
+    const choices = readSessionChoices(storage).filter(entry =>
+      entry.delegateDid !== choice.delegateDid || entry.providerDid !== choice.providerDid
+    );
+    choices.push(choice);
+    storage?.setItem(SESSION_CHOICES_STORAGE_KEY, JSON.stringify(choices.slice(-MAX_SESSION_CHOICES)));
+  } catch { /* best effort */ }
+}
+
+function removeSessionChoice(
+  storage: ConnectModalDeps['storage'],
+  delegateDid: string,
+  providerDid: string,
+): void {
+  try {
+    const choices = readSessionChoices(storage).filter(choice =>
+      choice.delegateDid !== delegateDid || choice.providerDid !== providerDid
+    );
+    if (choices.length === 0) {
+      storage?.removeItem(SESSION_CHOICES_STORAGE_KEY);
+    } else {
+      storage?.setItem(SESSION_CHOICES_STORAGE_KEY, JSON.stringify(choices));
+    }
+  } catch { /* best effort */ }
+}
+
 /** One cancellable relay session. */
 interface RelaySession {
   cancelled: Promise<never>;
@@ -379,24 +469,37 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
   const wallets = dedupeWalletsByUrl(options.wallets ?? []);
   const rememberChoice = options.rememberChoice ?? true;
   const appName = options.appName ?? window.location.host;
-  const relayWalletPath = options.relayWalletPath ?? '/connect/app';
+  const applicationId = options.applicationId ?? window.location.origin;
   const isMobile = deps.isMobile();
   const refreshing = options.mode === 'refresh';
 
   const lastChoice = rememberChoice ? readLastChoice(deps.storage) : undefined;
+  let savedRoute = rememberChoice && refreshing
+    ? readSessionChoice(
+      deps.storage,
+      options.delegatePortableDid?.uri,
+      options.expectedProviderDid,
+    )
+    : undefined;
+  const expectedProviderDid = options.expectedProviderDid ?? savedRoute?.providerDid;
+  const relayWalletPath = options.relayWalletPath ?? '/connect/app';
+  const savedRouteEscapeLabel = options.walletUrl === undefined
+    ? 'Choose another wallet or method'
+    : 'Choose another method';
 
-  // Wallet resolution order: explicit option → remembered → catalog head.
+  // Refresh routes resolve by delegate first; general preferences remain a
+  // best-effort fallback for sessions created before route-aware storage.
   const rememberedWalletUrl = lastChoice !== undefined
     && (refreshing || walletInCatalog(wallets, lastChoice.walletUrl))
     ? lastChoice.walletUrl
     : undefined;
-  const lockedWallet = options.walletUrl !== undefined || (refreshing && rememberedWalletUrl !== undefined);
-  let walletUrl = options.walletUrl
+  let walletUrl = savedRoute?.walletUrl
+    ?? options.walletUrl
     ?? rememberedWalletUrl
     ?? wallets[0]?.url;
 
-  // Method resolution order: explicit option → remembered → phone.
-  let method: ConnectMethod = options.preferredMethod ?? lastChoice?.method ?? 'phone';
+  // An exact refresh route wins over generic handler and global preferences.
+  let method: ConnectMethod = savedRoute?.method ?? options.preferredMethod ?? lastChoice?.method ?? 'phone';
 
   return new Promise<ConnectResult | undefined>((resolve, reject) => {
     // ── Host + shadow root ─────────────────────────────────────
@@ -517,8 +620,14 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
     };
 
     const succeed = (result: ConnectResult): void => {
-      if (rememberChoice) {
-        writeLastChoice(deps.storage, { method, walletUrl: walletUrl ?? '' });
+      if (rememberChoice && walletUrl !== undefined) {
+        writeLastChoice(deps.storage, { method, walletUrl });
+        writeSessionChoice(deps.storage, {
+          delegateDid : result.delegatePortableDid.uri,
+          providerDid : result.connectedDid,
+          method,
+          walletUrl,
+        });
       }
       renderConnected();
       setTimeout(settleWith(settle, () => resolve(result)), 1_200);
@@ -703,15 +812,47 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
       );
     };
 
+    const escapeSavedRoute = (): void => {
+      if (savedRoute === undefined) {
+        return;
+      }
+
+      relaySession?.cancel();
+      relaySession = undefined;
+      clearRemint();
+      removeSessionChoice(deps.storage, savedRoute.delegateDid, savedRoute.providerDid);
+      savedRoute = undefined;
+      if (options.walletUrl !== undefined) {
+        walletUrl = options.walletUrl;
+      }
+      renderFooter();
+      setStage(
+        el('p', 'stage-caption', 'Choose another way to reconnect.'),
+        el('p', 'stage-subline', 'We’ll still require the same wallet profile used for this session.'),
+      );
+    };
+
     const renderError = (message: string, error?: Error): void => {
       setStage(
         el('p', 'stage-caption', message),
         stageButton('Start over', () => { void startMethod(); }),
+        ...(savedRoute !== undefined
+          ? [stageLinkButton(savedRouteEscapeLabel, escapeSavedRoute)]
+          : []),
         stageLinkButton('Close', settleWith(settle, () => reject(error ?? new Error(`[@enbox/browser] ${message}`)))),
       );
     };
 
     const renderPhoneUnavailable = (): void => {
+      if (savedRoute !== undefined) {
+        setStage(
+          el('p', 'stage-caption', 'Your saved wallet connection is unavailable right now.'),
+          el('p', 'stage-subline', 'Try again in a moment to reconnect the same session.'),
+          stageButton('Try again', () => { void startPhone(); }),
+          stageLinkButton(savedRouteEscapeLabel, escapeSavedRoute),
+        );
+        return;
+      }
       setStage(
         el('p', 'stage-caption', 'This wallet can’t connect by phone here.'),
         el('p', 'stage-subline', 'You can continue in this browser instead.'),
@@ -724,12 +865,24 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
     const popupSurface = isMobile ? 'tab' : 'window';
 
     const renderPopupPrompt = (): void => {
+      const walletName = walletUrl !== undefined ? walletByUrl(walletUrl).name : 'your wallet';
+      const exactReconnect = savedRoute !== undefined;
+      const connectDescription = isMobile
+        ? 'Your wallet opens in a new tab to approve this connection — no code needed.'
+        : 'Your wallet opens in a small window to approve this connection.';
+      const description = exactReconnect
+        ? `We’ll open the same ${walletName} profile used for this session.`
+        : connectDescription;
+      const connectButtonLabel = isMobile ? 'Open wallet' : 'Open wallet window';
+      const buttonLabel = exactReconnect
+        ? `Open ${walletName} ${popupSurface}`
+        : connectButtonLabel;
       setStage(
-        el('p', 'stage-caption', 'Connect with a wallet in this browser'),
-        el('p', 'stage-subline', isMobile
-          ? 'Your wallet opens in a new tab to approve this connection — no code needed.'
-          : 'Your wallet opens in a small window to approve this connection.'),
-        stageButton(isMobile ? 'Open wallet' : 'Open wallet window', () => { startPopup(); }),
+        el('p', 'stage-caption', exactReconnect
+          ? `Reconnect with ${walletName}`
+          : 'Connect with a wallet in this browser'),
+        el('p', 'stage-subline', description),
+        stageButton(buttonLabel, () => { startPopup(); }),
       );
     };
 
@@ -747,7 +900,9 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
           ? `Your browser blocked the wallet ${popupSurface}.`
           : `The wallet ${popupSurface} was closed.`),
         stageButton(blocked ? 'Open it now' : `Reopen ${popupSurface}`, () => { startPopup(); }),
-        stageLinkButton(isMobile ? 'Use a code instead' : 'Use your phone instead', () => { void switchMethod('phone'); }),
+        ...(savedRoute !== undefined
+          ? [stageLinkButton(savedRouteEscapeLabel, escapeSavedRoute)]
+          : [stageLinkButton(isMobile ? 'Use a code instead' : 'Use your phone instead', () => { void switchMethod('phone'); })]),
       );
     };
 
@@ -833,10 +988,12 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
           walletUri           : new URL(relayWalletPath, origin).toString(),
           appName,
           appIcon             : options.appIcon,
+          applicationId,
           clientMetadata      : collectBrowserClientMetadata(),
           permissionRequests  : options.permissionRequests,
           delegatePortableDid : options.delegatePortableDid,
           requestType         : options.mode,
+          expectedProviderDid,
           timeoutMs           : options.timeout,
           cancelled           : session.cancelled,
           onWalletUriReady    : (handoff): void => {
@@ -907,9 +1064,11 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
           permissionRequests  : options.permissionRequests,
           appName,
           appIcon             : options.appIcon,
+          applicationId,
           timeoutMs           : options.timeout,
           delegatePortableDid : options.delegatePortableDid,
           requestType         : options.mode,
+          expectedProviderDid,
         });
         if (settled) { return; }
         if (result === undefined) {
@@ -945,7 +1104,7 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
     const renderFooter = (): void => {
       footer.replaceChildren();
 
-      if (!lockedWallet) {
+      if (savedRoute === undefined && options.walletUrl === undefined) {
         composeWalletRow();
         const switcher = buildWalletSwitcher();
         if (switcher.label !== undefined) {
@@ -958,7 +1117,7 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
       const row = document.createElement('div');
       row.className = 'footer-row';
 
-      if (method === 'phone') {
+      if (method === 'phone' && savedRoute === undefined) {
         const alt = document.createElement('button');
         alt.className = 'footer-link method-link';
         // On a phone both methods open the wallet on this device — what the
@@ -967,7 +1126,7 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
         // startPopup runs synchronously in this click handler.
         alt.addEventListener('click', () => { startPopup(); });
         row.appendChild(alt);
-      } else {
+      } else if (method === 'browser' && savedRoute === undefined) {
         const alt = document.createElement('button');
         alt.className = 'footer-link method-link';
         alt.textContent = isMobile ? 'Use a code instead →' : 'Use your phone instead →';