morphit/docs/CHAT-UI-DESIGN.md

# Chat UI Design — Phase 5d

**Status:** ✅ Chat surface is fully implemented and wired
into the main nav and surfaces.  The crypto module
(`apps/web/src/lib/chat/crypto.ts`), chat service controller
(`chatService.ts`), indexer endpoints, the on-chain op
(`morphit_chat_v1`), the `/chat` nav link in `+layout.svelte`,
the "Message" CTA on profile pages, and the "Message
seller/buyer" CTA on orderbook rows have all shipped.  This
doc describes the UX constraints that shaped the chat
surfaces; the "Entry points still to wire" and "What's left
to ship" sections below are retained as historical context
but have all closed.

> **Cipher note.** Earlier drafts of this doc referenced a
> heavier forward-secrecy protocol — that was the ADR-0014
> plan.  ADR-0015 replaced it with simpler per-message ECIES
> (X25519 + ChaCha20-Poly1305).  Anywhere this doc still
> describes session/envelope shape, the actual on-chain
> envelope is `{ ciphertext, header: { ephemeralPub, nonce } }`
> per ADR-0015.

## The one constraint that shapes every decision

**Blurt blocks are 3 seconds.** Chat messages are on-chain
`morphit_chat_v1` custom_json ops (ADR-0014). The chain-based
send→deliver round-trip is therefore **at least 3 seconds**, and
more realistically 3–6 seconds depending on where in the block cycle
a send lands.

A user who types "hi" and hits Enter cannot wait 3 seconds to see
their own message appear. **The UI must feel instant despite the
chain being slow.** Every architectural decision below exists to
reconcile those two facts.

## Optimistic local rendering

The user's own message is rendered in their chat pane *the instant
they hit Enter*, tagged as `'pending'`. The chain broadcast happens
in the background; the subsequent indexer poll merges the confirmed
record in and upgrades the state to `'confirmed'`.

States a local message can be in:

| State | Rendered as | How it got here |
|---|---|---|
| `pending` | Full opacity text, subtle ⏳ icon or just no time shown | Just submitted, broadcast in flight |
| `broadcast` | Same visual, internal flag only | Broadcast returned a trx_id, waiting for indexer |
| `confirmed` | Timestamp shown, icon removed | Indexer poll returned the record |
| `failed` | Red border, "Tap to retry" | Broadcast error (network, chain rejection) |

The user NEVER sees the difference between `pending` and `broadcast`
— both look identical. The split exists only so the retry path can
distinguish "I haven't even signed this yet" from "I signed it but
the chain hasn't confirmed in 15 seconds, probably a stuck node."

## Client-side deduplication: `client_tag`

The indexer's `chat_messages` table is keyed on `source_trx_id`
(unique). That's fine for server-side replay protection. But the
**client** can't use trx_id for reconciliation because at optimistic-
render time the trx_id doesn't exist yet — the op hasn't been
broadcast.

**Solution:** the client generates a random 16-byte `client_tag`
before broadcast and includes it in the **`header`** field of the
custom_json payload.

Why `header`? Because:
- The indexer already passes `header` through verbatim as opaque
  JSONB — no schema change needed
- The indexer chat-op handler doesn't validate the contents of
  `header` beyond size limits (it's the per-message ECIES
  envelope metadata — `ephemeralPub`, `nonce`, plus the
  `client_tag` — opaque to the chain)
- The client-side chat module already owns every byte of the
  payload it constructs, so adding a field is trivial

Flow:
1. User hits Enter → client generates `client_tag = randomBytes(16).hex()`
2. Client renders message in the pane with state `pending`,
   keyed locally by `client_tag`
3. Client builds payload: `{ recipient, ciphertext, header: { ...dr_header, client_tag } }`
4. Broadcast returns a trx_id. Client flips local state to `broadcast`.
5. Indexer poll (every ~3s) returns messages including the new one.
   Each returned message's `header.client_tag` is checked against
   pending/broadcast messages; on match, merge the server record
   (id, created_at) in and flip state to `confirmed`.
6. Messages received WITHOUT a matching local `client_tag` are
   new incoming messages from the counterparty.

Indexer change required: **none.** The field lives inside the
opaque `header` JSONB. The handler already accepts anything there
up to the size cap.

Shared-types change required: **none.** `header: unknown` stays
unknown; the client module reads `header.client_tag` at its own risk
and tolerates its absence gracefully (messages from older clients
wouldn't have one; they're matched against trx_id as a fallback).

## Poll cadence

Messages are delivered by polling `/v1/chat/:a/:b` — there's no
websocket or push channel.

Since blocks are 3s, polling faster than that is pure waste. Cadence:

- **Active chat view, tab in foreground**: poll every **3s**,
  aligned to block-timestamp boundaries with ±500ms jitter to
  spread load across users
- **Active chat view, tab in background**: poll every **15s**
  (document.visibilityState === 'hidden' triggers the backoff)
- **Inbox view (not in a specific chat)**: poll the per-
  conversation-count endpoint every **10s**; this is lighter
  than per-conversation polling

