client/plans/cashu-ux-cleanup.md

Cashu Page UX Cleanup — Fix Ambiguous Wallet Status

Problem

When loading cashu.html, the page shows confusing, ambiguous messaging:

1. "Wallet Status / Wallet ready" appears as a card, then below it "Create Wallet" appears — user wonders: is the wallet ready or do I need to create one?
2. The "Create Wallet" setup panel says "No NIP-60 wallet found" — but what is NIP-60? Why should the user care?
3. The status card and setup panel both compete for attention with no clear hierarchy
4. When a wallet IS loaded, the status card still says "Wallet ready" as a static label — it looks like a title, not a status

Root Cause

The page has two independent visibility states that can overlap:

• divWalletStatus — always visible, shows text like "Wallet ready" or "No wallet found"
• divSetupPanel — shown when no wallet exists, hidden when wallet exists
• divWalletContent — shown when wallet exists, hidden when no wallet

The problem is that divWalletStatus lives inside its own cashuCard that is ALWAYS visible regardless of state. So users see "Wallet Status" card + "Create Wallet" card simultaneously.

Solution: Two Mutually Exclusive Page States

The page should show exactly ONE of two states at any time, with a small status bar for transient messages.

State Diagram

stateDiagram-v2
    [*] --> Initializing
    Initializing --> SetupState: No wallet event found
    Initializing --> WalletState: Wallet event found
    SetupState --> WalletState: User creates wallet
    WalletState --> WalletState: Refresh / balance update

State 1: Setup — No Wallet Exists

┌─────────────────────────────────────┐
│  HEADER                             │
├─────────────────────────────────────┤
│                                     │
│  ┌─────────────────────────────┐    │
│  │  Get Started                │    │
│  │                             │    │
│  │  Your Nostr account doesnt │    │
│  │  have a Cashu wallet yet.   │    │
│  │  A Cashu wallet stores      │    │
│  │  ecash tokens backed by     │    │
│  │  Bitcoin, using one or more │    │
│  │  mints as token issuers.    │    │
│  │                             │    │
│  │  Mints                      │    │
│  │  ┌───────────────────────┐  │    │
│  │  │ https://mint1...      │  │    │
│  │  │ https://mint2...      │  │    │
│  │  └───────────────────────┘  │    │
│  │                             │    │
│  │  [Create Wallet]            │    │
│  │                             │    │
│  │  ─ status message here ──   │    │
│  └─────────────────────────────┘    │
│                                     │
├─────────────────────────────────────┤
│  FOOTER                             │
└─────────────────────────────────────┘

Key changes:

• Title is "Get Started" not "Create Wallet" — less confusing when combined with status
• Explanatory text says what a Cashu wallet IS in plain language — no mention of "NIP-60"
• The status message line is INSIDE this card at the bottom, not a separate card
• No separate "Wallet Status" card visible at all

State 2: Wallet Loaded

┌─────────────────────────────────────┐
│  HEADER                             │
├─────────────────────────────────────┤
│                                     │
│  ── status: Wallet ready ────────   │
│                                     │
│  ┌─────────────────────────────┐    │
│  │  Balance                    │    │
│  │  1,234 sats                 │    │
│  │  mint1: 800 | mint2: 434    │    │
│  └─────────────────────────────┘    │
│                                     │
│  [Receive] [Send] [Deposit]         │
│                                     │
│  ┌─────────────────────────────┐    │
│  │  Action panel               │    │
│  └─────────────────────────────┘    │
│                                     │
│  ... rest unchanged ...             │
│                                     │
├─────────────────────────────────────┤
│  FOOTER                             │
└─────────────────────────────────────┘

Key changes:

• The status message becomes a small inline text line above the balance card, not its own bordered card
• When status is "Wallet ready" it fades to muted color — its not a headline, its a status indicator
• Transient statuses like "Receiving token..." or "Token received" appear in this same line
• The separate "Wallet Status" card with its own border and title is removed

Implementation Steps

Step 1: Remove the Wallet Status card, replace with inline status line

File: www/cashu.html

Remove the current status card:

<!-- REMOVE THIS -->
<div class="cashuCard">
  <div class="cashuCardTitle">Wallet Status</div>
  <div id="divWalletStatus">Initializing…</div>
</div>

Replace with a simple inline status element placed OUTSIDE any card, at the top of divCashuPage:

