@modernman00/shared-js-lib 1.2.90 → 1.6.2

package/VisualSupremacyRuntime.js

@@ -0,0 +1,312 @@
+/**
+ * vse-canvas.js
+ *
+ * Next-Gen Visual Supremacy Engine (VSE) Client Runtime
+ * 
+ * Features:
+ * - Dynamic P3 wide colour gamut and HDR capability detection
+ * - 2.5D tactile gyroscopic micro-parallax with spring damping
+ * - Dr. Viktor Kovács & Marcus security killswitch (suspends sensors on input focus)
+ * - Accessibility & reduced-motion invariant compliance
+ * - 120Hz ProMotion frame pacing via requestAnimationFrame
+ */
+
+'use strict';
+
+class VisualSupremacyRuntime {
+    constructor() {
+        this.isP3 = false;
+        this.isHDR = false;
+        this.reducedMotion = false;
+        this.isLowPowerMode = false;
+        this.isSensorActive = false;
+        this.isInputFocused = false;
+        this.orientation = { gamma: 0, beta: 0 };
+        this.targetOrientation = { gamma: 0, beta: 0 };
+        this.rafId = null;
+        this.activeCards = new Set();
+        this.intersectionObserver = null;
+    }
+
+    init() {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            return;
+        }
+
+        // 1. Telemetry: Wide Colour Gamut & Dynamic Range Detection
+        try {
+            this.isP3 = window.matchMedia && window.matchMedia('(color-gamut: p3)').matches;
+            this.isHDR = window.matchMedia && window.matchMedia('(dynamic-range: high)').matches;
+            this.reducedMotion = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+            const root = document.documentElement;
+            if (this.isP3) {
+                root.classList.add('vse-p3-capable');
+            }
+            if (this.isHDR) {
+                root.classList.add('vse-hdr-capable');
+            }
+
+            // Watch for live reduced motion preference changes
+            if (window.matchMedia) {
+                window.matchMedia('(prefers-reduced-motion: reduce)').addEventListener('change', (e) => {
+                    this.reducedMotion = e.matches;
+                    if (this.reducedMotion) {
+                        this.resetTransforms();
+                        this.stopSensors();
+                    } else if (!this.isLowPowerMode) {
+                        this.startSensors();
+                    }
+                });
+            }
+        } catch (_) {}
+
+        if (this.reducedMotion) {
+            return;
+        }
+
+        // 2. Segun & Victor PWA Battery-Saver & Low-Memory Killswitch
+        this.setupBatteryAndMemoryGuard();
+
+        // 3. Observe media cards using IntersectionObserver to only animate visible elements
+        this.setupCardObserver();
+
+        // 4. Mandatory Adversarial Security Gate (Dr. Viktor Kovács & Marcus): Input Focus Guard
+        this.setupSecurityGuard();
+
+        // 5. Desktop Pointer Parallax Fallback
+        this.setupDesktopPointerParallax();
+
+        // 6. Initialize Sensor Pipeline
+        this.startSensors();
+    }
+
+    setupBatteryAndMemoryGuard() {
+        try {
+            // Low-end Android / memory-constrained device guard (< 2GB RAM)
+            if (typeof navigator !== 'undefined' && navigator.deviceMemory && navigator.deviceMemory < 2) {
+                this.isLowPowerMode = true;
+                this.stopSensors();
+                this.resetTransforms();
+                return;
+            }
+
+            // Battery Status API guard: Disable 2.5D sensors if battery <= 20% and not charging
+            if (typeof navigator !== 'undefined' && typeof navigator.getBattery === 'function') {
+                navigator.getBattery().then((battery) => {
+                    const checkBattery = () => {
+                        const low = !battery.charging && battery.level <= 0.20;
+                        this.isLowPowerMode = low;
+                        if (low) {
+                            this.stopSensors();
+                            this.resetTransforms();
+                        } else if (!this.reducedMotion && !this.isInputFocused && !document.hidden) {
+                            this.startSensors();
+                        }
+                    };
+                    checkBattery();
+                    battery.addEventListener('levelchange', checkBattery);
+                    battery.addEventListener('chargingchange', checkBattery);
+                }).catch(() => {});
+            }
+        } catch (_) {}
+    }
+
+    setupCardObserver() {
+        if (!('IntersectionObserver' in window)) {
+            return;
+        }
+
+        this.intersectionObserver = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+                if (entry.isIntersecting) {
+                    this.activeCards.add(entry.target);
+                } else {
+                    this.activeCards.delete(entry.target);
+                    // Reset transform when scrolling out of viewport to save GPU compositing
+                    this.resetCardTransform(entry.target);
+                }
+            });
+        }, { threshold: 0.1 });
+
+        // Auto-observe post-media-stage containers
+        this.refreshObservedCards();
+
+        // Re-check for dynamically inserted posts (e.g. infinite scroll, new post submission)
+        const observer = new MutationObserver(() => this.refreshObservedCards());
+        observer.observe(document.body, { childList: true, subtree: true });
+    }
+
+    refreshObservedCards() {
+        if (!this.intersectionObserver) return;
+        const stages = document.querySelectorAll('.post-media-stage:not([data-vse-observed])');
+        stages.forEach((el) => {
+            el.setAttribute('data-vse-observed', 'true');
+            this.intersectionObserver.observe(el);
+        });
+    }
+
+    setupSecurityGuard() {
+        // Gyroscopic Timing Side-Channel Defense: Immediately detach listeners on active input
+        const pauseEvents = ['focusin', 'focus'];
+        const resumeEvents = ['focusout', 'blur'];
+
+        pauseEvents.forEach((ev) => {
+            document.addEventListener(ev, (e) => {
+                const tag = e.target && e.target.tagName ? e.target.tagName.toLowerCase() : '';
+                const isEditable = e.target && (e.target.isContentEditable || tag === 'input' || tag === 'textarea' || tag === 'select');
+                if (isEditable) {
+                    this.isInputFocused = true;
+                    this.stopSensors();
+                    this.resetTransforms();
+                }
+            }, true);
+        });
+
+        resumeEvents.forEach((ev) => {
+            document.addEventListener(ev, () => {
+                this.isInputFocused = false;
+                if (!document.hidden && !this.reducedMotion) {
+                    this.startSensors();
+                }
+            }, true);
+        });
+
+        // Tab Visibility Guard
+        document.addEventListener('visibilitychange', () => {
+            if (document.hidden) {
+                this.stopSensors();
+                this.resetTransforms();
+            } else if (!this.isInputFocused && !this.reducedMotion) {
+                this.startSensors();
+            }
+        });
+    }
+
+    startSensors() {
+        if (this.isSensorActive || this.reducedMotion || this.isInputFocused || this.isLowPowerMode) {
+            return;
+        }
+
+        if (typeof window.DeviceOrientationEvent !== 'undefined') {
+            this.orientationHandler = (e) => this.handleDeviceOrientation(e);
+            window.addEventListener('deviceorientation', this.orientationHandler, { passive: true });
+            this.isSensorActive = true;
+            this.scheduleRenderLoop();
+        }
+    }
+
+    stopSensors() {
+        if (!this.isSensorActive) {
+            return;
+        }
+
+        if (this.orientationHandler) {
+            window.removeEventListener('deviceorientation', this.orientationHandler);
+            this.orientationHandler = null;
+        }
+        if (this.rafId) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        this.isSensorActive = false;
+    }
+
+    handleDeviceOrientation(event) {
+        if (this.isInputFocused || this.reducedMotion || this.isLowPowerMode) return;
+
+        // Gamma: Left to Right (-90 to 90), Beta: Front to Back (-180 to 180)
+        let g = event.gamma || 0;
+        let b = event.beta || 0;
+
+        // Normalise resting hand angle: smartphones are typically held tilted forward by ~45 degrees
+        b = b - 45;
+
+        // Clamp to safe, subtle displacement (±15 degrees input, mapping to ±3.5 degrees visual rotation)
+        const clamp = (val, max) => Math.max(-max, Math.min(max, val));
+        this.targetOrientation.gamma = clamp(g, 15);
+        this.targetOrientation.beta = clamp(b, 15);
+    }
+
+    setupDesktopPointerParallax() {
+        // For non-touch/pointer devices, provide a subtle interactive hover depth response
+        if (window.matchMedia && window.matchMedia('(hover: hover)').matches) {
+            document.addEventListener('mousemove', (e) => {
+                if (this.isInputFocused || this.reducedMotion || this.activeCards.size === 0) return;
+
+                this.activeCards.forEach((card) => {
+                    const rect = card.getBoundingClientRect();
+                    if (e.clientX >= rect.left && e.clientX <= rect.right && e.clientY >= rect.top && e.clientY <= rect.bottom) {
+                        const relX = ((e.clientX - rect.left) / rect.width) * 2 - 1; // -1 to 1
+                        const relY = ((e.clientY - rect.top) / rect.height) * 2 - 1; // -1 to 1
+
+                        const rotX = -relY * 3.5;
+                        const rotY = relX * 3.5;
+                        const transX = relX * 4;
+                        const transY = relY * 4;
+
+                        const img = card.querySelector('.post-media-first-img');
+                        if (img) {
+                            img.style.transform = `perspective(800px) rotateX(${rotX.toFixed(2)}deg) rotateY(${rotY.toFixed(2)}deg) translate3d(${transX.toFixed(1)}px, ${transY.toFixed(1)}px, 6px) scale(1.02)`;
+                            img.style.transition = 'transform 0.12s cubic-bezier(0.2, 0, 0, 1)';
+                        }
+                    } else {
+                        this.resetCardTransform(card);
+                    }
+                });
+            }, { passive: true });
+        }
+    }
+
+    scheduleRenderLoop() {
+        if (this.rafId) return;
+
+        const render = () => {
+            // Spring damping / low-pass filter for silky 120fps motion without jitter
+            const ease = 0.08;
+            this.orientation.gamma += (this.targetOrientation.gamma - this.orientation.gamma) * ease;
+            this.orientation.beta += (this.targetOrientation.beta - this.orientation.beta) * ease;
+
+            const rotY = (this.orientation.gamma / 15) * 3.2; // Max 3.2deg
+            const rotX = (-this.orientation.beta / 15) * 3.2; // Max 3.2deg
+            const transX = (this.orientation.gamma / 15) * 4.5; // Max 4.5px
+            const transY = (this.orientation.beta / 15) * 4.5; // Max 4.5px
+
+            if (this.activeCards.size > 0 && (Math.abs(rotY) > 0.05 || Math.abs(rotX) > 0.05)) {
+                this.activeCards.forEach((card) => {
+                    const img = card.querySelector('.post-media-first-img');
+                    if (img) {
+                        img.style.transform = `perspective(800px) rotateX(${rotX.toFixed(2)}deg) rotateY(${rotY.toFixed(2)}deg) translate3d(${transX.toFixed(1)}px, ${transY.toFixed(1)}px, 5px) scale(1.015)`;
+                        img.style.transformOrigin = 'center center';
+                        img.style.willChange = 'transform';
+                    }
+                });
+            }
+
+            this.rafId = requestAnimationFrame(render);
+        };
+
+        this.rafId = requestAnimationFrame(render);
+    }
+
+    resetCardTransform(card) {
+        if (!card) return;
+        const img = card.querySelector('.post-media-first-img');
+        if (img) {
+            img.style.transform = '';
+            img.style.willChange = 'auto';
+            img.style.transition = 'transform 0.3s ease-out';
+        }
+    }
+
+    resetTransforms() {
+        this.activeCards.forEach((card) => this.resetCardTransform(card));
+        this.targetOrientation = { gamma: 0, beta: 0 };
+        this.orientation = { gamma: 0, beta: 0 };
+    }
+}
+
+export const vseRuntime = new VisualSupremacyRuntime();
+export function initVisualSupremacy() {
+    vseRuntime.init();
+}

