UX audit & upgrade plan — VayuMail and VayuTalk

Date: 2026-08-26 · Scope: every user-facing surface of VayuMail (cmd/vayupress/vayuos_mail*.go, vayuos.go inbox/reader/search, accounts/contacts/DNS/devices/recovery handlers, static/js/admin-os-mail*.js) and VayuTalk (vayuos_talk.go, handlers_vayutalk.go, tor_talk_*.go, internal/vayuos/vayutalk/, static/js/admin-os-talk.js), plus the shared Admin-OS shell they live in (admin_os_ui.go, static/js/admin-os.js, static/css/admin-os.css). Method: adversarial source review walked as user journeys, same discipline as SECURITY-AUDIT-2026-07 but optimising for "super cool and easy to use" instead of attacker outcomes.

Security posture is not re-audited here: docs/SECURITY-AUDIT-2026-07-VAYUMAIL-VAYUTALK.md records all prior findings as fixed with regression tests. This document is the usability twin: what it costs a human to get something done, where the product silently lies or goes quiet, and where the day-to-day surfaces fall short of the operations surfaces' own standard.

Finding IDs: T-n = VayuTalk, M-n = VayuMail, S-n = shared shell/platform. Severity: P0 breaks the product promise · P1 major friction or trust damage · P2 recurring annoyance · P3 polish. Every finding cites file:line evidence.

Verdict

The bones are better than the feel. Both apps run on a genuinely strong platform — token-based design system with dark/light/Tor palettes, HTMX fragment backbone, strict CSP done right, a real component library (toasts, modals, skeletons, empty states), and exemplary XSS hygiene (textContent-only DOM building). The operations surfaces — DNS setup with live verification, recovery console, device approval, TLS diagnostics — are best-in-class for a self-hosted panel: plain language, honest failure copy, enumeration-safe flows.

The pain is concentrated and diagnosable. Five root causes produce nearly every finding below:

1. Failure paths are unloved. The happy path is polished (optimistic bubbles, undo-send); every error/reconnect/destructive path either goes silent, lies ("Copied" without copying), destroys user work (failed sends, draft race), or resurrects the dead (the P0).
2. There is no shared interaction foundation. Every app re-rolls cookie()/csrf()/toast; Members-era surfaces still use window.confirm/prompt/alert + full reloads while newer ones use modals + toasts — inside the same product.
3. The render model fights the data model. Full-folder filesystem scans on every poll/action make the mailbox get slower precisely as it gets more useful. Perf here is UX.
4. Trust signals whisper. For an E2E-encrypted product, a peer key change is silent, a failed decryption is indistinguishable from a friend going quiet, and Sent/Delivered/Read is never explained.
5. Admin-console patterns where app patterns belong. Nine flat tabs, tables everywhere, no pagination, no presence, no shortcuts worth the name — feature-rich, but it reads like a panel, not a mail/chat app.

The plan (Part 4) attacks these in order: correctness first, one feedback system second, then the mail-app feel, then the delight bets.

Part 1 — What is already excellent (do not regress)

Any upgrade must preserve these; several were explicit design wins found during the audit:

• XSS/CSP posture: all dynamic UI built via createElement/textContent; no innerHTML with untrusted data; nonce'd scripts; DOMPurify-guarded single sink (admin-os-editor.js:1714); OnionMode strips external origins at one chokepoint (internal/render/csp.go:31-48).
• Honest, human copy on the hard paths: onion-delivery failures name each reason (onion_transport.go:286-324); TLS mismatch predicts the exact Gmail-app symptom (vayuos_mail.go:1370-1407); recovery flows are enumeration-proof with constant responses (handlers_mail_recovery.go:41-66).
• Recovery console: codes shown once with Copy-all / Download / print, link consumed only on POST, assisted queue asks the operator to verify identity channel out loud (handlers_mail_recovery_pages.go:96-179, admin-os-mail-recovery.js:92-251,350-355).
• DNS/domain setup: 7 copy-paste values with per-value Copy, live verification for every domain, grey-cloud warning, deliverability self-check (vayuos_mail_dns.go:63-172).
• Composer depth: chips with inline validation, scoped private contact autocomplete, plain-text formatting toolbar with honest framing, preview, dropzone, per-identity signatures, PGP toggle, optional HTML alt part, word count, 8s undo-send with keepalive flush (vayuos_mail.go:45-257, admin-os-mail.js:102-573).
• Quota truth: warn/full bar plus hard over-quota send block with plain words (vayuos.go:2024-2043, vayuos_mail.go:526-529).
• VayuTalk privacy model: messages tab-memory-only; only contact names/keep-flags and fingerprints persist; notifications carry sender name never text (admin-os-talk.js:14-21,109-140).
• Bounded relay state, ownership-checked acks, SSRF-guarded onion dialer (internal/vayuos/vayutalk/store.go:19-34, handlers_vayutalk.go:246-279, tor_talk_identity.go:68-76).
• Platform guards that keep quality high: build-breaking CSS contract tests (css_contract_test.go:21-98), assetVer() content-hash cache busting, role-gated nav.

