fix(visuals): stop silently missing UI changes (chat flow, gap warning, param-route guard)

[crs48]

Why

Our Visual UI Capture system silently misses big UI changes. The trigger: PR #174 rewrote the entire chat layer (2,364 lines under apps/web/src/comms/) and its capture comment read "No visual differences detected in the changed UI." — the absence of change reported for one of the largest UI changes in the project.

Root cause (full write-up in exploration 0200): capture targets come from a hand-curated allowlist of param-free routes + co-located stories. Chat matched none — no story, no route glob, and it only renders at the parameterized /channel/$channelId route (needs an id + seed data, so the static-route capturer can't reach it). computeCaptureSet then fell back to capturing home, which diffs clean, so the comment said "no differences." A coverage gap was made indistinguishable from a no-op. The 0191 drift-guard that was meant to catch this explicitly skips $-routes, the exact place chat lives.

What this does

C — make misses loud (keystone). When changed UI files map to no story/route/flow, computeCaptureSet now records fallbackUsed + unmappedFiles (threaded capture-set → capture → diff → comment). The PR comment renders a > [!WARNING] listing the unmapped files instead of "No visual differences detected." This converts every future silent miss into an actionable nudge.

A — chat flow. A new interaction flow seeds a channel, posts messages, reacts, and opens a thread — recording the redesigned /channel/$channelId surface. Maps apps/web/src/comms/**, so a chat-only PR like #174 now resolves to this flow.

B — close the drift-guard hole. manifest-coverage.test.mjs now requires every parameterized route to be flow-covered or listed in PARAM_EXEMPT with a reason (+ a stale-exempt guard). channel is covered by the chat flow; 8 others are exempted as explicit TODOs.

D — chat primitive stories. PresenceDot + ReactionBar stories give the pipeline a stable, seed-free baseline captured by the co-location rule. (MessageRow is router/hook-coupled — not a stable isolated story; deferred.)

Verification

• Fix proven against the real manifest: PR feat(web): polished chat & channels UI (0198) #174's 19-file diff now yields { flows: ['chat'], fallbackUsed: false } — maps to the chat flow, not the silent home fallback.
• Gap warning end-to-end: an unmapped file yields fallbackUsed: true and comment.mjs renders the [!WARNING] block listing it.
• Guard bites: with the chat flow removed, the guard reports channel.$channelId uncovered (would go red).
• pnpm test:visuals green (27 tests); xnet-web typecheck clean; eslint + prettier clean; Storybook builds and indexes all 4 new comms stories.
• The visual-capture workflow on this PR (it touches apps/web/src/comms/**) will run the new chat flow and post the GIF — the live validation of Option A.

🤖 Generated with Claude Code

[github-actions]

✓ Changelog fragment found — thanks!

[github-actions]

🖼️ UI changes in this PR

Components

🆕 Web/Comms/PresenceDot — Active

🆕 Web/Comms/PresenceDot — All Statuses

🆕 Web/Comms/ReactionBar — Default

🆕 Web/Comms/ReactionBar — Single Reaction

Interactions

🎬 Open a channel and post a message

▶ Watch MP4

_{Auto-captured by CI · run. Informational — not a blocking check.}

[github-actions]

Preview removed for PR #185.