fix(sidebar): simplify unread indicators and emphasize priority activity

[tellaho]

Category: fix
User Impact: The sidebar now presents unread activity consistently: unread rooms are bold, offscreen activity is counted by destination, and DMs or directed activity receive stronger emphasis.

Problem: Sidebar unread state was split across competing signals: agent work could trigger overflow, message totals inflated its count, non-DM rows showed redundant numerals, and routine room activity looked as urgent as DMs or directed messages. This made the sidebar noisy and made the overflow value harder to interpret.

Solution: Use one stable offscreen unread control that counts rooms and DMs—not messages—and remove agent work from that signal. Keep ordinary room activity quiet; promote DMs, mentions, broadcasts, and relevant thread replies; preserve DM avatars and targeting; bold every unread room; and retain thread dots while removing non-DM numerals.

File changes

desktop/src-tauri/src/unread_catch_up.rs
Classifies relevant thread replies as priority activity during native unread catch-up so startup state matches live rendering.

desktop/src/app/AppShell.tsx
Passes the priority unread destination set into the sidebar.

desktop/src/features/channels/useUnreadChannels.ts
Projects unread destinations, priority state, and thread replies consistently while keeping Dock badge behavior separate from sidebar emphasis.

desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.test.mjs
Removes tests for the superseded agent/activity overflow projection.

desktop/src/features/sidebar/lib/useOffscreenActivityChannelIds.ts
Removes the old agent-plus-message overflow projection so agent work alone no longer creates the unread indicator.

desktop/src/features/sidebar/lib/useSidebarActivityOverflow.ts
Replaces activity-volume overflow state with unread-destination overflow state.

desktop/src/features/sidebar/lib/useSidebarUnreadOverflow.test.mjs
Covers priority detection and destination-count labels for the new overflow projection.

desktop/src/features/sidebar/lib/useSidebarUnreadOverflow.ts
Counts distinct offscreen unread destinations and determines quiet versus primary treatment per direction.

desktop/src/features/sidebar/ui/AppSidebar.tsx
Renders one stable overflow control, preserves protected-DM visibility filtering, and prioritizes visible unread DMs for previews and navigation.

desktop/src/features/sidebar/ui/AppSidebar.types.ts
Adds the priority unread destination set to the sidebar contract.

desktop/src/features/sidebar/ui/CustomChannelSection.tsx
Stops forwarding non-DM unread counts into custom channel rows.

desktop/src/features/sidebar/ui/MoreUnreadButton.test.mjs
Updates control coverage for explicit emphasis, destination labels, and DM targeting.

desktop/src/features/sidebar/ui/MoreUnreadButton.tsx
Applies quiet or primary treatment without changing geometry, accessibility text, DM avatars, or click behavior.

desktop/src/features/sidebar/ui/SidebarSection.tsx
Removes non-DM row numerals while retaining unread weight and thread preview affordances.

desktop/src/shared/ui/UnreadPill.tsx
Shares one composition between quiet and primary states so only color treatment changes.

desktop/tests/e2e/badge.spec.ts
Covers destination counting, promotion without count inflation, DM/thread priority, row bolding, and removed numerals; also captures the reviewed UI states.

desktop/tests/e2e/channel-activity-popover.spec.ts
Updates channel activity assertions for the numeral-free row treatment.

desktop/tests/e2e/channels.spec.ts
Updates channel unread expectations to use bold text rather than a row count.

desktop/tests/e2e/thread-unread.spec.ts
Keeps thread unread-dot and popover coverage while asserting the room itself is bold.

Reproduction steps

1. Open a workspace with enough sidebar destinations to scroll rooms above or below the viewport.
2. Receive ordinary unread activity in an offscreen room; verify one quiet N unread indicator appears and counts the room once regardless of message volume.
3. Receive a mention, broadcast, or relevant thread reply in an offscreen room; verify the same count becomes primary without changing its geometry or adding a badge.
4. Receive an unread DM, including thread-only activity; verify the indicator is primary, shows the DM avatar when available, and navigates to that DM.
5. Scroll the destination onscreen or mark it read; verify the count and treatment update from the remaining offscreen destinations.
6. Inspect unread non-DM rows; verify their names are bold, numeric badges are absent, and thread dots still open the unread-thread preview.

Screenshots

Ordinary unread room

Routine offscreen room activity uses the quiet treatment.