Part 2 — Findings

2.1 VayuTalk (/os/talk)

2.2 VayuMail

2.3 Shared shell / platform

Part 3 — Upgrade plan

Four phases, each shippable independently, ordered by trust-per-effort. Sizes: S ≤ half day, M 1–3 days, L > 3 days. Every item lists its finding IDs; nothing here requires new dependencies, CSP changes, or design-language forks (guardrails in Part 5).

Phase 0 — Correctness & trust (ship first)

Goal: the product stops lying and stop losing user work. These are small diffs with outsized credibility impact.

Done when: a reconnect after burn no longer resurrects messages (test-pinned); deleting an account can never leak old mail to a reissued address (test exists at store level — wire the panel to it and pin at handler level); no destructive action proceeds unconfirmed; no failure path silently discards user input.

Phase 1 — One feedback system + consistency sweep

Goal: every surface answers within a heartbeat and speaks in the same voice.

Done when: every mutating action in Mail/Talk surfaces ends in a toast/fragment update (never reload, never silence); a fresh install passes a keyboard-only walkthrough of inbox → read → reply → compose → send.

Phase 2 — Make it feel like a mail app

Goal: speed and flow at realistic mailbox sizes; close the gap to the Gmail-class experience ADR-0083 set.

Done when: opening a 10k-message mailbox feels the same as a 50-message one (pinned by a benchmark-style test on ListFolder path); HTML newsletters readable on demand without weakening CSP; a phone user completes receive-reply-send without scrolling past a rail.

Phase 3 — Structural bets (schedule deliberately, one ADR each)

Goal: remove the causes Phases 0–2 worked around. Each needs a short ADR because it revisits a recorded trade-off.

Part 4 — Guardrails (binding for any implementation)

These come from the platform audit and are enforced partly by tests, partly by CSP:

Do

• Model interactions as HTMX fragment endpoints (hx-get/post → target innerHTML), reuse the vm-poller + HX-Trigger fan-out patterns; CSRF comes free from shell glue (admin_os_ui.go:1554-1603).
• Style only via tokens and established prefixes (vm-*, vtalk-*, BEM-ish --modifier) in admin-os.css — the CSS contract tests fail the build otherwise (css_contract_test.go:21-98).
• Build DOM with createElement/textContent; route rendered-HTML needs (message previews!) through the DOMPurify sink (renderSanitized, admin-os-editor.js:1714-1724).
• Use vpToast(msg,'ok'|'error'|'warn'|'info') and fragment updates; never location.reload().
• Reuse .empty-state, .skeleton--*, .chip, .modal-panel, .dropdown-menu, inline currentColor SVG icons verbatim.
• Ship assets through embed + assetVer(); register routes beside the others in registerAdminOSUIRoutes.

Don't

• No CDNs, external fonts/APIs, unsafe-eval, standard Alpine builds, or markup-expression compilers — under this CSP they are inert, not degraded (csp.go:190-195). Alpine stays islands-only (CSP build, registered before alpine:init).
• No inline <style>/style="" attributes; no invented classes without stylesheet rules.
• No window.confirm/prompt/alert in new or migrated surfaces.
• Nothing may break under OnionMode (all external origins stripped automatically).
• Never persist message content client-side; hidden ≠ unreachable — keep server-side gating authoritative (gate() + osPathMinLevel).