package/WebAuthnClient.js

@@ -62,6 +62,13 @@ export class WebAuthnClient {
                 }
             };
 
+            if (Array.isArray(publicKey.excludeCredentials)) {
+                publicKey.excludeCredentials = publicKey.excludeCredentials.map(cred => ({
+                    ...cred,
+                    id: typeof cred.id === 'string' ? this.base64URLStringToBuffer(cred.id) : cred.id
+                }));
+            }
+
             const credential = await navigator.credentials.create({ publicKey });
             
             return {
@@ -76,7 +83,10 @@ export class WebAuthnClient {
         } catch (error) {
             // David's Rule: Defensive Degradation. If it fails or is canceled, log and swallow politely.
             console.warn("WebAuthn Registration failed or was canceled:", error);
-            throw new Error("Passkey registration was canceled or failed.");
+            const wrapped = new Error("Passkey registration was canceled or failed.");
+            wrapped.code = error && error.name ? error.name : 'UnknownError';
+            wrapped.originalError = error;
+            throw wrapped;
         }
     }
 
@@ -122,4 +132,339 @@ export class WebAuthnClient {
             throw new Error("Passkey login was canceled or failed. Please use your password.");
         }
     }
+
+    /**
+     * Checks if a user-verifying platform authenticator (Face ID, Touch ID, Fingerprint, Windows Hello) is available.
+     * Uses PublicKeyCredential.getClientCapabilities() with fallback to isUserVerifyingPlatformAuthenticatorAvailable().
+     * @returns {Promise<boolean>}
+     */
+    static async isPlatformAuthenticatorAvailable() {
+        if (!this.isSupported()) {
+            return false;
+        }
+        try {
+            if (typeof window.PublicKeyCredential.getClientCapabilities === 'function') {
+                const caps = await window.PublicKeyCredential.getClientCapabilities();
+                if (caps && typeof caps.userVerifyingPlatformAuthenticator === 'boolean') {
+                    return caps.userVerifyingPlatformAuthenticator;
+                }
+            }
+            if (typeof window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable === 'function') {
+                return await window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+            }
+        } catch (e) {
+            console.warn("WebAuthn capability check failed:", e);
+        }
+        return false;
+    }
+
+    /**
+     * Detects the platform-appropriate biometric label in British English.
+     * @param {string} [ua]
+     * @returns {string}
+     */
+    static detectBiometricLabel(ua = (typeof navigator !== 'undefined' ? navigator.userAgent : '')) {
+        const agent = String(ua || '');
+        if (/iPhone|iPad|iPod|Macintosh|Mac OS X/i.test(agent)) {
+            return 'Face ID or Touch ID';
+        }
+        if (/Android/i.test(agent)) {
+            return 'Fingerprint or Face Unlock';
+        }
+        if (/Windows/i.test(agent)) {
+            return 'Windows Hello';
+        }
+        return 'Biometric Passkey';
+    }
+
+    /**
+     * Determines if the post-login Biometric Passkey Activation UI should appear.
+     * @param {Object} state
+     * @returns {boolean}
+     */
+    static shouldShowActivationPrompt(state) {
+        if (!state || state.authenticated !== true || state.hasPasskey === true) {
+            return false;
+        }
+        const key = state.userKey || state.userId || 'default';
+        try {
+            if (localStorage.getItem('biometric_enrolled_' + key) === '1') {
+                return false;
+            }
+            const snoozeUntil = Number(localStorage.getItem('biometric_snooze_' + key) || '0');
+            if (snoozeUntil > Date.now()) {
+                return false;
+            }
+        } catch (_) {
+            // Ignore storage access errors in strict private modes
+        }
+        return true;
+    }
+
+    /**
+     * Snoozes the activation prompt for the specified number of hours (default 72h).
+     * @param {string} userKey
+     * @param {number} [hours=72]
+     */
+    static snoozeActivationPrompt(userKey, hours = 72) {
+        if (!userKey) return;
+        try {
+            const until = Date.now() + hours * 3600 * 1000;
+            localStorage.setItem('biometric_snooze_' + userKey, String(until));
+        } catch (_) {}
+    }
+
+    /**
+     * Marks the current device + user pair as enrolled in localStorage.
+     * @param {string} userKey
+     */
+    static markEnrolled(userKey) {
+        if (!userKey) return;
+        try {
+            localStorage.setItem('biometric_enrolled_' + userKey, '1');
+            localStorage.removeItem('biometric_snooze_' + userKey);
+        } catch (_) {}
+    }
+
+    /**
+     * Renders and mounts the native Biometric Passkey Activation UI modal / bottom-sheet.
+     * @param {Object} state
+     * @param {Object} [options]
+     * @returns {HTMLElement|null}
+     */
+    static renderPromptModal(state = {}, options = {}) {
+        if (typeof document === 'undefined' || !document.body) {
+            return null;
+        }
+        const existing = document.getElementById('universal-passkey-prompt-backdrop');
+        if (existing) {
+            return existing;
+        }
+
+        const appName = state.appName || 'this app';
+        const userKey = state.userKey || state.userId || 'default';
+        const userEmail = state.userEmail || state.userName || 'Verified Account';
+        const bioLabel = this.detectBiometricLabel();
+
+        const backdrop = document.createElement('div');
+        backdrop.id = 'universal-passkey-prompt-backdrop';
+        backdrop.setAttribute('role', 'dialog');
+        backdrop.setAttribute('aria-modal', 'true');
+        backdrop.setAttribute('aria-labelledby', 'universal-passkey-prompt-title');
+        backdrop.style.cssText = 'position:fixed;inset:0;z-index:99998;background:rgba(15,23,42,0.68);backdrop-filter:blur(8px);-webkit-backdrop-filter:blur(8px);display:flex;align-items:flex-end;justify-content:center;padding:0;opacity:0;transition:opacity 0.22s ease-out;font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;';
+
+        const styleTag = document.createElement('style');
+        styleTag.textContent = `
+            @media (min-width: 640px) {
+                #universal-passkey-prompt-backdrop { align-items: center !important; padding: 16px !important; }
+                #universal-passkey-prompt-card { border-radius: 24px !important; max-width: 420px !important; transform: translateY(8px); }
+            }
+            @keyframes passkeySpin { to { transform: rotate(360deg); } }
+        `;
+        backdrop.appendChild(styleTag);
+
+        const card = document.createElement('div');
+        card.id = 'universal-passkey-prompt-card';
+        card.style.cssText = 'width:100%;max-width:480px;background:linear-gradient(180deg,#0f172a 0%,#1e293b 100%);color:#f8fafc;border:1px solid rgba(148,163,184,0.22);border-radius:24px 24px 0 0;padding:24px 24px calc(24px + env(safe-area-inset-bottom,0px));box-shadow:0 25px 50px -12px rgba(0,0,0,0.65);transform:translateY(16px);transition:transform 0.25s cubic-bezier(0.16,1,0.3,1);box-sizing:border-box;';
+
+        card.innerHTML = `
+            <div style="width:40px;height:4px;background:rgba(148,163,184,0.35);border-radius:999px;margin:0 auto 16px;"></div>
+            <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:16px;">
+                <div style="display:inline-flex;align-items:center;gap:10px;background:rgba(16,185,129,0.14);border:1px solid rgba(16,185,129,0.35);padding:6px 12px;border-radius:999px;">
+                    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#34d399" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                        <path d="M12 10a2 2 0 0 0-2 2c0 1.02-.1 2.51-.26 4"/><path d="M14 13.12c0 2.38 0 6.38-1 8.88"/><path d="M17.29 21.02c.12-.6.43-2.3.5-3.02"/><path d="M2 12a10 10 0 0 1 18-6"/><path d="M2 16h.01"/><path d="M21.8 16c.2-2 .131-5.354 0-6"/><path d="M5 19.5C5.5 18 6 15 6 12a6 6 0 0 1 .34-2"/><path d="M8.65 22c.21-.66.45-1.32.57-2"/><path d="M9 6.8a6 6 0 0 1 9 5.2v2"/>
+                    </svg>
+                    <span style="font-size:12px;font-weight:700;letter-spacing:0.04em;text-transform:uppercase;color:#6ee7b7;white-space:nowrap;">Biometric Security</span>
+                </div>
+                <span id="universal-passkey-account-pill" style="font-size:12px;color:#94a3b8;max-width:180px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;"></span>
+            </div>
+            <h2 id="universal-passkey-prompt-title" style="margin:0 0 8px;font-size:22px;line-height:1.25;font-weight:800;letter-spacing:-0.02em;color:#ffffff;">Activate Biometric Sign-In</h2>
+            <p id="universal-passkey-prompt-desc" style="margin:0 0 16px;font-size:14px;line-height:1.55;color:#cbd5e1;"></p>
+            <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:8px;margin-bottom:18px;">
+                <div style="background:rgba(30,41,59,0.75);border:1px solid rgba(148,163,184,0.16);border-radius:12px;padding:10px 8px;text-align:center;">
+                    <div style="font-size:12px;font-weight:700;color:#f8fafc;">1-Tap Access</div>
+                    <div style="font-size:11px;color:#94a3b8;margin-top:2px;">Instant sign-in</div>
+                </div>
+                <div style="background:rgba(30,41,59,0.75);border:1px solid rgba(148,163,184,0.16);border-radius:12px;padding:10px 8px;text-align:center;">
+                    <div style="font-size:12px;font-weight:700;color:#f8fafc;">Device-Bound</div>
+                    <div style="font-size:11px;color:#94a3b8;margin-top:2px;">Private enclave</div>
+                </div>
+                <div style="background:rgba(30,41,59,0.75);border:1px solid rgba(148,163,184,0.16);border-radius:12px;padding:10px 8px;text-align:center;">
+                    <div style="font-size:12px;font-weight:700;color:#f8fafc;">Phishing-Proof</div>
+                    <div style="font-size:11px;color:#94a3b8;margin-top:2px;">FIDO2 standard</div>
+                </div>
+            </div>
+            <div id="universal-passkey-prompt-feedback" role="status" aria-live="polite" style="display:none;margin-bottom:14px;padding:10px 12px;border-radius:12px;font-size:13px;line-height:1.4;"></div>
+            <div style="display:flex;flex-direction:column;gap:10px;">
+                <button type="button" id="universal-passkey-activate-btn" style="min-height:48px;min-width:44px;width:100%;display:inline-flex;align-items:center;justify-content:center;gap:10px;padding:12px 20px;border-radius:14px;border:none;background:linear-gradient(135deg,#10b981 0%,#059669 100%);color:#ffffff;font-size:15px;font-weight:700;cursor:pointer;white-space:nowrap;flex-shrink:0;box-shadow:0 10px 20px -5px rgba(16,185,129,0.4);transition:transform 0.15s ease,filter 0.15s ease;">
+                    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                        <path d="M12 10a2 2 0 0 0-2 2c0 1.02-.1 2.51-.26 4"/><path d="M14 13.12c0 2.38 0 6.38-1 8.88"/><path d="M2 12a10 10 0 0 1 18-6"/><path d="M5 19.5C5.5 18 6 15 6 12a6 6 0 0 1 .34-2"/><path d="M9 6.8a6 6 0 0 1 9 5.2v2"/>
+                    </svg>
+                    <span id="universal-passkey-activate-label"></span>
+                </button>
+                <button type="button" id="universal-passkey-later-btn" style="min-height:44px;min-width:44px;width:100%;display:inline-flex;align-items:center;justify-content:center;padding:10px 16px;border-radius:12px;border:1px solid rgba(148,163,184,0.22);background:transparent;color:#cbd5e1;font-size:14px;font-weight:600;cursor:pointer;white-space:nowrap;flex-shrink:0;transition:background 0.15s ease,color 0.15s ease;">
+                    Maybe Later
+                </button>
+            </div>
+        `;
+
+        backdrop.appendChild(card);
+        document.body.appendChild(backdrop);
+
+        const accountPill = card.querySelector('#universal-passkey-account-pill');
+        if (accountPill) {
+            accountPill.textContent = userEmail;
+            accountPill.setAttribute('title', userEmail);
+        }
+        const descEl = card.querySelector('#universal-passkey-prompt-desc');
+        if (descEl) {
+            descEl.textContent = `Sign in to ${appName} instantly next time using your device's recognised biometric sensor (${bioLabel}). Your biometric data never leaves this device.`;
+        }
+        const activateLabelEl = card.querySelector('#universal-passkey-activate-label');
+        if (activateLabelEl) {
+            activateLabelEl.textContent = `Activate ${bioLabel}`;
+        }
+
+        requestAnimationFrame(() => {
+            backdrop.style.opacity = '1';
+            card.style.transform = 'translateY(0)';
+        });
+
+        const closePrompt = () => {
+            backdrop.style.opacity = '0';
+            card.style.transform = 'translateY(16px)';
+            setTimeout(() => {
+                if (backdrop.parentNode) {
+                    backdrop.parentNode.removeChild(backdrop);
+                }
+            }, 220);
+        };
+
+        const showFeedback = (msg, isSuccess = false) => {
+            const fb = card.querySelector('#universal-passkey-prompt-feedback');
+            if (!fb) return;
+            fb.style.display = 'block';
+            fb.style.background = isSuccess ? 'rgba(16,185,129,0.18)' : 'rgba(245,158,11,0.16)';
+            fb.style.border = isSuccess ? '1px solid rgba(16,185,129,0.4)' : '1px solid rgba(245,158,11,0.38)';
+            fb.style.color = isSuccess ? '#a7f3d0' : '#fde68a';
+            fb.textContent = msg;
+        };
+
+        const activateBtn = card.querySelector('#universal-passkey-activate-btn');
+        const laterBtn = card.querySelector('#universal-passkey-later-btn');
+
+        if (laterBtn) {
+            laterBtn.addEventListener('click', () => {
+                this.snoozeActivationPrompt(userKey, 72);
+                closePrompt();
+            });
+        }
+
+        if (activateBtn) {
+            const originalHTML = activateBtn.innerHTML;
+            activateBtn.addEventListener('click', async () => {
+                if (activateBtn.disabled) return;
+                activateBtn.disabled = true;
+                activateBtn.style.opacity = '0.85';
+                activateBtn.style.cursor = 'wait';
+                activateBtn.innerHTML = `
+                    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" style="animation:passkeySpin 0.8s linear infinite;" aria-hidden="true">
+                        <path d="M21 12a9 9 0 1 1-6.219-8.56"/>
+                    </svg>
+                    <span>Authorising Biometrics...</span>
+                `;
+
+                const csrfMeta = document.querySelector('meta[name="csrf-token"]');
+                const headers = {
+                    'Accept': 'application/json',
+                    'Content-Type': 'application/json',
+                    'X-Requested-With': 'XMLHttpRequest'
+                };
+                if (csrfMeta && csrfMeta.content) {
+                    headers['X-CSRF-TOKEN'] = csrfMeta.content;
+                }
+
+                try {
+                    const optRes = await fetch(options.optionsEndpoint || '/webauthn/register/options', {
+                        method: 'POST',
+                        headers,
+                        credentials: 'same-origin',
+                        body: JSON.stringify({ role: state.userRole || 'users' })
+                    });
+                    const optJson = await optRes.json();
+                    const creationOptions = optJson.token || optJson.data || optJson;
+                    if (!optRes.ok || !creationOptions || !creationOptions.challenge) {
+                        throw new Error(optJson.message || 'Unable to initialise biometric challenge.');
+                    }
+
+                    const credentialPayload = await this.registerDevice(creationOptions);
+                    credentialPayload.role = state.userRole || 'users';
+                    credentialPayload.deviceName = bioLabel;
+
+                    const verifyRes = await fetch(options.registerEndpoint || '/webauthn/register', {
+                        method: 'POST',
+                        headers,
+                        credentials: 'same-origin',
+                        body: JSON.stringify(credentialPayload)
+                    });
+                    const verifyJson = await verifyRes.json();
+                    if (!verifyRes.ok && verifyJson.status !== 'success') {
+                        throw new Error(verifyJson.message || 'Failed to verify biometric passkey.');
+                    }
+
+                    this.markEnrolled(userKey);
+                    showFeedback('Biometric Passkey activated! You can now sign in with 1 tap.', true);
+                    setTimeout(closePrompt, 1100);
+                } catch (err) {
+                    if (err && err.code === 'InvalidStateError') {
+                        // Self-healing: authenticator already holds a credential for this user/RP
+                        this.markEnrolled(userKey);
+                        showFeedback('Biometric Passkey is already active on this device.', true);
+                        setTimeout(closePrompt, 1100);
+                        return;
+                    }
+                    activateBtn.disabled = false;
+                    activateBtn.style.opacity = '1';
+                    activateBtn.style.cursor = 'pointer';
+                    activateBtn.innerHTML = originalHTML;
+                    const rehydratedLabel = activateBtn.querySelector('#universal-passkey-activate-label');
+                    if (rehydratedLabel) {
+                        rehydratedLabel.textContent = `Activate ${bioLabel}`;
+                    }
+
+                    let msg = 'Biometric verification was cancelled or did not complete. Tap Activate whenever you are ready to try again.';
+                    if (err) {
+                        if (err.name === 'SecurityError' || err.code === 'SecurityError') {
+                            msg = 'Passkey registration requires HTTPS or a valid domain origin.';
+                        } else if (err.name === 'NotSupportedError' || err.code === 'NotSupportedError') {
+                            msg = 'Biometric authentication is not supported or enabled on this browser.';
+                        } else if (err.message && err.name !== 'NotAllowedError' && err.code !== 'NotAllowedError') {
+                            msg = `${err.message}. Tap Activate to try again.`;
+                        }
+                    }
+                    showFeedback(msg, false);
+                }
+            });
+        }
+
+        return backdrop;
+    }
+
+    /**
+     * Automatically evaluates post-login state and shows the Biometric Passkey Activation UI if eligible.
+     * @param {Object} [customState]
+     * @returns {Promise<boolean>}
+     */
+    static async initPostLoginPrompt(customState = null) {
+        const state = customState || (typeof window !== 'undefined' ? window.__WEBAUTHN_PROMPT_STATE__ : null);
+        if (!this.shouldShowActivationPrompt(state)) {
+            return false;
+        }
+        const available = await this.isPlatformAuthenticatorAvailable();
+        if (!available) {
+            return false;
+        }
+        this.renderPromptModal(state);
+        return true;
+    }
 }