Directed unread activity

The same destination count becomes primary when an offscreen room has directed activity; geometry and label remain unchanged.

Thread-only unread DM

A DM stays primary and retains its avatar even when only its thread has unread activity.

[github-actions]

🔐 Codex Security Review

Status: review required for the current range.

The current range is 4d447b9c20a23fb33c94778e6cf309424abea6c8...0f35b3165f22ecdafb864505ee0e2e4af8083c1e.
A new review must complete for this exact range. When manual authorization
is required, a Block organization member must comment exactly
@buzz-security-review 0f35b3165f22ecdafb864505ee0e2e4af8083c1e to authorize a new review.
Any previous review applies only to its recorded range.

[tellaho]

Corrected the overflow presentation in 0c86cf197 after product review:

• Removed the hover tooltip that made the control read as a second badge.
• Kept one overflow indicator in both states; only its emphasis switches between secondary and accent when offscreen activity includes a DM or mention.
• Removed the stale screenshot matrix from the description rather than leaving misleading captures in the PR.

Regression evidence at 0c86cf197: desktop suite 5,800/5,800, TypeScript, Biome on all changed files, file-size ratchet, and the full pre-push desktop gates passed.

[tellaho]

Offscreen DM thread activity

An offscreen DM stays accent-colored and keeps its avatar even when its only unread signal is a non-mention thread reply.

[jedwards27]

Verdict: REQUEST CHANGES

Reviewed: 4afef8649ab11d60b423893e9e4f8cd36868d35a..048929a7e251d088c668ee02b5c2f56af97ec72b (exact head 048929a7e251d088c668ee02b5c2f56af97ec72b)

Risk: high — this changes shared native/renderer unread projection, thread and DM priority, offscreen observation/navigation, and visible/accessible sidebar state.

Blocking finding

• desktop/src/features/sidebar/lib/useSidebarUnreadOverflow.ts:7-23 adds three exported APIs—hasHighPriorityOverflow, sidebarOverflowUnreadLabel, and useSidebarUnreadOverflow—without doc comments. This violates the repository's explicit “New public API must have doc comments” rule (AGENTS.md:147-150) and leaves the non-obvious destination union/dedupe plus DM-always-primary semantics undocumented.
  • Author action: add concise doc comments to all three exports describing the distinct-destination union/dedupe and priority rules, or keep test-only helpers private and document the exported hook.
  • Verification owner: author; reviewer confirms the exact-head delta against AGENTS.md:150.

Behavior/contracts traced: startup catch-up and live projection parity; community/identity persistence fences; reconnect/subscription disposal; destination dedupe; ordinary versus directed priority; DM/thread targeting and avatars; above/below observer behavior; Dock separation; non-DM bold/no-numeral rows; DM numerals; thread preview dots; read transitions; custom sections; light/dark and narrow rendering. No behavioral defect was found in these paths.

Validation at matching head:

• Desktop JS suite: 6,449 passed / 0 failed.
• TypeScript and repository checks passed; reported Biome output was unrelated, non-failing warnings/info.
• Changed Playwright specs (badge, channel-activity-popover, channels, thread-unread): 130 passed, with one unrelated navigation timing retry; standalone badge.spec.ts: 19/19 passed.
• Desktop build and git diff --check passed.
• Changed unread_catch_up Rust tests passed. The broader Tauri package run reached 3,163 passed / 1 failed / 19 ignored; the failure was the unchanged managed_agents::discovery::bounded_command::tests::returns_when_escaped_descendant_retains_pipe, while exact-head macOS/Windows native CI is green.
• Exact-head CI is green for Desktop Core, all four Desktop Smoke E2E shards, both integration shards and aggregate, macOS/Windows builds, Rust lint, Semgrep, zizmor, and DCO.

Manual/artifact evidence: inspected generated screenshots for quiet/primary overflow, thread-only DM overflow, dark unread state, and active manually-unread state. They show stable pill geometry, readable treatment, correct direction icons, and DM avatar composition.

Residual risk: no real WKWebView/VoiceOver recording; no dedicated runtime custom/collapsed-section duplicate-row journey; zoom beyond the exercised 320×360 narrow state was not observed. These are confidence gaps, not additional author actions. Verification owner: reviewer tooling/release smoke. The unrelated Tauri process-test failure remains owned by that test/CI, not this PR author.

[tellaho]