Test hooks that must stay green (and grow): css_contract_test.go, css_console_baseline_test.go, console_fonts_test.go, vayumail_ui_test.go, client_surface_completeness_test.go, plus new regression tests pinned by Phase 0 (reconnect-resurrection, delete-path inheritance) and Phase 2 (large-mailbox listing cost).

Appendix — Implementation status (2026-09-13)

What was built against this document, as first verified on the author's Windows machine. It shipped in v3.17.71 after the Linux review recorded at the end of this appendix, which also lists what that review changed.

Verification method. A baseline was captured on the current HEAD for the touched packages (cmd/vayupress, internal/vayuos/{mail,vayutalk,pgp}, internal/render, internal/db, internal/settings), then re-run after each phase and diffed by test name. Final state: 64 failing tests before and after — zero regressions. Those 64 are environment limits, not defects: systemd/nginx/firewall/cosign/bundle tests that need a Linux host, and Maildir tests whose flag filenames contain : (illegal on NTFS). Two loopback-listener tests (TestSMTPReceiveDelivers, TestIMAPStableUIDsAcrossReconnect) time out intermittently under full-suite load on this box and pass on re-run — both were verified individually before being dismissed.

Phase 0 — Correctness & trust: 12/12 done

Every item implemented and pinned by cmd/vayupress/vayuos_ux_regression_test.go (16 tests): the reconnect tombstone, honest clipboard reporting, retry-on-failure, confirm-before-Rotate, keyboard-reachable conversation rows, the changed-safety-number alarm, account deletion through DeleteMailbox, drafts that keep Cc/Bcc, visible contact-save failures, bulk partial-failure reporting, the draft-navigation race, and a masked password modal (focus restored on close).

Phase 1 — One feedback system: 8/9 done

Done: toast kind normalisation (success/danger/warning were rendering unstyled), window.vpCsrf exposed, vpPost hardened for non-JSON bodies and expired CSRF, swap indicators on inbox/search/accounts, plain-language send errors, a bounded Talk stream-retry that names the remedy, live-region announcements, aria-expanded on the verify toggle, the Talk micro-friction pack, the Mail polish pack (dated quotes, app-password copy/download, “Later today”, c keeping ?user=, custom retention days, Archive unread counts), the dead /os/messages bottom-nav link, console high-contrast/forced-colors rules, and the premium Mail-IDs console (M-17) — which no longer reloads the whole page after every approve/disapprove/add/remove, uses vpConfirm instead of the native dialog, carries no inline styles, and serves its cards as a fragment.

Partial: the shared-foundation item reused the existing vpConfirm/vpPost/vpToast instead of adding admin-os-common.js. No native dialog remains in any console script; a test scans every file.

Correction found while implementing: the console's empty-state variants are .empty-icon/.empty-title/.empty-sub, not the -state- names one fix note in this document used. The build-breaking CSS contract test caught it.

Phase 2 — Mail-app feel: 10/10 done

