# TASK METADATA

- **Target Files:** `ui/components/LoginPage.tsx`,
  `ui/components/RegisterPage.tsx`, `ui/components/RecoveryPage.tsx`,
  `ui/public/auth-client.js`
- **Core Objective:** Modernize the login, registration, and recovery screens
  with one-tap hero passkey trigger, WebAuthn autofill / conditional mediation,
  and progressive disclosure for fallback options.
- **Dependencies:**
  `tasks/new/2026-0824.04.gem.feat.ui-shell.design-tokens-and-adaptive-nav-2215.md`
- **Additional Important Notes:** Must support seamless WebAuthn conditional
  mediation (`startAuthentication(..., true)`) while gracefully handling devices
  that do not support autofill.

---

## 1. TASK METADATA

The header block specifies the authentication templates, client-side WebAuthn
handler, core objective, dependencies, and constraints.

## 2. Architectural Considerations & Risks

### Risks

- **Autofill Abort Collisions:** If conditional mediation
  (`mediation: 'conditional'`) is running in the background and the user
  explicitly taps "Sign In with Passkey", some browsers can throw an
  `AbortError` if not handled correctly.
  - _Mitigation:_ Cancel or ignore active conditional mediation promises before
    starting explicit user-gesture WebAuthn authentication.
- **Missing Recovery Seed Visibility:** If the 12-word BIP39 seed phrase during
  registration is obscured or difficult to copy on mobile, users could lose
  account recovery capability.
  - _Mitigation:_ Provide a clear, high-contrast 12-word grid with a prominent
    1-tap "Copy All Words" clipboard button.

### Alternatives

- **Static Username Input vs Progressive Disclosure:** Showing a prominent
  username input confuses 95%+ of mobile passkey users whose credentials are
  discoverable resident keys. Collapsing the username field into an expandable
  drawer retains full backward compatibility for non-resident keys while
  providing a clean 1-tap experience for passkeys.

## 3. Proposed Implementation

### Phase 1: Hero Passkey Login Screen

1. Refactor `ui/components/LoginPage.tsx`:
   - Add a 52px biometric hero button: "Sign In with Passkey" with fingerprint
     SVG icon and subtle focus/press feedback.
   - Collapse optional username field and USB instructions behind an accessible
     `<details>` / toggle trigger.
   - Add pulse/spinner state when authenticator is active.

### Phase 2: WebAuthn Client Conditional UI

1. Update `ui/public/auth-client.js`:
   - Check `PublicKeyCredential.isConditionalMediationAvailable()` on page load.
   - If available, trigger
     `SimpleWebAuthnBrowser.startAuthentication(options, true)` in conditional
     mode.
   - On explicit button click, execute modal WebAuthn login.

### Phase 3: Registration & Recovery Mobile Polish

1. In `ui/components/RegisterPage.tsx`:
   - Streamline invite code and username entry into high-contrast inputs.
   - Format 12-word seed phrase in a 2-column mobile card grid with a 1-tap copy
     button.
2. In `ui/components/RecoveryPage.tsx`:
   - Support auto-advance input matrix and paste-all text box for seed phrase
     verification.

### Phase 4: Verification & Quality Gates

1. Run `deno fmt ui/**/*.tsx ui/public/**/*.js`.
2. Run `deno task lint` and `deno task check`.
3. Run `deno task test` to verify zero regression in authentication endpoints
   and redirects.