diff --git a/docs/SIDEBAR.md b/docs/SIDEBAR.md index 82b0522..2a3d658 100644 --- a/docs/SIDEBAR.md +++ b/docs/SIDEBAR.md @@ -5,8 +5,7 @@ sidebar (#107) and the TUI sidebar (#108) describe a session the same way. Read this before changing either. Both clients implement exactly what is written here; if it needs to change, change it here first. -A card has **line 1** always and **line 2** only when line 2 has something to -say. +A card is always two lines: **line 1** and **line 2**. ## Line 1 — name + actions @@ -25,32 +24,32 @@ badge move off this row into line 2. ## Line 2 — meta line (adaptive) -Rendered only when at least one of these holds: +Line 2 always renders — never an empty placeholder row either, since its +unconditional fragments (see below) always have something to show. Its +*fragments* are adaptive: some show only when their trigger holds. The line +itself is not. -1. The session has been held in its current activity state longer than - **30 seconds** (`activity_since` from #102). A freshly-active session - stays one line. -2. Its worktree holds blocked work: `blocked_work` is `Some` and not clear - (`InTheWay::is_clear()`), rendered in `formatInTheWay`'s phrasing on web - and as `⚠ ` on the TUI. -3. It has exited: `status == Dead`. -4. An agent-reported state (#105) of `Error` is in force (see Precedence). - -Otherwise line 2 is absent — never an empty placeholder row. - -When present, line 2 reads left to right: +Line 2 reads left to right: ``` - [] [ | exited] [] + [] [] [ | exited] ``` +Its minimum content is therefore the dot and the command. + `` is a single filled glyph (`●` on both clients) carrying the activity -state's colour, and `` follows in the same colour. There is no state -word and no second badge: the dot exists so the state is still legible when a -row is dimmed or the terminal renders the duration in the default fg. The dot -and duration are unconditional parts of line 2; the bracketed fragments appear -only when their trigger holds. A payload that predates #102 (no usable -`activity_since`) contributes no duration — the dot still renders. +state's colour, and `` follows in the same colour when shown. There +is no state word and no second badge: the dot exists so the state is still +legible when a row is dimmed or the terminal renders the duration in the +default fg. The dot is an unconditional part of line 2; the bracketed +fragments appear only when their trigger holds. + +`` renders only once the session has been held in its current +activity state longer than **30 seconds** (`activity_since` from #102) — under +that threshold the duration is absent and the dot renders alone. A payload +that predates #102 (no usable `activity_since`) likewise contributes no +duration — the dot still renders. This rule now governs only the duration +fragment; it no longer decides whether line 2 exists. `` is an agent-reported string (#105) — e.g. why a session is in `Error`. It sits right after the duration, in the muted style, and shows only @@ -60,9 +59,11 @@ truncates with `…` ahead of the trailing fragments — a long detail never pushes ``, `exited`, or `` off the line, and neither client ever lets it wrap. -`` is optional and muted: the session's command line, shown only when -the rendered name came from `metadata.name` and differs from the command (the -web has always surfaced this; the TUI may omit it). +`` is unconditional and muted: the session's command line, shown on +every card in both clients — no omission in the TUI, no name-vs-command +comparison gating it. A session named by its command line then shows the same +string on both lines; that is accepted, the price of a row that never changes +height. ## Colour per activity state