J3vbandClaude Fable 5
1fe3df7962
* refactor(protocol): retire reserved voice_speakers and member_leave (S-15) Neither type was ever emitted by the server; B2-1 clears them from the schema before the epoch-1 wire fixtures are captured, so the frozen epoch does not carry two dead message types. Client: dropped the dead `ws.on(MEMBER_LEAVE)` / `ws.on(VOICE_SPEAKERS)` dispatcher handlers, the `MemberLeavePayload` type and both `ServerMessage` union members, and the tests that only exercised those WS paths. `removeMember` (member_ban) and `setSpeakers` (LiveKit ActiveSpeakers) stay live and keep their direct unit tests. * test(ws): capture the epoch-1 wire fixtures alpha.4 is the last client on the pre-epoch wire and B2-2 adds a protocol epoch to the auth handshake next, so record what epoch 1 actually looks like while it is still observable. TestEpoch1Fixtures drives eleven journeys through the ws package's in-process hub harness (full migrations, real hub, httptest WebSocket server) and compares each journey's per-connection frame sequence with a transcript under protocol/fixtures/epoch-1/: - fresh-connect, auth-failure, ping - chat-send-fanout, chat-edit-delete, reaction-add-remove - typing, mark-read, dm-send - resume-replay (last_seq + buffer-tier replay burst) - voice-join-e2ee-leave (join, both voice_state forms, announce and offer relay, leave) Volatile values are replaced by typed placeholders before both writing and comparison -- any key that is id/seq/last_seq, ends in _id (except channel_id and role_id) or _at, is timestamp/ts/last_seen, or contains token, becomes "<class:json-type>" so a field that changes type is still a diff, while everything else is compared verbatim. Regenerate with: go test ./ws -run TestEpoch1Fixtures -update Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(client): pin the epoch-1 auth frame contract Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(updater): pin the epoch-1 manifest and client-update shapes * test(ws): harden the epoch-1 fixtures against trailing frames and absent optionals Every journey now ends with the ping/pong barrier on each recorded connection, so a frame the server emits after the last read fails as `expected "pong", got "X"` instead of going unrecorded; auth-failure asserts the StatusPolicyViolation close instead, its socket being gone. alice carries a display name, avatar, about text, custom status, identity public key and an announce signature (bob carries none), so every optional field is frozen in its present form as well as its absent one — a rename or a retype of display_name or identity_public_key now moves a fixture. The typing journey focuses the channel on "a" before typing: without the subscription registerNow only makes for a focused client, its ping/pong proved nothing about excludeUserID. Comment fixes: the escaped placeholder form MarshalIndent would write, the real (headroom) reason for the raised read limit, a note that bare id and active_channel_id are normalised by design, and a .prettierignore line saying these fixtures are verified by the Go comparison, not by git diff. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(protocol): document the epoch-1 fixtures * docs(protocol): match the epoch-1 wire where the fixtures contradicted the doc - voice_state: note the unsequenced relay-to-joiner form (table row + section) - auth_error: correct the example message and list the real rejection messages - member_join/presence connect example: add the seq both frames actually carry - chat_message.user: document display_name - voice_join reply order: state that the joiner's own voice_state broadcast is not ordered against the other three frames * test(ws): freeze the null forms of auth_ok and member_join user fields buildAuthOK emits display_name/about/custom_status/avatar as always-present nulls, but only alice — who has all four set — ever authenticated on a recorded connection, so the fixtures froze those fields in their populated form alone. A rename, a retype or a dropped null would have moved nothing, on the very frame B2-2 edits. fresh-connect now records bob's handshake too, on a second connection: his auth_ok carries the four nulls, his member_join carries avatar null with display_name and identity_public_key omitted, and alice — idle by then, so her reads stay in hub order — records the same pair as an already-connected observer sees it. In voice-join-e2ee-leave bob answers alice's signed announce with a legacy unsigned one, which freezes the absent form of signature next to her present one. The auth frames the test writes now carry the correlation id the real client stamps on every frame (ws.ts send()); normalisation renders it <id:string>. expectClosed also asserts the close reason ("authentication failed"), not just code 1008 — HP-2 asks for both. Comment precision, no behaviour change: the barrier guarantee now states that pong may overtake a pending LOW-priority frame (writePump) and that no journey is affected because every barrier is sent on an idle connection; the ping-budget ceiling is six connections, not four; the typing journey cites handleChannelFocusV2 rather than registerNow as the subscribe site; resume-replay's b barrier explains why moving it past the resume would be a flake, not a fix; and the header notes that normalisation hides that chat_send_ok.id echoes the request id. The client contract test's cited range for ws.ts's send() call is 441-453, not 441-454. Regenerate with: go test ./ws -run TestEpoch1Fixtures -update Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(protocol): shape-not-value fixture rule, voice_max_video default, auth close code The fixture rule read "a fixture may only change with an epoch bump", which is false for the seeded values the transcripts record verbatim: role permission masks and colours, motd, server_name, voice_max_video, the voice_config preset. A migration that changes a default mask diffs fresh-connect.json, and the README told the author to revert a change that never touched the wire. Split the rule along shape versus value. A key set, a JSON type, a key appearing or disappearing, or per-connection frame order is a protocol change and earns fixtures/epoch-<n+1>/. A seeded default value is a seed change: regenerate in the same PR and read the diff frame by frame. Normalising those values is explicitly not the answer — a placeholder over a mask or over an enum such as voice_config.threshold_mode would hide the drift the fixtures exist to catch. Two wire facts corrected against the fixtures: - voice_max_video on an unconfigured channel is 25, not 0 (migration 004 is DEFAULT 25); the doc listed it among the zero values. - auth_error is followed by a close with code 1008 (policy violation) and reason "authentication failed" (serve.go:128), which the doc left as "closes the connection". Also: voice_speakers moves from discord-parity's "still dead" list to "came off the list" — it was retired earlier on this branch. And Kick says sessions are revoked and sockets drop on the next sweep, which is what ForceLogout does (moderation.go:236); it does not cut sockets. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(protocol): fixture rule covers enum vocabularies; header comment precision Re-check minors from the whole-branch review: a fixed-vocabulary value the client switches on is shape, not a seeded value; drop the false 'new default channel' clause (the seed asserts channel ids); the low-priority frame is presence_update, not connect presence. * docs(plans): record B2-1 evidence for HP-2 (PR #1435, fixture commit SHAs) * docs(protocol): additive changes stay within an epoch; bump only for what old clients cannot process Codex review on #1435: B2-2 keeps protocol_epoch = 1 while adding auth/ready/auth_error fields, which the previous wording would have called a break to revert. An epoch is a compatibility boundary, not a snapshot: additive keys regenerate in the same PR and are documented; removals, renames, retypes, dropped frames and reordering bump the epoch. The plan's B2-1 evidence records the refinement and hands B2-2/B2-4 the open questions (additive-tolerant replay of the epoch-1 transcript; epoch 0 vs 1 naming). * test(client): compare auth-frame key sets order-independently Codex review on #1435: Object.keys preserves insertion order, so a harmless property reorder in ws.ts would fail the pin. Key order has no wire meaning; the Go fixtures already compare with sorted keys. Sort both sides. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
22 KiB
OwnCord Client UX Specification (target state)
Verified against: commit 5630aa1, 2026-08-04
Companion: ../client.md (structural module map) · ../../audit-2026-08-04-docs-and-coverage.md
This directory specifies how the Tauri client should behave — what every UI
step does, and how each view reacts to server events, permission state, and
failure. Unlike client.md, which maps the code as-built, these
documents are prescriptive (to-be): they describe the intended target UX.
Where today's code diverges, each flow carries a ⚠ Current gap callout — so
this set doubles as a UX improvement backlog. Gaps are grounded in real
file:line references from the client.
Scope. This is a behavior spec, not a visual design spec. It defines states, transitions, events, and reactions — not pixel layout, spacing, or color. Those live in
src/styles/tokens.cssand the component CSS.
Documents
| Doc | Covers |
|---|---|
| connection-and-auth.md | App boot, server profiles, connect/health, login, TOTP, register-by-invite, the connected handshake, reconnect, and cert-TOFU trust prompts |
| messaging.md | Composer + send (optimistic), edit/delete, reactions, attachments, replies, pins, search, read/unread, slow-mode, announcement read-only gating |
| channels-members-dms.md | Channel list/switch/categories, member list + presence + typing, roles, DM open/close, blocking |
| voice-and-e2ee.md | Voice join/leave, mute/deafen/camera/screenshare, push-to-talk, active-speaker, and the E2EE securing/key-ready indicators |
| settings-and-admin.md | Settings tabs, profile/password/2FA/delete-account, appearance/theming, the inline admin surface (ban/kick/roles, channel CRUD, invites), and the updater |
The cross-cutting vocabulary and global reaction matrices below apply to every document; the per-flow docs reference them rather than repeating them.
1. View-state vocabulary
Every data-bearing view must be able to represent each of these states and must choose a defined presentation for each (a view may legitimately collapse some — e.g. a view that can never be empty — but that must be a decision, not an omission):
| State | Meaning | Default presentation |
|---|---|---|
loading |
A fetch/subscription is in flight and no cached data is shown yet | Skeleton or inline spinner in the view's own region — never a full-screen blocker except the initial connected handshake |
ready |
Data present and current | The normal view |
empty |
Fetch succeeded, zero items | A labelled empty state with a one-line "what goes here / what to do next" hint |
error |
Fetch/action failed | Inline error with a Retry affordance for recoverable errors; a toast only for fire-and-forget actions |
stale |
Data shown but known out of date (e.g. during reconnect) | The normal view plus a non-blocking status hint (connection banner); interactions that require a live socket are disabled with a reason |
permission-denied |
The user may see the view but not act | The view renders read-only; the disallowed control is disabled with a visible reason, never hidden silently and never enabled-then-rejected |
offline |
No live socket | Live-only controls disabled with the connection status surfaced |
Principle — no silent states. Every terminal outcome (success, empty, failure, denial) produces some observable feedback. A control that will be rejected by the server must be pre-disabled with a reason; an action that succeeds without a visible result must emit a confirmation.
2. Feedback primitives
The client has a fixed set of feedback surfaces. Each has one job; pick by the decision table, don't improvise.
| Primitive | Source | Use for | Do not use for |
|---|---|---|---|
Toast (info/success/error, 5 s auto-dismiss, max 5) |
lib/toast.ts → components/Toast.ts |
Transient results of an explicit user action (sent, copied, saved, "couldn't reach server") | Anything the user must act on; anything that must survive navigation |
| Inline field error | per-form | Validation and per-field server rejections (bad password, weak input) | Global/connection state |
| Inline section error + Retry | per-view | A failed load of a view's own data (messages, invites, pins) | One-shot actions (use a toast) |
| Persistent banner | components/ServerBanner.ts (reconnect/restart), ad-hoc cert banner |
Connection status: reconnecting, server-restart countdown, first-trust cert notice | Per-action results |
| Blocking modal | lib/modalFactory.ts (+ CertMismatchModal) |
Decisions that must be made before proceeding: cert mismatch, destructive confirm | Routine feedback; anything dismissable-by-ignoring |
| Two-click / inline confirm | AdminActions.ts withConfirmation, PendingDeleteManager |
Reversible-ish destructive actions in dense menus (kick, ban, delete channel, delete message) | Irreversible account-level actions (use a modal with typed confirm) |
| Disabled control + reason | per-control | Actions not currently permitted (offline, no permission, slow-mode cooldown, upload in flight) | Errors that already happened |
Transient-error store (ui.store.setTransientError) |
survives navigation | A message that must appear on the connect page after a forced disconnect (banned, kicked, restart) | In-session messaging (use a toast) |
3. Connection status is a first-class, observable state
Every live-only interaction keys off one connection status. Target: a single
source of truth in ui.store.connectionStatus
(connected | reconnecting | disconnected), written from the WS client's
onStateChange, and read by any control that needs a live socket.
✓ Implemented (2026-07).
ui.store.connectionStatusis now the single source of truth:main.tscallswireConnectionStatus(ws), whose writer lives inlib/dispatcher.ts(ws.onStateChange→toConnectionStatus→setConnectionStatus), mapping the internal 5-state machine onto the 3-state status (connecting/authenticatingread asreconnecting, since a reconnect cycle passes through them). Consumers subscribe to the store instead of wiring ad-hoc callbacks: the reconnect banner (MainPage, synced at mount and now also showing "Disconnected" instead of going stale), the composer gating (ChannelController, "Reconnecting…" / "Not connected" per the table), and the presence picker (UserBar— previously dead in production becauseSidebarAreanever passed it aws; it now gates on the store and receives thewssend path). The one-shot connected-overlay wiring inmain.tsstays onws.onStateChangedeliberately — it needs the exact internal transition. The voice column is now wired too: the VoiceWidget freezes its in-call controls (disabled + a "Reconnecting…" / "Not connected" reason) whileconnectionStatus !== "connected", and the join affordance itself — the voice-channel row in theChannelSidebar— takes the same disabled-with-reason state (.disabledclass,aria-disabled, a "Reconnecting…" / "Not connected" title) and its click becomes a no-op, so joining/leaving is visibly gated, not a silent dead click. The join/leave callbacks (VoiceCallbacks.ts) still refuse to firevoice_join/voice_leaveover a down socket as a defensive backstop. LiveKit's own reconnection keeps retrying underneath — only the UI is gated, never LiveKit's machinery.
| Status | Composer / send | Voice controls | Presence picker | Reconnect banner |
|---|---|---|---|---|
connected |
enabled | enabled | enabled | hidden |
reconnecting |
disabled, "Reconnecting…" | frozen, retrying underneath | disabled | visible, spinner |
disconnected |
disabled | torn down | disabled | visible or → connect page on fatal |
4. Global event → reaction map
The dispatcher (src/lib/dispatcher.ts) is the single fan-in from the socket to
the stores. Target: every inbound message type produces a defined store
mutation and, where user-visible, a defined UI reaction. The per-flow docs
detail each; this is the index.
| Inbound event | Store effect | Target UI reaction |
|---|---|---|
auth_ok |
auth.setAuth |
Advance handshake → ready overlay |
auth_error |
ui.setTransientError + auth.clearAuth |
Return to connect page with the reason shown |
ready |
bulk-load channels/roles/members/voice/dm | Render main view; resolve the connected overlay |
chat_message |
messages.addMessage (+ unread/DM/notify) |
Append; reconcile a pending optimistic row if it's our echo |
chat_send_ok |
messages.confirmSend |
Mark the optimistic row sent (see gap in messaging.md) |
chat_edited / chat_deleted |
messages.editMessage / deleteMessage |
In-place edit / tombstone |
chat_bulk_deleted |
messages.bulkDeleteMessages |
Remove every purged row in one pass |
reaction_update |
messages.updateReaction |
Toggle the pill + count, reflect me |
typing |
members.setTyping (5 s auto-clear) |
Typing indicator |
presence / member_update / user_update |
members.* |
Live member-list update |
member_join / member_ban |
members.add/remove |
Member-list add/remove |
channel_create / channel_update / channel_delete |
channels.* |
Sidebar update; redirect if the active channel was deleted |
roles_update |
channels.setRoles |
Refresh name colors + permission-gated affordances |
emoji_update |
emoji.setCustomEmoji |
Refresh picker, autocomplete, and rendered custom emoji |
voice_state / voice_leave / voice_config |
voice.* |
Voice roster (speaking rings come from LiveKit's ActiveSpeakers, not the wire) |
voice_moved / voice_disconnected |
voice.* + livekitSession |
Follow a mod move by rejoining the new channel / tear down after a mod kick with an error toast naming the reason |
voice_token / voice_e2ee_* |
livekitSession.* |
Drive the voice-join + securing indicators |
dm_channel_open / dm_channel_close |
dm.* |
DM list add/remove |
server_restart |
ui.setTransientError |
Restart banner with countdown |
error |
ui.setTransientError (+ clearAuth on BANNED) |
Map the code → the reaction in §5 |
call_incoming / call_declined are deliberately not routed through the
dispatcher: MainPage.ts subscribes to them directly (page-scoped listeners)
and drives the ring state machine in lib/call-ring.ts +
components/IncomingCallBanner.ts.
✓ Implemented (2026-07). Error codes are no longer silently dropped for sends: the server echoes the request id on error replies, so
SLOW_MODE,FORBIDDEN,RATE_LIMITED,BAD_REQUEST, etc. are mapped to the exact optimistic row that failed (retry offered), andchat_send_ok'smessage_id/timestampnow reconcile the pending row. See the optimistic lifecycle in messaging.md.
5. Error & permission reaction matrix
One canonical reaction per failure class, applied everywhere. Today error
handling is per-call-site with no shared mapper (doFetch() in lib/api.ts centralizes only
401); this matrix is the target contract.
| Class | Source | Target reaction |
|---|---|---|
| 401 Unauthorized | any REST call | Global: clearAuth() → disconnect → connect page, with "Your session expired — sign in again." (centralized in api.ts + main.ts; since 2026-07 uploadFile honors it too, and the connect page shows the session-expired reason) |
| 403 Forbidden (action) | REST/WS | Toast "You don't have permission to do that." and pre-disable the control so it can't be attempted again in that context |
| 403 Suspended/Banned | login REST / WS BANNED |
Transient-error store → connect page: "Your account has been suspended." Force logout, no reconnect |
| 429 Rate-limited | REST/WS RATE_LIMITED |
Non-destructive toast "You're doing that too fast — try again in a moment." Keep the user's input; re-enable the control after a short cooldown |
| Slow-mode | WS SLOW_MODE |
Disable send with a live countdown in the composer; do not drop the drafted message |
| Validation (400) | REST | Inline field error with the server message (capped to a safe length — the login form caps at 200 chars in the handleFormSubmit() catch block, pages/connect-page/LoginForm.ts; apply everywhere) |
| Conflict/Not-found (404/409) | REST/WS | Contextual inline message + refresh the affected view (the target moved/vanished) |
| 5xx / network | REST | Inline section error + Retry; for one-shot actions, a toast "Couldn't reach the server." Never a silent drop |
| Transport backpressure | WS ws_send "channel full" |
Mark the optimistic row failed with Retry (✓ since 2026-07: ws.onSendFailure → dispatcher → markSendFailed with NETWORK/OFFLINE; id-less sends like heartbeats stay silent) |
| Cert first-use | Rust cert-tofu: first_use |
Blocking trust modal (createCertFirstUseModal): the Rust proxy rejects the first connection rather than auto-pinning; Accept stores the pin and retries, Cancel leaves the server untrusted (already: the ws.onCertFirstUse(...) handler in main.ts) |
| Cert mismatch | Rust cert-tofu: mismatch |
Blocking CertMismatchModal; Accept re-pins + reconnects, Reject disconnects + returns to connect (already: the ws.onCertMismatch(...) handler in main.ts) |
6. Cross-cutting principles
- Optimistic where the user acts, authoritative where the server decides. Local actions (send, react, mute) reflect immediately with a pending marker, then reconcile against the server echo; on failure they roll back visibly with a retry — never silently.
- Permission is expressed as affordance, not as rejection. If the server will refuse, the client disables the control with a reason first. The announcement-channel composer is the canonical example (see messaging.md).
- Connection state gates live controls reactively (§3), not per-click.
- One reaction per failure class (§5), applied uniformly.
- No silent success and no silent failure (§1).
Maintenance rule
Same as the blueprint set: if a PR changes a client flow, event handler, or the
set of states a view must represent, it updates the corresponding UX doc in the
same change. These specs reference stable identifiers (event-type strings, store
action names, component names) over line numbers; the file:line anchors in the
gap callouts are point-in-time and dated by the header.