Each poll uses the **latest `created_at` cursor** we've seen, so
we only fetch the delta since last poll. A fresh page load does
one full fetch of the most recent 50 messages to populate history.

**Block-align trick**: a Blurt block lands roughly on the integer
3-second second. Aligning our polls to `(Date.now() % 3000)`
boundaries with jitter maximizes the chance a freshly-mined
block's messages are in the response. Less than ideal worst case
is we miss a block and catch it on the next poll (≤3s extra
latency). Acceptable.

## Per-message crypto is CPU-bound

Per-message libsodium operations (X25519 ECDH, ChaCha20-Poly1305
AEAD, BLAKE2b) take 1-5ms each on modern hardware, but a chat
load of 50 messages = 50 decrypts. Even at 5ms that's 250ms of
main-thread work if done synchronously, which is enough to
freeze the scroll.

**Rules:**
- Never `await` a chat decrypt inside a Svelte `$derived`.
  The reactivity system would block on each decrypt.
- Decryption happens in a background loop (a `$effect` that
  processes pending ciphertexts one at a time, with `await` so
  the event loop breathes between each).
- **Decision deferred to implementation time**: whether decryption
  moves to a Web Worker. Probably yes for messages >10, because a
  worker lets the UI keep rendering other content (scrolling,
  typing, paging) while the history decrypts. For messages ≤10,
  main-thread with async boundaries is fine.
- Message encryption on send: always main-thread, always in the
  send path (not parallel — we need the ciphertext before
  broadcast). But it's one op, ~50ms worst case, invisible.

## Virtualization

A conversation of 500 messages with identicons and timestamps is
~15MB of DOM. Mobile Safari chokes at around 2000 nodes in a
scrollable container.

Threshold: **virtualize when `items.length > 50`**. Below that,
static `{#each}` is fine and avoids the flicker of virtualizer
warm-up.

Above 50, use a windowed list: render 20 messages above and below
the viewport; recycle as the user scrolls.

Any library? No need to bundle one — the pattern is small enough
to write inline:
- Track `scrollTop`, `viewportHeight`
- Maintain an estimated message height (updates as real messages
  render)
- Render only the window; spacers above/below with `height`
  equal to `(first-visible-index) * avgHeight`

## Draft persistence

If the user closes the tab mid-message, the draft should survive.

**Keyed by conversation**: `localStorage['morphit.chat.draft.<peer-account>']`.

**Lifecycle**:
- Typing anywhere in a compose box → debounced 500ms save
- Successful send → wipe the key
- Explicit lock (user taps "Lock now") → wipe all drafts along
  with the identity (same as the existing Lock Session behavior)
- Auto-lock → **keep** drafts. Auto-lock is an idle timeout; the
  user's intent to send the message is still there. They'll
  unlock and finish typing.

This is more conservative than wiping on every lock, but it
matches user expectation. Locked-state drafts are low-sensitivity
plaintext sitting in localStorage — a lower bar than the keystore
itself, but the user chose to type it somewhere unencrypted, and
the tradeoff for convenience wins.

## Composer behaviors

- **Enter**: send
- **Shift+Enter**: newline
- **Tab**: default focus behavior (escape the textarea)
- After send: the composer retains focus but clears its value
- Sending disabled when the text is empty OR trimmed-empty
- Sending disabled while the identity is locked (show unlock hint
  where the Send button would be)
- **Private-key detector (already built)**: the composer uses
  `ProtectedTextarea` + `PrivateKeyWarningModal` exactly like
  the feedback forms. `redactPrivateKeys()` runs on the plaintext
  before it goes into the ECIES encryption step. The
  ciphertext that gets broadcast contains only the redacted form.
- 256-codepoint plaintext cap (matches the indexer's
  `MAX_CIPHERTEXT_CHARS` budget after AEAD tag + base64
  overhead). Live counter next to the input.

## Mobile viewport

iOS Safari and Android Chrome both reshape the viewport when the
keyboard appears. Old behavior: the visual viewport shrinks but
CSS `100vh` doesn't.

**Rules:**
- The chat container uses `height: 100svh` (small viewport height;
  accounts for the keyboard).
- The message list is the flex-grow child; the composer is
  fixed-height at the bottom.
- Avoid `position: fixed` on the composer — it misbehaves with the
  iOS keyboard. Use the flex layout instead.
- When a new message comes in AND the user is scrolled to the
  bottom, scroll to the new message. When the user is scrolled
  up reading history, show a **"N new messages ↓"** pill that
  scrolls down on tap instead of forcing them.

## What belongs on-chain vs off-chain

**On-chain** (via `morphit_chat_v1`):
- The ciphertext + ECIES envelope header of each sent message
  (`{ ephemeralPub, nonce }`). One op per message.

**Off-chain** (local state only, never sent anywhere):
- Draft text
- Typing indicator ("Alice is typing…")
- Read receipts (contentious — skip for now; a "read" event
  taking 3+ seconds to deliver is worse than no read receipts)
- Presence (online/offline)

Typing indicators and presence could theoretically be done via
WebRTC data channels between peers once both are on the chat
page, but that's significant complexity for a secondary feature.
**Decision: skip for v1.** The 3-second block time makes these
features inherently laggy on-chain anyway.