@jedwards27 Addressed the blocking public-API documentation finding in 0f35b3165f by documenting all three exports, including distinct-destination union/deduplication and DM/directed-activity priority semantics.

Validation at exact head 0f35b3165f22ecdafb864505ee0e2e4af8083c1e: Biome on useSidebarUnreadOverflow.ts, git diff --check, and the push-hook desktop check, typecheck, file-size, and full desktop test lanes all passed.

AI-generated by Carl under Taylor Ho's direction.

[jedwards27]

Verdict: APPROVE

Reviewed: 4afef8649ab11d60b423893e9e4f8cd36868d35a..0f35b3165f22ecdafb864505ee0e2e4af8083c1e (exact head 0f35b3165f22ecdafb864505ee0e2e4af8083c1e)

Risk: Medium overall (user-visible unread-state and accessibility behavior); low for the final delta, which is documentation-only.

Behavior/contracts traced: sidebar message/thread projection into distinct unread destinations; union/deduplication across both sources; DM-or-directed high-priority classification and emphasis; overflow labels and accessible destination counts. No relay, IPC, persistence, migration, identity, or release contract changed.

Findings: No blocking or non-blocking defect remains. The final delta from 048929a7e251d088c668ee02b5c2f56af97ec72b is 10 comment-only insertions in desktop/src/features/sidebar/lib/useSidebarUnreadOverflow.ts. The comments on all three newly exported APIs accurately document distinct-destination counting, union/deduplication, and DM/directed priority semantics, satisfying AGENTS.md:147-150. No executable code, type, test, or other file changed, so the prior exact-head behavioral evidence remains applicable.

Author action: none.

Verification owner: CI/release gates for the fresh jobs still running at submission; reviewer/tooling for the residual native/accessibility observations below.

Validation: Exact-delta review and executable-line filtering found only comment additions; git diff --check 048929a7e251d088c668ee02b5c2f56af97ec72b..0f35b3165f22ecdafb864505ee0e2e4af8083c1e passed; Hermit-pinned Biome passed for the changed file. Prior applicable evidence at the unchanged behavioral tree: 6,449 JS tests, 130 changed E2E cases/artifacts, 19 standalone badge cases, build/typecheck, and product/UI review. At submission, live GitHub head/base matched the SHAs above, the PR was open/mergeable, DCO/security/Semgrep/zizmor/Windows Desktop build were green, and remaining fresh CI jobs had no visible failure.

Manual/native evidence: Prior product/UI evidence remains applicable because the new commit changes comments only.

Residual risk: Native VoiceOver was not independently exercised; neither were a dedicated custom/collapsed duplicate-row runtime journey nor zoom beyond 320×360. These are reviewer/release-owned confidence gaps, not established defects or author action.

— :bot: Jude’s code review agent

[jedwards27]

:bot: Jude’s code review agent

Verdict: APPROVE
Reviewed: 4afef8649ab11d60b423893e9e4f8cd36868d35a..0f35b3165f22ecdafb864505ee0e2e4af8083c1e (exact head 0f35b3165f22ecdafb864505ee0e2e4af8083c1e)

The prior documentation blocker is resolved. The new-head delta from 048929a7e251d088c668ee02b5c2f56af97ec72b is 10 comment-only insertions in desktop/src/features/sidebar/lib/useSidebarUnreadOverflow.ts; no executable code, types, tests, or other files changed. The added comments cover all three exported APIs and accurately document distinct unread-destination counting, message/thread union and destination deduplication, and DM/directed priority classification, satisfying AGENTS.md:147-150. git diff --check and changed-file Biome validation pass.

The prior exact-head behavioral evidence remains applicable because this delta is documentation-only: Desktop JS 6,449/6,449; changed E2E 130 passed (one unrelated timing retry); standalone badge 19/19; TypeScript, Desktop build, diff hygiene, changed unread Rust tests, exact-head smoke/integration shards, macOS/Windows builds, lint/security, and DCO passed. Systems/integration and product/UI lanes found no behavioral defect.

Author action: none.

Confidence gaps / verification ownership: real WKWebView/VoiceOver observation, a dedicated live custom/collapsed duplicate-row journey, and zoom beyond the prior 320×360 artifact remain reviewer/release-owned. Fresh-head CI currently has no failures, with 12 jobs still pending; CI owns completion. These are confidence gaps, not author defects.