@arcblock/did-connect-core 4.1.52 → 4.1.54

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;
+        }
+        else {
+            target.removeAttribute('data-theme');
         }
-        // 'dark' is the default — no data-theme attribute needed
+        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,20 @@ 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) {
+        if (!(this.options.showLocaleSelector ?? this.options.mode !== 'dialog'))
+            return;
+        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 +313,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';
@@ -215,6 +327,8 @@ export class LoginPage {
         trigger.addEventListener('click', (event) => {
             event.stopPropagation();
             setOpen(menu.hidden);
+            if (!menu.hidden)
+                menu.querySelector('[aria-checked="true"]')?.focus();
         });
         for (const item of locales) {
             const checked = item.code === current.code;
@@ -224,12 +338,13 @@ export class LoginPage {
             btn.setAttribute('role', 'menuitemradio');
             btn.setAttribute('aria-checked', checked ? 'true' : 'false');
             btn.dataset.locale = item.code;
+            btn.tabIndex = -1;
             btn.title = item.label;
-            if (checked) {
+            {
                 const mark = document.createElement('span');
                 mark.className = 'locale-check';
                 mark.setAttribute('aria-hidden', 'true');
-                mark.textContent = '✓';
+                mark.textContent = checked ? '✓' : '';
                 btn.appendChild(mark);
             }
             const label = document.createElement('span');
@@ -241,9 +356,36 @@ export class LoginPage {
             });
             menu.appendChild(btn);
         }
-        const onOutsideClick = (event) => {
-            if (!wrapper.contains(event.target))
+        wrapper.addEventListener('keydown', (event) => {
+            const items = [...menu.querySelectorAll('.locale-btn')];
+            const active = this.shadow?.activeElement ?? document.activeElement;
+            const index = items.indexOf(active);
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                event.stopPropagation();
                 setOpen(false);
+                trigger.focus();
+            }
+            else if (event.key === 'Tab')
+                setOpen(false);
+            else if (['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) {
+                event.preventDefault();
+                setOpen(true);
+                const next = event.key === 'Home' ? 0 : event.key === 'End' ? items.length - 1 : index < 0 ? (event.key === 'ArrowUp' ? items.length - 1 : 0) : (index + (event.key === 'ArrowUp' ? -1 : 1) + items.length) % items.length;
+                items[next]?.focus();
+            }
+        });
+        const onOutsideClick = (event) => {
+            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 +410,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));
@@ -284,10 +430,26 @@ export class LoginPage {
                 break;
         }
     }
+    /** Keep recognition next to the action, without a second page subtitle. */
+    markLastUsed(button, method, locale) {
+        if (!this.options.preferenceKey)
+            return;
+        try {
+            if (localStorage.getItem(`did-login-method:${this.options.preferenceKey}`) !== method)
+                return;
+            const hint = document.createElement('span');
+            hint.className = 'last-used';
+            hint.textContent = t('lastUsed', locale);
+            button.classList.add('has-last-used');
+            button.appendChild(hint);
+        }
+        catch { /* Storage may be unavailable in private mode. */ }
+    }
     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);
         // Passkey unsupported warning
@@ -298,6 +460,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 +477,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 +527,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 +551,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 +580,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 +613,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 +642,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 +650,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 +670,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 +682,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 +692,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,28 +721,36 @@ 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) {
+    renderBackButton(parent, locale, onBack = () => this.switchView('methods')) {
         const btn = document.createElement('button');
+        btn.type = 'button';
         btn.className = 'back-btn';
         btn.innerHTML = `${ICON_BACK_ARROW} ${escapeHtml(t('back', locale))}`;
-        btn.addEventListener('click', () => this.switchView('methods'));
+        btn.addEventListener('click', onBack);
         parent.appendChild(btn);
     }
     /**
@@ -515,6 +765,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 +776,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 +808,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 +863,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 +932,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 +958,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);
@@ -690,17 +968,17 @@ export class LoginPage {
             createBtn.id = 'passkey-btn';
             createBtn.innerHTML = `${ICON_PASSKEY} ${escapeHtml(t('passkeyCreate', locale))}`;
             section.appendChild(createBtn);
-            const backLink = document.createElement('button');
-            backLink.type = 'button';
-            backLink.className = 'passkey-alt';
-            backLink.textContent = t('passkeyBackToSignIn', locale);
-            section.appendChild(backLink);
+            parent.querySelector('.back-btn')?.remove();
+            this.renderBackButton(parent, locale, () => renderSignInState());
             const doCreate = async () => {
                 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 +986,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.
@@ -718,22 +998,28 @@ export class LoginPage {
             createBtn.addEventListener('click', doCreate);
             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 +1031,29 @@ 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');
+            parent.querySelector('.back-btn')?.remove();
+            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))}`;
+            this.markLastUsed(signInBtn, 'passkey', 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,147 +1070,237 @@ export class LoginPage {
     //  methods now render through renderSecondaryGrid)
     // ─── Private: OAuth popup flow ──────────────────────────────────────
     startOAuthPopup(providerId, btn) {
+        this.oauthCleanup?.();
+        const epoch = this.generation;
+        const locale = this.options.locale;
         const servicePrefix = this.config.servicePrefix ?? '/.well-known/service';
-        // Federation: popup opens Master's OAuth login URL (cross-domain callback)
         const oauthBase = this.options.masterOAuthOrigin
-            ? `${this.options.masterOAuthOrigin}${servicePrefix}`
-            : servicePrefix;
+            ? `${this.options.masterOAuthOrigin}${servicePrefix}` : servicePrefix;
         const oauthOrigin = new URL(oauthBase, window.location.href).origin;
-        const loginUrl = `${oauthBase}/api/oauth/${encodeURIComponent(providerId)}/login?returnUrl=${encodeURIComponent(window.location.href)}`;
-        // Open centered popup — compact size, enough for provider auth pages
-        const width = 500;
-        const height = 620;
-        const left = window.screenX + (window.innerWidth - width) / 2;
-        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) {
-            window.location.href = loginUrl;
-            return;
+        let returnUrl = window.location.href;
+        if (this.options.mode !== 'dialog' && window.location.pathname === `${servicePrefix}/login`) {
+            const requested = new URLSearchParams(window.location.search).get('return_to');
+            try {
+                const target = new URL(requested || '/', window.location.origin);
+                returnUrl = target.origin === window.location.origin && !/^\/[/\\]/.test(target.pathname) ? target.href : `${window.location.origin}/`;
+            }
+            catch {
+                returnUrl = `${window.location.origin}/`;
+            }
         }
-        // Save original button content and enter loading state
+        const loginUrl = `${oauthBase}/api/oauth/${encodeURIComponent(providerId)}/login?returnUrl=${encodeURIComponent(returnUrl)}`;
+        const provider = this.options.oauthProviders?.find(p => p.id === providerId)?.name ?? providerId;
         const originalHTML = btn.innerHTML;
-        btn.innerHTML = `<span class="oauth-spinner"></span> Authorizing...`;
-        btn.disabled = true;
-        btn.classList.add('oauth-btn-loading');
-        const restore = () => {
+        let popup = null;
+        let settled = false;
+        let exchanging = false;
+        let probing = false;
+        let pollTimer;
+        let sessionTimer;
+        let abandonTimer;
+        const current = () => !settled && this.mounted && epoch === this.generation;
+        const locked = [];
+        const lockMethods = () => {
+            for (const button of this.cardEl?.querySelectorAll('.method-btn, .passkey-create-entry, #passkey-btn, .locale-trigger, .locale-btn') ?? []) {
+                locked.push({ button, disabled: button.disabled });
+                button.disabled = true;
+            }
+        };
+        const recovery = document.createElement('div');
+        recovery.className = 'oauth-recovery';
+        recovery.setAttribute('role', 'status');
+        const hint = document.createElement('p');
+        const actions = document.createElement('div');
+        actions.className = 'oauth-recovery-actions';
+        const reopen = document.createElement('button');
+        reopen.type = 'button';
+        reopen.className = 'oauth-retry';
+        reopen.textContent = t('oauthReopen', locale);
+        reopen.hidden = true;
+        reopen.onclick = () => { this.select('oauth'); this.activeProvider = providerId; this.startOAuthPopup(providerId, btn); };
+        const fullPage = document.createElement('a');
+        fullPage.href = loginUrl;
+        fullPage.textContent = t('oauthFullPage', locale);
+        fullPage.addEventListener('click', event => {
+            const reconcile = recovery.dataset.state === 'oauthUnconfirmed';
+            if (exchanging && !settled) {
+                event.preventDefault();
+                return;
+            }
+            if (reconcile)
+                event.preventDefault();
+            this.options.onBeforeRedirect?.();
+            this.oauthCleanup?.();
+            if (reconcile)
+                window.location.reload();
+        });
+        const cancel = document.createElement('button');
+        cancel.type = 'button';
+        cancel.className = 'oauth-cancel';
+        cancel.textContent = t('cancel', locale);
+        actions.append(reopen, fullPage, cancel);
+        recovery.append(hint, actions);
+        btn.parentElement?.after(recovery);
+        const restoreButton = () => {
             btn.innerHTML = originalHTML;
             btn.disabled = false;
             btn.classList.remove('oauth-btn-loading');
         };
-        let settled = false;
-        let sessionPollTimer;
+        const closePopup = () => { try {
+            popup?.close();
+        }
+        catch { /* COOP can sever the window reference. */ } };
+        const cleanup = () => {
+            settled = true;
+            clearInterval(pollTimer);
+            clearInterval(sessionTimer);
+            clearTimeout(abandonTimer);
+            window.removeEventListener('message', onMessage);
+            for (const item of locked.splice(0))
+                item.button.disabled = item.disabled;
+            restoreButton();
+        };
+        const showRecovery = (key) => {
+            hint.textContent = t(key, locale, { provider });
+            recovery.dataset.state = key;
+            actions.hidden = false;
+            reopen.hidden = false;
+            cancel.hidden = true;
+            restoreButton();
+        };
+        const fail = (key) => {
+            if (!current())
+                return;
+            cleanup();
+            closePopup();
+            showRecovery(key);
+            this.emit('incomplete');
+        };
         const succeed = () => {
-            if (settled)
+            if (!current())
                 return;
-            settled = true;
             cleanup();
-            btn.innerHTML = `<span class="oauth-check">✓</span> Success`;
+            closePopup();
+            recovery.remove();
+            btn.textContent = t('success', locale);
+            btn.disabled = true;
             this.handleSuccess();
         };
