feat(web): add opt-in PWA taskbar unread badge

[techotaku39]

Summary

• Add unread-session counting for installed Edge/Chrome PWAs through the App Badging API.
• Make the taskbar unread badge opt-in and disabled by default.
• Add a local toggle under Settings > Display > Session list.
• Keep selected-session read tracking visibility-aware so minimized PWAs retain unread activity.
• Clear the native app badge when the preference is disabled.
• Add unit, settings, Playwright, and documentation coverage.

Problem / Motivation

HAPI needs a taskbar signal for new session activity. Manual validation found two related issues.

First, Edge and Windows can render one logical App Badging API state as two overlapping visual layers. In the affected environment, one layer is offset toward the bottom-right and clipped by the taskbar boundary. Calling navigator.clearAppBadge() removes both layers together. HAPI has only one runtime App Badging API write path, and the Service Worker notification badge resource is unrelated to the taskbar App Badge. This is consistent with a host-level browser/OS rendering issue, similar in class to Chromium issue 324585422.

Second, when the PWA was minimized, a selected session could receive an SSE update and be marked as seen solely because its updatedAt changed, even though the document was hidden. This caused the system notification to appear while the unread badge remained absent. Unselected sessions correctly produced a badge, confirming that the counter and App Badging API path worked.

Selected sessions are now marked as read only while the document is visible. When the PWA becomes visible again, the current selected session is reconciled against its latest activity.

Because the host rendering can be visually undesirable, the badge is opt-in instead of enabled for all users by default.

User Impact

Users who want the native taskbar count can enable:

Settings > Display > Session list > Taskbar unread badge

The preference is local to the current browser/PWA profile. While the PWA is minimized, new activity in the selected session remains unread and can contribute to the badge count. When the PWA becomes visible again, the selected session is marked as read.

Disabling the setting clears the native badge and disables the badge-specific session query.

Risk / Rollback

• No dependency, API, database, or migration changes.
• Badge rendering remains controlled by the host browser and operating system.
• The feature is disabled by default.
• The setting is local and can be changed at any time.
• Rollback is limited to reverting this commit.

Validation

• bun run typecheck:web — passed.
• pwsh -NoProfile -File .\scripts\Invoke-HapiTaskPlaywright.ps1 -Name investigate-windows-taskbar-badge -Suite Root -TestArgs settings-responsive.spec.ts — 2 passed, including default-off behavior, opt-in behavior, and persistence after reload.
• bun run --cwd web test -- src/hooks/useDocumentVisibility.test.ts src/hooks/useSelectedSessionSeen.test.ts src/hooks/useAppBadge.test.ts src/hooks/useAppBadgePreference.test.ts src/lib/sessionLastSeen.test.ts src/lib/sessionAttention.test.ts — 45 passed.
• bun run build — passed.
• git diff --check origin/main...HEAD — passed.
• Deployed smoke check — Hub health, authentication, test machine, and Runner verified successfully.

Related Issues

None

AI Disclosure

OpenAI Codex (GPT-5.6) assisted with implementation, testing, and validation.

[github-actions]

Findings

• None.

Summary

Review mode: initial

No issues found in the added or modified lines. Residual risk remains around browser/OS-specific App Badging behavior and delivery while a Windows PWA is minimized; the unit tests mock the API, and the Playwright coverage verifies the opt-in setting rather than the native taskbar result.

Testing

Not run (automation). GitHub integration check passed; the main test check was pending at review time.

HAPI Bot