• 2.1 A parsed-header cache in the Maildir (listing is stat-bound, validated by size+mtime, with a test proving a rewritten file is never served stale); the folder view windowed at 200 rows with “Load older” and the count of what is out of view, the window carried through polls and pane actions; a short TTL cache for displayed mailbox sizes while the quota gate measures fresh.
• 2.2 Search asks for two characters, debounces at 600 ms, and says when the scan hit its limit instead of reporting a floor as a total.
• 2.3 Opt-in HTML rendering with a plain-text default. Two sanitiser policies: the default strips image SOURCES (a privacy boundary — loading a tracker tells the sender the mailbox opened the message), the opt-in loads them. Verified by tests that assert scripts, handlers, iframes and every image URL are gone from the strict path.
• 2.4 Evidence-first threading: In-Reply-To/References decide, subject is the fallback, so a reply joins its parent even when the subject changed and unrelated mail sharing a subject is no longer merged. Eight tests, including a reference loop.
• 2.5 A real first-run empty inbox with Compose/Connect CTAs.
• 2.6–2.10 Presence-lite (one-sided by design: “online” only when a stream exists, never a claim about someone's phone), the Talk recipient picker, the phone dual-view (list ⇄ thread with a back control, dvh-sized thread, no more 40vh rail), a peerkey stream event that clears stale “unverified” badges, and the decrypt-loss chip.

Phase 3 — Structural bets: 5/7 done

• 3.2 Per-reader cursors — the root fix for the P0. Envelope.WebRead plus QueuedExcludingWebRead/MarkWebRead in the store, SubscribeWeb and the ownership-checked MarkWebReadAs on the engine, the console wired to both, and the client signalling reads in the clearnet world as well. Three engine tests pin that a reconnect stops re-flushing, the app's queued copy is untouched, and the app's ack remains the destroyer.
• 3.3 Drafts as real messages — attachments are stored as MIME parts and the send path merges them back by draft id, so reopening a draft and pressing Send no longer ships a message without the files the composer was showing. Autosave deliberately skips while files are attached (it would re-upload them on every keystroke); the button still stores them and the composer says so. Four engine tests, including a hostile filename and a binary round trip.
• 3.4 Domain-health checklist — a guided card above the DNS reference tables, built from the same one-per-render verdict set (so the two can never disagree), ending in a named next step, refreshed out-of-band with the Re-check button. Five tests.
• 3.6 Share links (minus QR): /os/talk?t=<address> pre-fills Start, for people with mailboxes on the same install. The Tor world's “Copy share link” was removed in review: it pointed at this install's console, where no outsider can sign in and every insider already is that code, so it could not work.
• 3.5 Per-mailbox settings page — every per-mailbox setting (forwarding, vacation, aliases, recovery, handover, PGP, filters, picture picker) now lives on its own routed URL, /os/vayumail/accounts/settings?user=…. The accounts list keeps what an operator scans across mailboxes and links out, so the seven-nested-<details> card and its whole-list re-renders are gone. The section builders are shared, so the swap target is adapted in one documented place and the response surface is chosen from HTMX's HX-Target; tests assert the settings page contains no list-surface target and that a list-surface control still receives the list, so neither surface can silently swap the other. This retired TestAccountCardHasEverySetting by design and replaced it with TestEveryPerMailboxSettingLivesOnItsOwnPage, which asserts nothing became unreachable.

Also fixed along the way (not in the original plan): the composer's link inserter was the last window.prompt in the Mail/Talk surfaces — it is now a console modal, and a test forbids window.prompt/window.confirm from returning to either file (window.alert is allowed exactly once, as the documented toast fallback).

Still open — and how each was closed (v3.17.72)

• 3.1 SQLite message-header index. Measured, then settled by ADR-0162: no index. The listing was slow for two other reasons, now fixed — a cold listing read every message whole, and one install-wide cache bound reset whole at 50,000 entries, so a warm listing of a 60,000-message folder cost 1.11 s. Headers-only reads and per-folder eviction bring that to 326 ms, without a second copy of the mail to keep right.
• 3.5 Per-mailbox settings page. Done — see above. TestAccountCardHasEverySetting was retired deliberately: it pinned the nested-in-one-card design, and the replacement test asserts the stronger property (nothing became unreachable).
• 3.7 String extraction / i18n prep. Designed in ADR-0163 and deliberately not extracted: with no target language, extraction adds a lookup to every sentence and translates nothing. The ADR fixes how it is done when the first language arrives.
• Phase 1 leftovers: the shared client foundation was reused (existing vpConfirm/vpPost/vpToast) rather than centralised. No native dialog remains in the console — TestConsoleScriptsUseTheConsolesOwnDialogs scans every script file and TestConsoleInlineScriptsUseTheConsolesOwnDialogs every Go-served one — and hx-confirm goes through vpConfirm too.
• Full-page reloads after a change in Members, Newsletter, Analytics, SEO and Security are gone: vpRefresh re-renders the page in place, keeping the toast, scroll, focus and open sections, and the scripts listen by delegation so the new controls work. Analytics goals update from the confirmed reply, because that page is served from a background cache, which a goal change now rebuilds. The self-update reload stays: the new binary's assets must load.
• 3.4 nav badge: a failing mail domain is raised in the notification bell and on the DNS tab, from a verdict stored by every live check and a six-hourly background watch — no page render asks DNS.
• QR codes: VayuTalk's new share panel shows the chat link (the anonymous code in the Tor world) as text, a Copy button and a QR code, served per identity through the same entitlement check as every Talk request.

Four findings no phase picked up (closed in v3.17.74)

A check of every finding ID against the plan found four P3 rows that no phase ever assigned, so nothing tracked them:

• T-22 — VayuTalk asked for notification permission on every page load and every Start. It now asks only from Start, at most once per visit, and on load only picks up a permission already granted.
• T-23 — Talk's buttons and badges used colour emoji beside the console's monochrome icons. They now use a small set of line icons in currentColor. The page-wide callouts keep the console's callout style.
• T-25 — a live stream whose buffer was full was skipped and left open, so it never reconnected to collect queued store-mode messages. It is now closed; the client reconnects and the queue is re-delivered (TestAStuckStreamIsClosedSoItsClientReconnects).
• M-21 — the mailbox two-factor dialog now closes on Escape, verifies on Enter and returns focus to the button that opened it.

With these, every finding in Part 2 is either fixed or settled by an ADR, and the only plan item not built is 3.7, which waits for a first language by design (ADR-0163).

Corrections to this document found while implementing

1. The console's empty-state variants are .empty-icon/.empty-title/.empty-sub, not the -state- names one fix note used — the build-breaking CSS contract test caught it.
2. high-contrast.css could not have reached /os even after a retarget: it is a public-tier asset, and it is a minified Go const behind a codegen test. The console now carries its own prefers-contrast/forced-colors rules in admin-os.css.
3. The “Copied” bug was wider than one call site: 'danger' and 'warning' were also being passed to a toast that only styles ok/error/info/warn. Fixed at the source, so no call site can lose its colour.

Review on Linux before release (v3.17.71)

The work above was built on Windows. Before it shipped it was rebased onto main, run through every gate on Linux, driven in Chromium against a built binary, and read adversarially. On Linux the whole suite is green, including the integration suite under -race; the "63–64 failures" in the totals below were that Windows box, not the code. What the review found and fixed:

1. Burned Talk messages came back on reload for anyone chatting as a mailbox (every administrator). /os/talk/read resolved the reader as the session's default identity, so the ownership check refused every mark. Found only in the browser — the source-scan test passed with the bug in place. Now resolved by talkSelf(r, as) like the stream and send; see the ADR-0131 amendment.
2. Compose and Reply from a mailbox sent as postmaster@. The From select ignored ?user=, so an administrator answering in alice's mailbox answered from a different address. The mailbox being viewed is now the selected sender.
3. The list keyboard layer threw on every keypress on every console page: it sat after admin-os.js's closing line and called a helper that only exists inside it. Moving it in would have made n jump to the post editor from Mail and Talk, so n is now confined to post lists, as its own comment always said.
4. hx-confirm still used the native dialog — eleven prompts, including bulk mail delete. Answered once in the shell through vpConfirm.
5. A send held for Undo could vanish if the sender left during the countdown with an attachment: the Fetch spec caps a keepalive body at 64 KiB and Firefox and Safari enforce it. Past the cap the browser now also asks before leaving.
6. A full local recipient was reported as the sender's own full mailbox.
7. Tor-world Talk ack deleted by id alone; it now checks the reader is the recipient.
8. The header cache remembered a failed read, listing a message with no sender or subject until the file changed — never, for delivered mail.
9. Contact errors echo what was typed into value="…" — correct, and now proven escaped by a behaviour test rather than a source scan.
10. Thread grouping: a reply with no Message-Id of its own landed on its mid-thread parent instead of the root, and one branch of the keyer was dead code.

Several source-scan tests were replaced by behaviour tests (mailbox delete, bulk partial failure, contact errors, the settings page's admin gate), and every fix above was mutation-tested: each test was seen to fail on the bug it guards.

Also corrected: S-05 was already done (stable palette key, vpActions registry); S-10 is fixed (the console's theme is mirrored to the sign-in pages, and a failed save says so); S-11 is fixed (docs/ADMIN-UI.md rewritten against the live console); T-26 is fixed (ADR-0131 amendment).

Totals

56 new test functions across cmd/vayupress and internal/vayuos/{mail,vayutalk}, plus one extended engine test. Final gate: go build ./... and go vet clean; the touched-package suite reports 63–64 failures, matching the pre-work baseline exactly — zero regressions (the count moves by one only because two loopback-listener tests are flaky on this box).