+        cancel.onclick = () => { if (exchanging)
+            return; fail('oauthCancelled'); btn.focus(); };
         const onMessage = async (event) => {
-            if (event.origin !== oauthOrigin)
-                return;
-            if (!event.data || event.data.type !== 'authorization_response')
+            if (event.origin !== oauthOrigin || event.source !== popup || !popup)
                 return;
-            if (settled)
+            if (!event.data || event.data.type !== 'authorization_response' || !current() || exchanging)
                 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,
-            // and the callback also window.close()s itself after postMessage.
-            if (pollTimer !== undefined) {
-                clearInterval(pollTimer);
-                pollTimer = undefined;
-            }
-            try {
-                popup.close();
-            }
-            catch {
-                /* ignore */
-            }
+            clearInterval(pollTimer);
+            clearInterval(sessionTimer);
             if (event.data.error) {
-                restore();
-                cleanup();
+                fail(event.data.error === 'access_denied' ? 'oauthDenied' : event.data.error === 'cancelled' ? 'oauthCancelled' : 'oauthFailed');
                 return;
             }
             const { code, state } = event.data.response ?? event.data;
-            if (!code) {
-                restore();
-                cleanup();
+            if (typeof code !== 'string' || !code || typeof state !== 'string' || !state) {
+                fail('oauthFailed');
                 return;
             }
-            btn.innerHTML = `<span class="oauth-spinner"></span> Signing in...`;
+            exchanging = true;
+            lockMethods();
+            actions.hidden = true;
+            closePopup();
+            hint.textContent = t('verifying', locale);
+            btn.textContent = t('verifying', locale);
             btn.disabled = true;
             try {
                 const oauthBody = { provider: providerId, code, state };
                 if (this.options.invitationId)
                     oauthBody.invitationId = this.options.invitationId;
-                await this.http.post(`${servicePrefix}/api/oauth/login`, oauthBody);
+                await this.http.post(`${servicePrefix}/api/oauth/login`, oauthBody, { signal: this.abort?.signal });
                 succeed();
             }
-            catch (oauthErr) {
-                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') {
-                    settled = true;
+            catch (err) {
+                if (!current())
+                    return;
+                const code = err instanceof Error && 'code' in err ? String(err.code) : '';
+                const message = err instanceof Error ? err.message : '';
+                if (code === 'FORBIDDEN' || code === 'registration_closed' || message === 'registration_closed') {
                     cleanup();
-                    this.showFullError(friendlyError(oauthErr, this.options.locale));
-                }
-                else {
-                    restore();
+                    recovery.remove();
+                    this.showFullError(friendlyError(err, locale));
                 }
+                else
+                    fail('oauthFailed');
+            }
+        };
+        this.oauthCleanup = () => { cleanup(); recovery.remove(); closePopup(); };
+        window.addEventListener('message', onMessage);
+        try {
+            popup = window.open(loginUrl, 'oauth-login:popup', `left=${window.screenX + (window.innerWidth - 500) / 2},top=${window.screenY + (window.innerHeight - 620) / 2},width=500,height=620,resizable,scrollbars=yes,status=1,popup`);
+        }
+        catch { /* Treat a browser refusal like a blocked popup. */ }
+        if (!popup) {
+            fail('oauthBlocked');
+            return;
+        }
+        hint.textContent = t('oauthWaiting', locale, { provider });
+        btn.textContent = t('oauthWaiting', locale, { provider });
+        btn.disabled = true;
+        btn.classList.add('oauth-btn-loading');
+        // COOP can report closed before the callback arrives. Keep the listener,
+        // but show recovery immediately and never overlap server session probes.
+        const checkSession = async () => {
+            if (!current() || exchanging || probing)
+                return;
+            probing = true;
+            try {
+                const session = await this.http.get(`${servicePrefix}/api/did/session`);
+                if (current() && !exchanging && session?.authenticated === true)
+                    succeed();
+            }
+            catch { /* A later probe or callback may still complete this attempt. */ }
+            finally {
+                probing = false;
             }
         };
-        // popup.closed is not "user cancelled". Provider COOP and the callback's
-        // own window.close() both flip it. Dropping the message listener here is
-        // what made GitHub login fail: authorize succeeds, parent already gave up.
-        let pollTimer = setInterval(() => {
+        pollTimer = setInterval(() => {
             let closed = false;
             try {
-                closed = popup.closed;
+                closed = !!popup?.closed;
             }
             catch {
                 return;
             }
-            if (!closed)
+            if (!closed || !current())
                 return;
-            if (pollTimer !== undefined) {
-                clearInterval(pollTimer);
-                pollTimer = undefined;
-            }
-            restore();
-            const checkSession = () => {
-                void this.http
-                    .get(`${servicePrefix}/api/did/session`)
-                    .then((session) => {
-                    if (session?.authenticated)
-                        succeed();
-                })
-                    .catch(() => {
-                    /* keep waiting for postMessage or the next session probe */
-                });
-            };
-            checkSession();
-            sessionPollTimer = setInterval(checkSession, 500);
+            clearInterval(pollTimer);
+            showRecovery('oauthIncomplete');
+            // Remain explicitly cancellable while a COOP callback may still arrive.
+            cancel.hidden = false;
+            void checkSession();
+            sessionTimer = setInterval(() => { void checkSession(); }, 2000);
         }, 500);
-        const abandonTimer = setTimeout(() => {
-            if (settled)
+        abandonTimer = setTimeout(() => {
+            if (!current())
+                return;
+            if (!exchanging) {
+                fail('oauthTimedOut');
                 return;
+            }
+            // A request may have reached the server even if its response never arrived.
+            // Do not promise cancellation or start a second exchange in that ambiguity.
+            this.abort?.abort();
             cleanup();
-            restore();
+            closePopup();
+            lockMethods();
+            hint.textContent = t('oauthUnconfirmed', locale);
+            recovery.dataset.state = 'oauthUnconfirmed';
+            actions.hidden = false;
+            reopen.hidden = true;
+            cancel.hidden = true;
+            fullPage.href = window.location.href;
+            fullPage.textContent = t('oauthCheckSession', locale);
+            this.emit('incomplete');
         }, 5 * 60 * 1000);
-        const cleanup = () => {
-            if (pollTimer !== undefined) {
-                clearInterval(pollTimer);
-                pollTimer = undefined;
-            }
-            if (sessionPollTimer !== undefined) {
-                clearInterval(sessionPollTimer);
-                sessionPollTimer = undefined;
-            }
-            clearTimeout(abandonTimer);
-            window.removeEventListener('message', onMessage);
-        };
-        window.addEventListener('message', onMessage);
     }
     // (removed dead code: renderEmailButton — email now renders through renderSecondaryGrid)
     /**
@@ -924,20 +1309,28 @@ 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 }))}`;
+                this.markLastUsed(btn, `oauth:${provider.id}`, locale);
                 grid.appendChild(btn);
                 btn.addEventListener('click', () => {
+                    this.select('oauth');
+                    this.activeProvider = provider.id;
                     this.startOAuthPopup(provider.id, btn);
                 });
             }
@@ -948,8 +1341,10 @@ export class LoginPage {
             btn.className = 'method-btn';
             btn.id = 'email-btn';
             btn.innerHTML = `${ICON_EMAIL} ${escapeHtml(t('emailButton', locale))}`;
+            this.markLastUsed(btn, 'email', locale);
             grid.appendChild(btn);
             btn.addEventListener('click', () => {
+                this.select('email');
                 this.switchView('email');
             });
         }
@@ -961,8 +1356,10 @@ export class LoginPage {
             // Use short label when sharing grid with other methods
             const walletLabel = grid.children.length > 0 ? t('didWalletButtonShort', locale) : t('didWalletButton', locale);
             btn.innerHTML = `${ICON_DID_WALLET} ${escapeHtml(walletLabel)}`;
+            this.markLastUsed(btn, 'did-connect', locale);
             grid.appendChild(btn);
             btn.addEventListener('click', () => {
+                this.select('did-connect');
                 this.switchView('qr');
             });
         }
@@ -971,11 +1368,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 +1384,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 +1425,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 +1441,8 @@ export class LoginPage {
             this.tokenSession.startPolling();
         }
         catch (err) {
+            if (!isCurrent())
+                return;
             statusEl.textContent = friendlyError(err, locale);
             clearQR(qrContainer);
         }
@@ -1054,7 +1463,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 +1618,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);