## What already exists in the codebase

- `apps/web/src/lib/chat/crypto.ts` — full ECIES implementation
  per ADR-0015. Exports `deriveChatIdentity`,
  `encryptToRecipient`, `decryptFromSender`, plus encode/decode
  helpers and a `wipeChatIdentity` zeroing utility. 22 vitest
  scenarios cover the round-trip + AAD binding + tamper
  detection.
- `apps/web/src/lib/chat/chatService.ts` — full state-machine
  controller. Owns the optimistic-render flow, polling cadence,
  client_tag reconciliation, decrypt-on-read pipeline, retry
  ladder. Wired to the real crypto.
- `apps/web/src/lib/chat/ensureChatIdentity.ts` — one-time
  publish-on-first-need flow for the chat identity key.
- `apps/web/src/lib/chat/pubPin.ts` — TOFU pinning of the
  peer's chat pubkey + chain re-verification on mismatch.
- `apps/web/src/lib/chat/blocks.ts` — chain-block management.
- `apps/web/src/lib/chat/readState.ts` — local + on-chain
  read-state tracking.
- `apps/web/src/lib/chat/recentPeers.ts` — fallback peer list
  when the indexer hasn't yet seen any conversations.
- `apps/web/src/lib/components/ConversationView.svelte` —
  per-conversation chat UI. Implements the scroll-to-bottom UX
  in this doc, the block/unblock affordance, and the stranger-
  fee admission flow.
- `apps/web/src/routes/[lang]/chat/+page.svelte` — inbox with tabbed
  Messages / Requests partitioning.
- `apps/web/src/routes/[lang]/chat/[peer=account]/+page.svelte` —
  per-conversation route.
- `apps/indexer/src/api/chat.ts` — `/v1/chat/:a/:b` endpoint
  with cursor pagination. Canonicalizes the pair so
  `/chat/alice/bob` and `/chat/bob/alice` hit the same
  conversation.
- `apps/indexer/src/indexer/handlers/chat.ts` —
  `morphit_chat_v1` op handler.
- `apps/indexer/src/indexer/handlers/chatIdentity.ts` —
  `morphit_chat_identity_v1` op handler.
- `apps/indexer/src/indexer/handlers/chatRead.ts` —
  `morphit_chat_read_v1` op handler.
- `packages/indexer-client/src/index.ts` — `ChatMessageRecord`,
  `ChatHistoryResponse`, `ConversationSummary` shared types.

## Routes (implemented)

- `/chat` — inbox: list of conversations with Messages /
  Requests tabs, unread badge, hidden + blocked filtering.
- `/chat/[peer]` — conversation view.

## Entry points still to wire

- **Main nav**: `/chat` is not yet linked from the top nav.
  Adding requires the unread-badge surface in the nav itself.
- **Profile page**: a "Message" CTA next to the IdentityLabel
  for any viewer (→ `goto('/chat/' + account)`).
- **Order rows**: a "Message seller/buyer" CTA on order detail
  rows (for non-owners) → `goto('/chat/' + order.account)`.

## Open items deferred

1. **Identity publication**: when and how the user publishes their
   chat identity key via `morphit_chat_identity_v1`. Implemented
   as auto-publish on first compose attempt, idempotent (skipped
   if a key is already on chain). See `ensureChatIdentity.ts`.
2. **Multi-device**: out of scope for v1. A single device per
   account. Multi-device requires key-server or linked-device
   flows — defer to Phase 6.
3. **Message deletion**: chain entries are permanent. A client-
   side "hide" is possible (local blocklist of trx_ids) but
   confusing UX — probably skip for v1.
4. **Conversation deletion**: same — chain entries are permanent.
   Client-side hide only.
5. **Block/unblock a user**: lands via the chain block op. See
   "Block/unblock — landed" below.

## Block/unblock — landed

Block/unblock rides on `morphit_block_v1` (chain-broadcast).
The chain block prevents the blocked sender's new messages
from being delivered to the blocker by the indexer's
admission gate (Finding H layer 1).  Hidden-accounts is the
local-only equivalent (see ADR-0013 Q1.4) and applies on
orderbook surfaces; chat surfaces honor BOTH stores
(§F.22 ensured the same on orderbook for symmetry).

## What's left to ship (historical — all closed as of Part 120 audit)

The core chat infrastructure is implemented.  The remaining
wiring described below has all shipped:

1. ✅ `/chat` is in the main nav (`apps/web/src/routes/+layout.svelte`).
2. ✅ "Message" CTA on profile pages
   (`apps/web/src/routes/[lang]/[x+40][account=account]/+page.svelte`).
3. ✅ "Message seller" CTA on orderbook rows
   (`apps/web/src/routes/[lang]/orderbook/+page.svelte`).
4. i18n key coverage across all 10 locales is verified
   continuously by the locale-parity smoke
   (`apps/web/scripts/i18n-locale-parity-smoke.ts`).
5. End-to-end manual smokes are operator/QA work and continue
   on every release cycle.