<div id="divWalletStatus">Initializing…</div>

Add CSS to style it as a subtle status line rather than a card:

#divWalletStatus {
  font-size: 80%;
  color: var(--muted-color);
  min-height: 18px;
  text-align: center;
  padding: 2px 0;
}

#divWalletStatus.error {
  color: var(--accent-color);
}

Step 2: Rewrite the Setup panel copy

File: www/cashu.html

Change the setup panel from:

<div id="divSetupPanel" class="cashuCard clsHidden">
  <div class="cashuCardTitle">Create Wallet</div>
  <div style="font-size: 80%; color: var(--muted-color);">
    No NIP-60 wallet found for this account, add one or more mints and create a wallet.
  </div>
  <textarea id="taSetupMints" ...></textarea>
  <button id="btnCreateWallet" ...>Create Wallet</button>
</div>

To:

<div id="divSetupPanel" class="cashuCard clsHidden">
  <div class="cashuCardTitle">Get Started</div>
  <div style="font-size: 80%; color: var(--muted-color);">
    Your Nostr account does not have a Cashu wallet yet.
    A Cashu wallet stores ecash tokens backed by Bitcoin, using one or more mints as token issuers.
    Add at least one mint below to create your wallet.
  </div>
  <div style="font-size: 80%; font-weight: bold; color: var(--primary-color); margin-top: 5px;">Mints</div>
  <textarea id="taSetupMints" class="cashuTextarea" placeholder="Mint URLs — one per line"></textarea>
  <button id="btnCreateWallet" class="cashuBtn">Create Wallet</button>
</div>

Step 3: Move the status line inside the setup panel for setup state

When in setup state, the status message should appear inside the setup card — not floating above it. Add a second status display point inside the setup panel:

<div id="divSetupStatus" style="font-size: 80%; color: var(--muted-color); min-height: 18px; text-align: center;"></div>

The setStatus() function should update BOTH divWalletStatus and divSetupStatus so the message appears wherever the user is looking.

Step 4: Update the JavaScript state transitions

File: www/cashu.html — inline script

Update showSetup():

function showSetup() {
  divSetupPanel.classList.remove('clsHidden');
  divWalletContent.classList.add('clsHidden');
  divWalletStatus.classList.add('clsHidden'); // hide top-level status in setup mode
  // ...existing mint prefill logic...
}

Update showWallet():

function showWallet() {
  divSetupPanel.classList.add('clsHidden');
  divWalletContent.classList.remove('clsHidden');
  divWalletStatus.classList.remove('clsHidden'); // show top-level status in wallet mode
}

Step 5: Update status messages to be less ambiguous

File: www/cashu.html — inline script

Change the initialization status messages:

Current message	New message
'Wallet ready'	'Wallet loaded'
'No wallet found, create one to begin'	(no top-level status — setup panel explains everything)
'Loading wallet...'	'Loading wallet…'
'Initializing…'	'Connecting…'
'Creating wallet...'	'Creating wallet…'
'Wallet created'	'Wallet created successfully'

Step 6: Update setStatus to write to both status locations

function setStatus(message, isError = false) {
  divWalletStatus.textContent = message;
  divWalletStatus.classList.toggle('error', Boolean(isError));

  // Also update setup panel status if it exists and is visible
  const divSetupStatus = document.getElementById('divSetupStatus');
  if (divSetupStatus) {
    divSetupStatus.textContent = message;
    divSetupStatus.style.color = isError ? 'var(--accent-color)' : 'var(--muted-color)';
  }
}

Files to Modify

File	Changes
www/cashu.html — HTML	Remove Wallet Status card, add inline status line, rewrite setup panel copy, add setup status element
www/cashu.html — CSS	Restyle #divWalletStatus as inline text instead of card content
www/cashu.html — JS	Update showSetup(), showWallet(), setStatus(), and status message strings

No changes needed to www/js/cashu-wallet.mjs — this is purely a UI/UX fix.

Summary of What Changes

1. Remove the always-visible "Wallet Status" card — replace with a subtle inline status line
2. Rewrite the setup panel: title becomes "Get Started", copy explains what a Cashu wallet is in plain language, no NIP-60 jargon
3. Ensure only one state is visible at a time — setup OR wallet, never both competing
4. Move status messages to appear contextually — inside the setup card during setup, as an inline line during wallet use
5. Improve status message wording to be unambiguous