Files
kandev/docs/specs/ui/ws-connectivity-warning.md
T
2026-07-31 14:23:16 +01:00

118 lines
6.9 KiB
Markdown

---
status: approved
created: 2026-07-30
owner: kandev
---
# WebSocket Connectivity Warning
## Why
Kandev can look current while its live WebSocket updates are delayed or unavailable. Users need a
quiet but unavoidable indication that task, session, and workspace state may be stale, without
showing permanent healthy-state chrome or flashing for harmless reconnects.
## What
- Kandev derives one transient connectivity severity from the continuous time since its canonical
application WebSocket last entered `connected`:
- **Healthy/grace:** no warning before 3 seconds offline.
- **Unstable:** yellow from 3 seconds offline until 10 seconds offline.
- **Lost:** red from 10 seconds offline until the connection recovers.
- Transitions among `connecting`, `reconnecting`, `disconnected`, and `error` belong to the same
continuous offline interval. They do not restart either threshold.
- Any `connected` transition clears the warning immediately. A later disconnect starts a new grace
interval.
- The yellow detail reads **Connection unstable. Reconnecting to Kandev.**
- The red detail reads **Connection lost for at least 10 seconds. Live updates may be stale.**
- Color is never the only signal. The active surface exposes the matching detail as an accessible
status name and through hover/focus on fine-pointer layouts or tap on phone.
- Desktop and tablet show exactly one warning:
- When **App status bar** is enabled, its built-in connection item is problem-only: absent while
healthy or in grace, yellow while unstable, and red while lost.
- When **App status bar** is disabled, a problem-only connection indicator appears in the persistent
app-sidebar footer beside the theme control. The fallback is absent while healthy or in grace.
- Phone uses its existing native Status paths rather than adding a persistent bar or overlay:
- Existing Status entry points receive yellow/red warning treatment.
- Route chrome that leads to a nested Status action, such as the Home or Settings menu, carries
the same warning treatment so the issue is visible before opening the menu.
- When **App status bar** is disabled, these paths appear only during an active warning and open a
connection-only Status drawer. Plugin contributions and metrics stay disabled.
- The warning does not alter reconnect attempts, WebSocket subscriptions, queued requests, or
last-known application data.
## State machine
| State | Entry | Visible result | Exit |
|---|---|---|---|
| `healthy` | WebSocket enters `connected` | No warning | First non-`connected` status |
| `grace` | A continuous offline interval starts | No warning | `connected`, or 3 seconds elapse |
| `unstable` | The same interval reaches 3 seconds | Yellow warning | `connected`, or 10 seconds elapse |
| `lost` | The same interval reaches 10 seconds | Red warning | `connected` |
The state is client-local and transient. A page reload starts a new connection attempt and grace
interval; no outage timestamp or warning history persists.
## Failure modes
- If the reconnect client exhausts its attempts, the warning remains red until a later
`connected` transition or page reload. It does not claim that retries are still running.
- If the optional App status surface is disabled, an active warning bypasses only its visibility
gate. It does not mount metrics, plugin status contributions, or a desktop/tablet status bar.
- If a responsive presentation changes during an outage, the current severity moves to the new
canonical surface without resetting its offline interval or rendering duplicate warnings.
- If the warning timer owner unmounts, it cancels pending thresholds and does not update stale
application state.
## Responsive and mobile contract
- Desktop outcome: one problem-only warning in the enabled bottom status bar or, when that bar is
disabled, beside the sidebar theme control.
- Phone entry points reuse the shipped Page/Office top-bar Status button, task bottom-nav Status
action, and Home/Settings menu paths. The persistent route control signals severity before the
nested Status action is opened.
- The existing App Status drawer is the nearest shipped mobile exemplar. It contributes the inset
bottom surface, fixed summary, one safe-area-aware internal scroll owner, 44 px rows, dismissal,
and focus return.
- A short connection explanation belongs in that temporary drawer; it does not justify a new route
or full-height surface.
- Connection timing and severity are shared across breakpoints. Mobile-specific code only chooses
presentation and touch entry points.
## Scenarios
- **GIVEN** a connected client, **WHEN** its WebSocket is offline for less than 3 seconds and
reconnects, **THEN** no connectivity warning appears.
- **GIVEN** a connected client, **WHEN** its WebSocket remains offline for 3 seconds, **THEN** one
yellow warning appears with **Connection unstable. Reconnecting to Kandev.**
- **GIVEN** the same outage, **WHEN** it reaches 10 seconds, **THEN** the existing warning becomes
red with **Connection lost for at least 10 seconds. Live updates may be stale.**
- **GIVEN** an unstable or lost warning, **WHEN** any reconnect attempt enters `connected`, **THEN**
the warning disappears immediately and a later outage receives a fresh grace interval.
- **GIVEN** reconnect attempts cycle through non-connected raw statuses, **WHEN** the continuous
outage crosses a threshold, **THEN** the threshold is measured from the original disconnect.
- **GIVEN** App status bar enabled on desktop or tablet, **WHEN** connection severity changes,
**THEN** only its built-in connection item reflects the warning and no sidebar fallback appears.
- **GIVEN** App status bar disabled on desktop or tablet, **WHEN** connection severity becomes
unstable or lost, **THEN** one warning indicator appears beside the sidebar theme control and exposes
the matching detail on hover and focus.
- **GIVEN** App status bar disabled on phone, **WHEN** connection severity becomes unstable or
lost, **THEN** persistent route chrome signals the issue and its Status path opens a
connection-only, touch-sized drawer without metrics or plugin contributions.
- **GIVEN** a phone warning, **WHEN** the user opens and dismisses Status, **THEN** the connection
detail is readable, the drawer stays within the viewport, and focus returns to the trigger.
- **GIVEN** an active warning, **WHEN** the viewport crosses between phone and wider layouts,
**THEN** the severity remains unchanged and exactly one canonical warning surface is visible.
## Out of scope
- Latency, packet-loss, heartbeat-quality, or REST-health sampling.
- Changing reconnect delays, retry limits, queueing, resubscription, or missed-event recovery.
- Manual reconnect actions, recovery toasts, healthy-state success messages, outage history, or
persisted incident timestamps.
- A new phone bar, toast, route, full-screen alert, or desktop top-bar injection.
## Implementation plan
[WebSocket connectivity warning plan](../../plans/ws-connectivity-warning/plan.md)