fix: show macOS Dock badges for unread messages

[cj-vana]

When Mesh Client has unread messages, macOS can show the in-app count without a Dock badge because setting the badge does not initialize notification authorization. This change initializes Electron's native macOS notification support before setting a nonzero unread badge, restores the latest count when the window regains focus, and clears it when all messages are read.

Windows retains its red taskbar overlay and Linux retains launcher counts where supported. Native badge updates are independent of tray updates, and the existing restart-nudge badge keeps its priority. macOS still honors the user's notification and badge settings; troubleshooting now explains where to enable them.

The Electron test launcher now explicitly loads the built Mesh Client renderer so an unrelated development server on port 5173 cannot replace the app under test.

Validation:

• pnpm run build
• pnpm run check:pr
• pnpm exec playwright test e2e/unread-badge.spec.ts on macOS: actual preload IPC sets the Dock count, focus restores it, and zero clears it.
• Unit coverage for macOS, Windows, and Linux badge dispatch and combined unread counts across protocols.

The native macOS test checks Electron's Dock badge state. Windows/Linux native visuals and a packaged app's first-time macOS permission prompt were not exercised locally.

Summary by CodeRabbit

• New Features

  • Unread message counts now appear on supported macOS Dock, Windows taskbar, and Linux launcher icons.
  • Badges update when unread messages change and are restored when the app regains focus.
  • Added troubleshooting guidance for configuring app-icon badges.

• Bug Fixes

  • Improved badge behavior when notification permissions or platform-specific badge support affect visibility.

• Tests

  • Added coverage for badge updates across supported desktop platforms.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: QUIET

Plan: Advanced

Run ID: c17ab05f-fdae-4783-b8ed-e31b7316c552

📥 Commits

Reviewing files that changed from the base of the PR and between faa6b9e and f5f1ebe.

📒 Files selected for processing (1)

• docs/troubleshooting.md

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The change centralizes unread-count badge updates, applies badges on count changes and window focus, adds platform-specific tests, and documents macOS, Windows, and Linux badge behavior.

Changes

Unread app badge synchronization

Layer / File(s)	Summary
Platform badge update contract src/main/unreadAppBadge.ts, src/main/unreadAppBadge.test.ts	Adds a shared host interface and platform-specific badge updates for macOS, Linux, and Windows. Tests cover authorization, clearing, reapplication, and suppression behavior.
Main-process badge wiring src/main/index.ts, src/main/index.contract.test.ts	Refreshes the native badge after unread-count updates and window focus. The integration preserves platform callbacks and logs update failures.
Cross-platform validation and troubleshooting src/renderer/hooks/*, e2e/*, docs/troubleshooting.md	Tests combined unread counts and macOS Dock behavior. End-to-end tests load the built renderer and verify badge restoration and clearing. Documentation describes platform-specific badge requirements.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to f5f1e

Unread-message counts now synchronize to native app badges across supported desktop platforms, including clearing and focus restoration. The covered behavior presents no remaining actionable merge risk.

Sequence Diagram(s)

sequenceDiagram
  participant Renderer as useAppTrayUnreadSync
  participant IPC as setTrayUnread IPC
  participant Main as refreshUnreadAppBadge
  participant Native as Native badge API
  Renderer->>IPC: Send combined unread count
  IPC->>Main: Update lastTrayUnreadCount
  Main->>Native: Apply or clear platform badge
  Native-->>Main: Complete badge update
  Main->>Native: Reapply badge on window focus

Loading

Suggested reviewers: rinchen

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 8 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main macOS Dock badge fix. It does not mention the related Windows, Linux, testing, or documentation changes, but the title does not need to cover every change.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 8 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/unread-app-badge

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}