@arcblock/did-connect-core 4.1.51 → 4.1.53

package/dist/ui/login-page.js

@@ -53,15 +53,42 @@ export class LoginPage {
     tokenSession = null;
     styleEl = null;
     mounted = false;
+    completed = false;
+    generation = 0;
+    activeMethod;
+    activeProvider;
+    oauthCleanup;
+    emailTimer;
+    emailDraft = '';
+    abort;
+    emit(name) {
+        try {
+            this.options.onEvent?.({ name, method: this.activeMethod, mode: this.options.mode ?? 'page' });
+        }
+        catch { /* analytics must not interrupt authentication */ }
+    }
+    select(method) {
+        this.generation++;
+        this.oauthCleanup?.();
+        this.abort?.abort();
+        this.abort = new AbortController();
+        this.activeMethod = method;
+        this.activeProvider = undefined;
+        this.emit('method_selected');
+    }
     currentView = 'methods';
     cardEl = null;
     mediaQuery = null;
     mediaListener = null;
     localeOutsideClick = null;
+    /** Open shadow root when isolate is set. Reused across destroy/mount. */
+    shadow = null;
+    isolate;
     constructor(container, config, http, options) {
         this.container = container;
         this.config = config;
         this.http = http;
+        this.isolate = options?.isolate === true;
         this.options = {
             methods: ['passkey', 'did-connect'],
             locale: 'en',
@@ -83,11 +110,14 @@ export class LoginPage {
         if (this.mounted)
             return;
         this.mounted = true;
+        this.completed = false;
+        this.emit('view');
         // 1. Inject styles
         this.styleEl = document.createElement('style');
         this.styleEl.textContent = LOGIN_PAGE_STYLES;
-        this.container.appendChild(this.styleEl);
-        // 2. Apply theme
+        this.mountRoot().appendChild(this.styleEl);
+        // 2. Follow ?theme= / web-mode, then the caller's fallback.
+        this.adoptStoredTheme();
         this.applyTheme();
         // 3. Feature-detect available methods
         const available = this.filterMethods(this.options.methods);
@@ -96,24 +126,40 @@ export class LoginPage {
     }
     /** Destroy the login UI, clean up timers and listeners. Idempotent. */
     destroy() {
+        this.generation++;
+        this.oauthCleanup?.();
+        this.abort?.abort();
+        clearInterval(this.emailTimer);
         this.detachLocaleMenu();
         if (this.tokenSession) {
             this.tokenSession.destroy();
             this.tokenSession = null;
         }
-        if (this.mediaQuery && this.mediaListener) {
-            this.mediaQuery.removeEventListener('change', this.mediaListener);
-            this.mediaQuery = null;
-            this.mediaListener = null;
+        this.detachMedia();
+        if (this.isolate) {
+            // innerHTML on the host does not clear its shadow root.
+            const shadow = this.shadow ?? this.container.shadowRoot;
+            if (shadow)
+                shadow.innerHTML = '';
+            this.container.removeAttribute('data-theme');
+        }
+        else {
+            document.documentElement.removeAttribute('data-theme');
+            this.container.innerHTML = '';
         }
-        // Clean up theme attribute
-        document.documentElement.removeAttribute('data-theme');
-        this.container.innerHTML = '';
         this.styleEl = null;
         this.cardEl = null;
         this.currentView = 'methods';
         this.mounted = false;
     }
+    /**
+     * Apply a light or dark theme without remounting.
+     * The host writes `web-mode` itself. Isolate updates the shadow host only.
+     */
+    setTheme(theme) {
+        this.options.theme = theme;
+        this.applyTheme();
+    }
     /** Update options and re-render. */
     update(newOptions) {
         Object.assign(this.options, newOptions);
@@ -123,27 +169,84 @@ export class LoginPage {
         }
     }
     // ─── Private: theme ────────────────────────────────────────────────
+    /** Light DOM themes <html>. Isolate themes the shadow host only. */
+    themeTarget() {
+        return this.isolate ? this.container : document.documentElement;
+    }
+    /** Shadow root created once. attachShadow throws if called again. */
+    mountRoot() {
+        if (!this.isolate)
+            return this.container;
+        if (this.shadow)
+            return this.shadow;
+        this.shadow = this.container.shadowRoot ?? this.container.attachShadow({ mode: 'open' });
+        return this.shadow;
+    }
+    detachMedia() {
+        if (this.mediaQuery && this.mediaListener) {
+            this.mediaQuery.removeEventListener('change', this.mediaListener);
+        }
+        this.mediaQuery = null;
+        this.mediaListener = null;
+    }
+    /**
+     * Same order as theme/init.js: `?theme=` is a preview and wins;
+     * otherwise `localStorage["web-mode"]`. Neither write happens here.
+     */
+    adoptStoredTheme() {
+        if (this.options.mode === 'dialog')
+            return;
+        if (typeof window === 'undefined')
+            return;
+        const urlTheme = new URLSearchParams(window.location.search).get('theme');
+        if (urlTheme === 'light' || urlTheme === 'dark' || urlTheme === 'auto') {
+            this.options.theme = urlTheme;
+            return;
+        }
+        try {
+            const stored = localStorage.getItem('web-mode');
+            if (stored === 'light' || stored === 'dark' || stored === 'auto')
+                this.options.theme = stored;
+        }
+        catch { /* private mode */ }
+    }
+    /** light sets data-theme. dark removes it. auto follows the OS. */
     applyTheme() {
+        this.detachMedia();
         const theme = this.options.theme ?? 'dark';
+        const target = this.themeTarget();
         if (theme === 'light') {
-            document.documentElement.dataset.theme = 'light';
+            target.dataset.theme = 'light';
         }
         else if (theme === 'auto' && typeof window.matchMedia === 'function') {
             const mq = window.matchMedia('(prefers-color-scheme: light)');
             this.mediaQuery = mq;
             const apply = (light) => {
-                if (light) {
-                    document.documentElement.dataset.theme = 'light';
-                }
-                else {
-                    document.documentElement.removeAttribute('data-theme');
-                }
+                if (light)
+                    target.dataset.theme = 'light';
+                else
+                    target.removeAttribute('data-theme');
+                this.repaintQRPlate();
             };
             apply(mq.matches);
             this.mediaListener = (e) => apply(e.matches);
             mq.addEventListener('change', this.mediaListener);
+            return;
         }
-        // 'dark' is the default — no data-theme attribute needed
+        else {
+            target.removeAttribute('data-theme');
+        }
+        this.repaintQRPlate();
+    }
+    /** Redraw a visible QR so its plate matches the theme. Leaves a timeout overlay alone. */
+    repaintQRPlate() {
+        const qr = this.mountRoot().querySelector('#did-connect-qr');
+        if (!(qr instanceof HTMLElement))
+            return;
+        const url = qr.dataset.qrUrl;
+        if (!url || !qr.querySelector('canvas') || qr.querySelector('.qr-timeout-overlay'))
+            return;
+        renderQR(qr, url);
     }
     // ─── Private: rendering ──────────────────────────────────────────────
     filterMethods(methods) {
@@ -158,11 +261,18 @@ export class LoginPage {
     }
     renderCard(methods) {
         const card = document.createElement('div');
-        card.className = 'card';
+        card.className = this.options.mode === 'dialog' ? 'card card-modal' : 'card';
         this.cardEl = card;
-        this.container.appendChild(card);
+        this.mountRoot().appendChild(card);
         this.switchView('methods', methods);
     }
+    /** Locale sits on the card's top-right row, level with Back / Cancel. */
+    renderCardTools(card) {
+        const tools = document.createElement('div');
+        tools.className = 'card-tools';
+        this.renderLocaleSwitcher(tools);
+        card.appendChild(tools);
+    }
     renderLocaleSwitcher(card) {
         const passed = this.options.locales;
         if (passed) {
@@ -201,7 +311,7 @@ export class LoginPage {
         trigger.className = 'locale-trigger';
         trigger.setAttribute('aria-haspopup', 'menu');
         trigger.setAttribute('aria-expanded', 'false');
-        trigger.innerHTML = `${ICON_GLOBE} ${escapeHtml(current.label)}`;
+        trigger.innerHTML = `${ICON_GLOBE} <span class="locale-label">${escapeHtml(current.label)}</span>`;
         trigger.title = current.label;
         const menu = document.createElement('div');
         menu.className = 'locale-menu';
@@ -242,8 +352,16 @@ export class LoginPage {
             menu.appendChild(btn);
         }
         const onOutsideClick = (event) => {
-            if (!wrapper.contains(event.target))
-                setOpen(false);
+            const path = event.composedPath();
+            if (path.includes(wrapper))
+                return;
+            // Shadow clicks are retargeted to the host, so contains(event.target)
+            // is always false and the menu would close on every click. A click
+            // whose path includes the host is still inside the component. Light
+            // DOM has isolate false, so a click on the card still closes the menu.
+            if (this.isolate && path.includes(this.container))
+                return;
+            setOpen(false);
         };
         document.addEventListener('click', onOutsideClick);
         this.localeOutsideClick = onOutsideClick;
@@ -268,10 +386,14 @@ export class LoginPage {
                 this.tokenSession = null;
             }
         }
+        this.generation++;
+        this.oauthCleanup?.();
+        this.abort?.abort();
+        clearInterval(this.emailTimer);
         this.currentView = view;
         this.cardEl.innerHTML = '';
         this.cardEl.dataset.view = view;
-        this.renderLocaleSwitcher(this.cardEl);
+        this.renderCardTools(this.cardEl);
         switch (view) {
             case 'methods':
                 this.renderMethodsView(this.cardEl, locale, methods ?? this.filterMethods(this.options.methods));
@@ -287,9 +409,25 @@ export class LoginPage {
     renderMethodsView(card, locale, methods) {
         // ── Escape hatch ("Cancel") — top-left, mirrors the locale switcher
         //    (top-right). Standard placement for a standalone auth card. ──
-        this.renderHomeLink(card, locale);
+        if (this.options.mode !== 'dialog')
+            this.renderHomeLink(card, locale);
         // ── Brand header ──
         this.renderBrandHeader(card, locale);
+        if (this.options.preferenceKey) {
+            try {
+                const last = localStorage.getItem(`did-login-method:${this.options.preferenceKey}`);
+                const labels = { passkey: 'Passkey', oauth: 'OAuth', email: t('emailButton', locale), 'did-connect': 'DID Wallet' };
+                const provider = last?.startsWith('oauth:') ? this.options.oauthProviders?.find(p => p.enabled && `oauth:${p.id}` === last) : undefined;
+                const label = provider?.name ?? (last ? labels[last] : undefined);
+                if (last && label && (methods.includes(last) || (provider && methods.includes('oauth')))) {
+                    const hint = document.createElement('p');
+                    hint.className = 'subtitle';
+                    hint.textContent = t('lastUsed', locale, { method: label });
+                    card.appendChild(hint);
+                }
+            }
+            catch { /* private mode */ }
+        }
         // Passkey unsupported warning
         const requestedPasskey = this.options.methods.includes('passkey');
         if (requestedPasskey && !methods.includes('passkey')) {
@@ -298,6 +436,12 @@ export class LoginPage {
             warn.textContent = t('passkeyUnsupported', locale);
             card.appendChild(warn);
         }
+        const socialFirst = this.options.preferredLayout !== 'passkey-first' && methods.includes('oauth') && this.options.oauthProviders?.some(p => p.enabled && ['google', 'apple'].includes(p.id));
+        card.classList.toggle('social-first', !!socialFirst);
+        if (socialFirst) {
+            this.renderSecondaryGrid(card, locale, ['oauth'], 'primary');
+            this.renderDivider(card, locale);
+        }
         // ── Primary group: passkey ──
         const hasPrimary = methods.includes('passkey');
         if (hasPrimary) {
@@ -309,7 +453,21 @@ export class LoginPage {
             this.renderDivider(card, locale);
         }
         if (secondary.length > 0) {
-            this.renderSecondaryGrid(card, locale, methods);
+            if (socialFirst) {
+                if (methods.includes('email'))
+                    this.renderSecondaryGrid(card, locale, ['email']);
+                const details = document.createElement('details');
+                details.className = 'other-methods';
+                const summary = document.createElement('summary');
+                summary.textContent = t('otherMethods', locale);
+                details.appendChild(summary);
+                this.renderSecondaryGrid(details, locale, methods.filter(m => m !== 'email'), 'secondary');
+                if (details.querySelector('button'))
+                    card.appendChild(details);
+            }
+            else {
+                this.renderSecondaryGrid(card, locale, methods);
+            }
         }
         // If no methods available at all, show a message
         if (methods.length === 0 && !requestedPasskey) {
@@ -345,11 +503,15 @@ export class LoginPage {
         walletBtn.id = 'did-wallet-open-btn';
         walletBtn.textContent = t('openInWallet', locale);
         walletBtn.disabled = true; // enabled once URL is ready
-        card.appendChild(walletBtn);
+        if (isMobile())
+            card.insertBefore(walletBtn, qrContainer);
+        else
+            card.appendChild(walletBtn);
         // Status
         const statusEl = document.createElement('div');
         statusEl.id = 'did-connect-status';
         statusEl.className = 'status';
+        statusEl.setAttribute('role', 'status');
         card.appendChild(statusEl);
         // Trust footer
         this.renderTrustFooter(card, locale);
@@ -365,10 +527,25 @@ export class LoginPage {
         title.className = 'view-title';
         title.textContent = t('emailTitle', locale);
         card.appendChild(title);
+        const emailLabel = document.createElement('label');
+        emailLabel.className = 'input-label';
+        emailLabel.htmlFor = 'login-email-address';
+        emailLabel.textContent = t('emailPlaceholder', locale);
+        card.appendChild(emailLabel);
+        const emailHelp = document.createElement('p');
+        emailHelp.className = 'email-help';
+        emailHelp.textContent = t('emailExplanation', locale);
+        card.appendChild(emailHelp);
         // Email input
         const emailInput = document.createElement('input');
         emailInput.className = 'input';
+        emailInput.id = 'login-email-address';
         emailInput.type = 'email';
+        emailInput.required = true;
+        emailInput.autocomplete = 'email';
+        emailInput.value = this.emailDraft;
+        emailInput.setAttribute('aria-label', t('emailPlaceholder', locale));
+        emailInput.addEventListener('input', () => { this.emailDraft = emailInput.value; });
         emailInput.placeholder = t('emailPlaceholder', locale);
         card.appendChild(emailInput);
         // Submit button
@@ -379,16 +556,24 @@ export class LoginPage {
         // Status
         const status = document.createElement('div');
         status.className = 'status';
+        status.setAttribute('role', 'status');
         card.appendChild(status);
         // ── Code verification section (hidden initially) ──
         const codeSection = document.createElement('div');
         codeSection.className = 'email-code-section';
         codeSection.style.display = 'none';
+        const codeLabel = document.createElement('label');
+        codeLabel.className = 'input-label';
+        codeLabel.htmlFor = 'login-email-code';
+        codeLabel.textContent = t('emailCodePlaceholder', locale);
+        codeSection.appendChild(codeLabel);
         const codeInput = document.createElement('input');
+        codeInput.id = 'login-email-code';
         codeInput.className = 'input';
         codeInput.type = 'text';
         codeInput.inputMode = 'numeric';
         codeInput.maxLength = 8;
+        codeInput.setAttribute('aria-label', t('emailCodePlaceholder', locale));
         codeInput.autocomplete = 'one-time-code';
         codeInput.placeholder = t('emailCodePlaceholder', locale);
         codeSection.appendChild(codeInput);
@@ -404,6 +589,27 @@ export class LoginPage {
         card.insertBefore(codeSection, status);
         // Trust footer
         this.renderTrustFooter(card, locale);
+        const epoch = this.generation;
+        const isCurrent = () => this.mounted && epoch === this.generation;
+        const editBtn = document.createElement('button');
+        editBtn.className = 'passkey-alt';
+        editBtn.textContent = t('emailEdit', locale);
+        codeSection.appendChild(editBtn);
+        editBtn.addEventListener('click', () => this.switchView('email'));
+        const cooldown = () => {
+            let remaining = 60;
+            clearInterval(this.emailTimer);
+            resendBtn.disabled = true;
+            resendBtn.textContent = t('emailCooldown', locale, { seconds: String(remaining) });
+            this.emailTimer = setInterval(() => {
+                remaining--;
+                resendBtn.textContent = remaining > 0 ? t('emailCooldown', locale, { seconds: String(remaining) }) : t('emailResend', locale);
+                if (remaining <= 0) {
+                    clearInterval(this.emailTimer);
+                    resendBtn.disabled = false;
+                }
+            }, 1000);
+        };
         let currentEmail = '';
         let currentCodeId;
         const servicePrefix = this.config.servicePrefix ?? '/.well-known/service';
@@ -412,7 +618,7 @@ export class LoginPage {
             if (sendBtn.disabled)
                 return;
             const email = emailInput.value.trim();
-            if (!email?.includes('@')) {
+            if (!emailInput.checkValidity()) {
                 status.textContent = t('emailInvalid', locale);
                 status.className = 'status error';
                 return;
@@ -420,12 +626,18 @@ export class LoginPage {
             sendBtn.disabled = true;
             status.textContent = t('emailSending', locale);
             status.className = 'status';
+            status.setAttribute('role', 'status');
             try {
                 const sendResult = await this.http.post(`${servicePrefix}/api/email/sendCode`, { email, locale });
+                if (!isCurrent())
+                    return;
+                cooldown();
                 currentEmail = email;
                 currentCodeId = sendResult?.id;
                 // Switch to code input phase
                 emailInput.style.display = 'none';
+                emailLabel.hidden = true;
+                emailHelp.hidden = true;
                 sendBtn.style.display = 'none';
                 codeSection.style.display = '';
                 title.textContent = t('emailVerify', locale);
@@ -434,6 +646,8 @@ export class LoginPage {
                 codeInput.focus();
             }
             catch (err) {
+                if (!isCurrent())
+                    return;
                 const msg = err instanceof Error ? err.message : 'Failed to send email';
                 status.textContent = msg;
                 status.className = 'status error';
@@ -444,7 +658,7 @@ export class LoginPage {
             if (verifyBtn.disabled)
                 return;
             const code = codeInput.value.trim();
-            if (!code || code.length !== 8) {
+            if (!/^\d{8}$/.test(code)) {
                 status.textContent = t('emailCodeInvalid', locale);
                 status.className = 'status error';
                 return;
@@ -454,11 +668,15 @@ export class LoginPage {
             status.className = 'status';
             try {
                 await this.http.post(`${servicePrefix}/api/email/login`, { code, id: currentCodeId });
+                if (!isCurrent())
+                    return;
                 status.textContent = t('success', locale);
                 status.className = 'status';
                 this.handleSuccess();
             }
             catch (err) {
+                if (!isCurrent())
+                    return;
                 if (err instanceof Error && 'code' in err && err.code === 'FORBIDDEN') {
                     this.showFullError(friendlyError(err, locale));
                 }
@@ -479,21 +697,28 @@ export class LoginPage {
         codeInput.addEventListener('keydown', (e) => { if (e.key === 'Enter')
             verifyCode(); });
         resendBtn.addEventListener('click', async () => {
+            if (resendBtn.disabled)
+                return;
             resendBtn.disabled = true;
             status.textContent = t('emailSending', locale);
             status.className = 'status';
             try {
                 const resendResult = await this.http.post(`${servicePrefix}/api/email/sendCode`, { email: currentEmail, locale });
+                if (!isCurrent())
+                    return;
+                cooldown();
                 currentCodeId = resendResult?.id;
                 status.textContent = t('emailSent', locale, { email: currentEmail });
                 status.className = 'status';
             }
             catch (err) {
+                if (!isCurrent())
+                    return;
+                resendBtn.disabled = false;
                 const msg = err instanceof Error ? err.message : 'Failed to resend';
                 status.textContent = msg;
                 status.className = 'status error';
             }
-            resendBtn.disabled = false;
         });
     }
     renderBackButton(parent, locale) {
@@ -515,6 +740,8 @@ export class LoginPage {
      * sub-view back buttons that mean "return to the method list".
      */
     renderHomeLink(parent, locale) {
+        if (this.options.dismissible === false)
+            return;
         const { homeUrl, onCancel } = this.options;
         if (!onCancel && !homeUrl)
             return;
@@ -524,7 +751,7 @@ export class LoginPage {
             btn.type = 'button';
             btn.className = 'home-link';
             btn.innerHTML = label;
-            btn.addEventListener('click', () => this.options.onCancel?.());
+            btn.addEventListener('click', () => { this.emit('cancel'); this.options.onCancel?.(); });
             parent.appendChild(btn);
         }
         else {
@@ -556,7 +783,16 @@ export class LoginPage {
         else {
             h1.textContent = t('signIn', locale);
         }
+        if (this.options.purpose)
+            h1.textContent = this.options.purpose.title;
+        h1.id = 'login-title';
         header.appendChild(h1);
+        if (this.options.purpose?.description) {
+            const description = document.createElement('p');
+            description.className = 'subtitle';
+            description.textContent = this.options.purpose.description;
+            header.appendChild(description);
+        }
         // Subtitle: only the federation hint ("Authentication provided by X") carries
         // real information. The generic "Sign in to continue" just echoes the title,
         // so it's omitted — the title + auth buttons speak for themselves.
@@ -602,6 +838,12 @@ export class LoginPage {
             }
             footer.appendChild(links);
         }
+        if (this.currentView !== 'methods' && this.options.mode !== 'dialog') {
+            this.renderHomeLink(footer, locale);
+            const cancel = footer.querySelector('.home-link');
+            if (cancel)
+                cancel.style.cssText = 'position:static;display:inline-flex;margin-top:12px';
+        }
         parent.appendChild(footer);
     }
     renderDivider(parent, locale) {
@@ -665,15 +907,25 @@ export class LoginPage {
             retryBtn.addEventListener('click', () => doSignIn());
             const createLink = document.createElement('button');
             createLink.type = 'button';
-            createLink.className = 'passkey-alt';
+            createLink.className = 'passkey-alt passkey-create-entry';
             createLink.textContent = t('passkeyCreateInstead', locale);
             section.appendChild(createLink);
             createLink.addEventListener('click', () => renderCreateState());
         };
         // ── State 1: explicit create (new user declared intent) ──
         const renderCreateState = () => {
+            this.cardEl?.classList.add('passkey-creating');
+            this.abort?.abort();
+            this.generation++;
             section.innerHTML = '';
             clearStatus();
+            const heading = this.cardEl?.querySelector('h1');
+            if (heading)
+                heading.textContent = t('passkeyCreateAccount', locale);
+            const explanation = document.createElement('p');
+            explanation.className = 'subtitle';
+            explanation.textContent = t('passkeyExplanation', locale);
+            section.appendChild(explanation);
             const nameRow = document.createElement('div');
             nameRow.className = 'name-row visible';
             nameRow.id = 'passkey-name-row';
@@ -681,6 +933,7 @@ export class LoginPage {
             nameInput.className = 'input';
             nameInput.id = 'passkey-name-input';
             nameInput.type = 'text';
+            nameInput.setAttribute('aria-label', t('namePlaceholder', locale));
             nameInput.placeholder = t('namePlaceholder', locale);
             nameInput.autocomplete = 'name';
             nameRow.appendChild(nameInput);
@@ -699,8 +952,11 @@ export class LoginPage {
                 if (createBtn.disabled)
                     return; // Enter-key auto-repeat on the name input
                 createBtn.disabled = true;
+                this.select('passkey');
+                const epoch = this.generation;
                 const result = await runPasskeyAuth({
                     registerOnly: true,
+                    signal: this.abort?.signal,
                     name: nameInput.value.trim(),
                     onStatus: setStatus,
                     texts: statusTexts,
@@ -708,6 +964,8 @@ export class LoginPage {
                     prefix: this.options.passkeyPrefix,
                     invitationId: this.options.invitationId,
                 });
+                if (!this.mounted || epoch !== this.generation || this.abort?.signal.aborted)
+                    return;
                 if (handleResult(result))
                     return;
                 // Cancelled or other error — stay in create state, let the user retry.
@@ -719,21 +977,28 @@ export class LoginPage {
             nameInput.addEventListener('keydown', (e) => { if (e.key === 'Enter')
                 doCreate(); });
             backLink.addEventListener('click', () => renderSignInState());
-            nameInput.focus();
+            createBtn.focus();
         };
         // ── State 0: sign-in (default) ──
         const doSignIn = async () => {
             const btn = section.querySelector('#passkey-btn');
+            if (btn?.disabled)
+                return;
             if (btn)
                 btn.disabled = true;
+            this.select('passkey');
+            const epoch = this.generation;
             const result = await runPasskeyAuth({
                 authOnly: true,
+                signal: this.abort?.signal,
                 onStatus: setStatus,
                 texts: statusTexts,
                 locale,
                 prefix: this.options.passkeyPrefix,
                 invitationId: this.options.invitationId,
             });
+            if (!this.mounted || epoch !== this.generation || this.abort?.signal.aborted)
+                return;
             if (handleResult(result))
                 return;
             if (result.error && result.error !== 'no_passkey') {
@@ -745,20 +1010,27 @@ export class LoginPage {
             }
             // no_passkey (or user cancelled) — fork to cross-device / create choice
             // instead of silently creating a second credential.
+            this.emit('incomplete');
             renderCrossDeviceState();
         };
         const renderSignInState = () => {
+            this.cardEl?.classList.remove('passkey-creating');
+            this.abort?.abort();
+            this.generation++;
+            const heading = this.cardEl?.querySelector('h1');
+            if (heading)
+                heading.textContent = this.options.purpose?.title ?? (this.options.appName ? t('signInTo', locale, { appName: this.options.appName }) : t('signIn', locale));
             section.innerHTML = '';
             clearStatus();
             const signInBtn = document.createElement('button');
-            signInBtn.className = 'btn';
+            signInBtn.className = this.cardEl?.classList.contains('social-first') ? 'btn btn-secondary' : 'btn';
             signInBtn.id = 'passkey-btn';
             signInBtn.innerHTML = `${ICON_PASSKEY} ${escapeHtml(t('passkeySignIn', locale))}`;
             section.appendChild(signInBtn);
             signInBtn.addEventListener('click', () => doSignIn());
             const createLink = document.createElement('button');
             createLink.type = 'button';
-            createLink.className = 'passkey-alt';
+            createLink.className = 'passkey-alt passkey-create-entry';
             createLink.textContent = t('passkeyFirstTime', locale);
             section.appendChild(createLink);
             createLink.addEventListener('click', () => renderCreateState());
@@ -775,6 +1047,8 @@ export class LoginPage {
     //  methods now render through renderSecondaryGrid)
     // ─── Private: OAuth popup flow ──────────────────────────────────────
     startOAuthPopup(providerId, btn) {
+        this.oauthCleanup?.();
+        const epoch = this.generation;
         const servicePrefix = this.config.servicePrefix ?? '/.well-known/service';
         // Federation: popup opens Master's OAuth login URL (cross-domain callback)
         const oauthBase = this.options.masterOAuthOrigin
@@ -789,15 +1063,30 @@ export class LoginPage {
         const top = window.screenY + (window.innerHeight - height) / 2;
         const popup = window.open(loginUrl, 'oauth-login:popup', `left=${left},top=${top},width=${width},height=${height},resizable,scrollbars=yes,status=1,popup`);
         if (!popup) {
+            this.options.onBeforeRedirect?.();
             window.location.href = loginUrl;
             return;
         }
         // Save original button content and enter loading state
         const originalHTML = btn.innerHTML;
-        btn.innerHTML = `<span class="oauth-spinner"></span> Authorizing...`;
+        btn.textContent = t('oauthWaiting', this.options.locale, { provider: this.options.oauthProviders?.find(p => p.id === providerId)?.name ?? providerId });
         btn.disabled = true;
         btn.classList.add('oauth-btn-loading');
+        const recovery = document.createElement('div');
+        recovery.className = 'oauth-recovery';
+        recovery.setAttribute('role', 'status');
+        const hint = document.createElement('p');
+        hint.textContent = t('oauthIncomplete', this.options.locale);
+        const fullPage = document.createElement('a');
+        fullPage.href = loginUrl;
+        fullPage.textContent = t('oauthFullPage', this.options.locale);
+        fullPage.addEventListener('click', () => { this.options.onBeforeRedirect?.(); this.oauthCleanup?.(); });
+        recovery.append(hint, fullPage);
+        recovery.hidden = true;
+        btn.parentElement?.after(recovery);
         const restore = () => {
+            recovery.hidden = false;
+            this.emit('incomplete');
             btn.innerHTML = originalHTML;
             btn.disabled = false;
             btn.classList.remove('oauth-btn-loading');
@@ -805,19 +1094,19 @@ export class LoginPage {
         let settled = false;
         let sessionPollTimer;
         const succeed = () => {
-            if (settled)
+            if (settled || !this.mounted || epoch !== this.generation)
                 return;
             settled = true;
             cleanup();
-            btn.innerHTML = `<span class="oauth-check">✓</span> Success`;
+            btn.textContent = t('success', this.options.locale);
             this.handleSuccess();
         };
         const onMessage = async (event) => {
-            if (event.origin !== oauthOrigin)
+            if (event.origin !== oauthOrigin || event.source !== popup)
                 return;
             if (!event.data || event.data.type !== 'authorization_response')
                 return;
-            if (settled)
+            if (settled || !this.mounted || epoch !== this.generation)
                 return;
             // Stop the closed-poll only. Do NOT drop this listener from popup.closed —
             // GitHub/Twitter COOP reports closed while the provider page is still up,
@@ -843,7 +1132,7 @@ export class LoginPage {
                 cleanup();
                 return;
             }
-            btn.innerHTML = `<span class="oauth-spinner"></span> Signing in...`;
+            btn.textContent = t('verifying', this.options.locale);
             btn.disabled = true;
             try {
                 const oauthBody = { provider: providerId, code, state };
@@ -853,6 +1142,8 @@ export class LoginPage {
                 succeed();
             }
             catch (oauthErr) {
+                if (settled || !this.mounted || epoch !== this.generation)
+                    return;
                 const errMsg = oauthErr instanceof Error ? oauthErr.message : '';
                 const errCode = oauthErr instanceof Error && 'code' in oauthErr ? oauthErr.code : '';
                 if (errCode === 'FORBIDDEN' || errMsg === 'registration_closed' || errCode === 'registration_closed') {
@@ -904,6 +1195,10 @@ export class LoginPage {
             restore();
         }, 5 * 60 * 1000);
         const cleanup = () => {
+            settled = true;
+            btn.innerHTML = originalHTML;
+            btn.disabled = false;
+            btn.classList.remove('oauth-btn-loading');
             if (pollTimer !== undefined) {
                 clearInterval(pollTimer);
                 pollTimer = undefined;
@@ -915,6 +1210,10 @@ export class LoginPage {
             clearTimeout(abandonTimer);
             window.removeEventListener('message', onMessage);
         };
+        this.oauthCleanup = () => { cleanup(); recovery.remove(); try {
+            popup.close();
+        }
+        catch { /* COOP */ } };
         window.addEventListener('message', onMessage);
     }
     // (removed dead code: renderEmailButton — email now renders through renderSecondaryGrid)
@@ -924,20 +1223,27 @@ export class LoginPage {
      * Even count: all items in 2 columns (each half width).
      * Odd count: DID Wallet spans full width at the end.
      */
-    renderSecondaryGrid(parent, locale, methods) {
+    renderSecondaryGrid(parent, locale, methods, group) {
         const grid = document.createElement('div');
         grid.className = 'methods-grid';
         // 1. OAuth buttons (each provider is one grid item)
         if (methods.includes('oauth') && this.options.oauthProviders?.length) {
-            const enabledProviders = (this.options.oauthProviders ?? []).filter((p) => p.enabled);
+            const order = this.options.oauthProviderOrder ?? ['google', 'apple', 'github'];
+            const rank = (id) => order.includes(id) ? order.indexOf(id) : order.length;
+            const explicitOrder = !!this.options.oauthProviderOrder || this.options.oauthProviders?.some(p => p.order !== undefined && p.order !== 999);
+            const enabledProviders = (this.options.oauthProviders ?? []).filter((p) => p.enabled && (!group || ((explicitOrder || ['google', 'apple'].includes(p.id)) === (group === 'primary')))).sort((a, b) => this.options.oauthProviderOrder
+                ? rank(a.id) - rank(b.id)
+                : (a.order ?? 999) - (b.order ?? 999) || rank(a.id) - rank(b.id));
             for (const provider of enabledProviders) {
                 const btn = document.createElement('button');
                 btn.className = 'method-btn';
                 btn.dataset.provider = provider.id;
                 const icon = getOAuthIcon(provider.id);
-                btn.innerHTML = `${icon} ${escapeHtml(provider.name)}`;
+                btn.innerHTML = `${icon} ${escapeHtml(t('continueWith', locale, { provider: provider.name }))}`;
                 grid.appendChild(btn);
                 btn.addEventListener('click', () => {
+                    this.select('oauth');
+                    this.activeProvider = provider.id;
                     this.startOAuthPopup(provider.id, btn);
                 });
             }
@@ -950,6 +1256,7 @@ export class LoginPage {
             btn.innerHTML = `${ICON_EMAIL} ${escapeHtml(t('emailButton', locale))}`;
             grid.appendChild(btn);
             btn.addEventListener('click', () => {
+                this.select('email');
                 this.switchView('email');
             });
         }
@@ -963,6 +1270,7 @@ export class LoginPage {
             btn.innerHTML = `${ICON_DID_WALLET} ${escapeHtml(walletLabel)}`;
             grid.appendChild(btn);
             btn.addEventListener('click', () => {
+                this.select('did-connect');
                 this.switchView('qr');
             });
         }
@@ -971,11 +1279,15 @@ export class LoginPage {
     // ─── Private: DID Connect flow (QR view) ───────────────────────────
     async startDIDConnectInView(statusEl, qrContainer, walletBtn, locale) {
         statusEl.textContent = t('connecting', locale);
+        const epoch = this.generation;
+        const isCurrent = () => this.mounted && epoch === this.generation;
         try {
             // Clean up previous session if any
             this.tokenSession?.destroy();
             this.tokenSession = new TokenSession(this.config, this.http);
             this.tokenSession.on('succeed', async () => {
+                if (!isCurrent())
+                    return;
                 // Transition to result state: hide QR + wallet button, show verifying
                 this.showConnectResult(qrContainer, walletBtn, statusEl, t('verifying', locale));
                 try {
@@ -983,11 +1295,15 @@ export class LoginPage {
                     await this.http.post(`${servicePrefix}/api/did/connect/complete`, {
                         token: this.tokenSession.state.token,
                     });
+                    if (!isCurrent())
+                        return;
                     // Show success state with green checkmark
                     this.showConnectSuccess(qrContainer, walletBtn, statusEl, locale);
                     this.handleSuccess();
                 }
                 catch (err) {
+                    if (!isCurrent())
+                        return;
                     this.showConnectResult(qrContainer, walletBtn, statusEl, friendlyError(err, locale), true);
                 }
             });
@@ -1020,13 +1336,15 @@ export class LoginPage {
                 }
             });
             const state = await this.tokenSession.create({ locale });
+            if (!isCurrent())
+                return;
             if (state.url) {
                 renderQR(qrContainer, state.url);
                 // Enable "Open in DID Wallet" button with platform-specific handler
                 walletBtn.disabled = false;
                 walletBtn.addEventListener('click', () => {
                     // Immediately show connecting state when user taps to open wallet
-                    this.showConnectScanned(qrContainer, walletBtn, statusEl, locale);
+                    statusEl.textContent = t('walletRetry', locale);
                     this.openInWallet(state.url, locale);
                 });
             }
@@ -1034,6 +1352,8 @@ export class LoginPage {
             this.tokenSession.startPolling();
         }
         catch (err) {
+            if (!isCurrent())
+                return;
             statusEl.textContent = friendlyError(err, locale);
             clearQR(qrContainer);
         }
@@ -1054,7 +1374,7 @@ export class LoginPage {
         }
         this.cardEl.innerHTML = '';
         this.cardEl.dataset.view = 'error';
-        this.renderLocaleSwitcher(this.cardEl);
+        this.renderCardTools(this.cardEl);
         const resultContainer = document.createElement('div');
         resultContainer.className = 'connect-result';
         resultContainer.innerHTML = `<div class="result-icon result-error">✕</div>`;
@@ -1209,8 +1529,25 @@ export class LoginPage {
     }
     // ─── Private: success handler ────────────────────────────────────────
     handleSuccess() {
+        if (!this.mounted || this.completed)
+            return;
+        this.completed = true;
+        this.emit('success');
+        if (this.options.preferenceKey && this.activeMethod) {
+            try {
+                localStorage.setItem(`did-login-method:${this.options.preferenceKey}`, this.activeMethod === 'oauth' && this.activeProvider ? `oauth:${this.activeProvider}` : this.activeMethod);
+            }
+            catch { /* private mode */ }
+        }
         if (this.options.onSuccess) {
-            this.options.onSuccess();
+            const epoch = this.generation;
+            Promise.resolve().then(() => { if (this.mounted && epoch === this.generation)
+                return this.options.onSuccess?.(); }).catch(() => {
+                if (!this.mounted || epoch !== this.generation)
+                    return;
+                this.completed = false;
+                this.showFullError(t('authFailed', this.options.locale));
+            });
         }
         else {
             setTimeout(() => location.reload(), 300);