refactor(fe): trim >30-line comment blocks (second pass, #2077)

docs/web-ui/shape.md

@@ -88,14 +88,31 @@ SSE replay. Pages register a `kind → renderer` map; unknown kinds
 fall through to a JSON-dump note row. The factory ships three row
 shapes the renderers call:
 
-- `api.row(cls, text)` — single-line row with an inline `linkify`
-  pass over the text.
-- `api.details(cls, summary, body)` — collapsible `<details>` with
+- `api.row(cls, text, icon?)` — single-line row with an inline `linkify`
+  pass over the text; optional `icon` lands in a fixed-width `.row-glyph`
+  cell so glyphs of varying rendered width all align.
+- `api.details(cls, summary, body, icon?)` — collapsible `<details>` with
   a `<pre>` body (used by long tool-results and stack traces).
-- `api.detailsDiff(cls, summary, body)` — same shape, splits the
+- `api.detailsDiff(cls, summary, body, icon?)` — same shape, splits the
   body on newlines and tags each line as `diff-add` / `diff-del` /
   `diff-ctx` so the renderer's diff bodies get coloured without
   emitting raw HTML.
+- `api.placeholder(text)` — replaces the log with a single muted row,
+  cleared automatically when the next real row arrives.
+- `api.fromHistory` — `true` while backfill replay is running; renderers
+  use it to suppress live-only side effects.
+
+**`create(opts)` options:** `logEl` (log container element), `streamUrl`
+(SSE endpoint), `historyUrl?` (optional replay endpoint — skipped if absent
+or if the fetch fails), `renderers` (kind→fn map; unknown kinds fall through
+to `renderers._default`, itself defaulting to a JSON-dump note row),
+`onLiveEvent?(ev)` (live-only side effects), `onAnyEvent?(ev, {fromHistory})`
+(runs for both replay and live — use for derived views that need the full
+event picture), `onBackfillDone?(count)` (one-shot after replay; `count=0` on
+failed/skipped fetch), `onStreamOpen?()` (fires on every EventSource
+(re)connect — use to re-sync snapshot-derived state after a reconnect gap),
+`pillAnchor?` (parent element for the "↓ N new" pill; defaults to
+`logEl.parentElement`).
 
 **Sticky-bottom + snap animation.** `stickToBottom` is the
 operator's intent: true means "keep snapping to bottom on every