headquarter/openspec/changes/archive/2026-06-12-completed-changes-archive/notification-center/apply-pr4.md

PR-4 Apply Report: Toast Coordination for Notification Center

Status: COMPLETE

All 4 tasks for PR-4 (NC-PR4-001 through NC-PR4-004) have been implemented, tested, and validated.

What Was Implemented

NC-PR4-001: Update EventToastBridge with Preference Checks

File: apps/web/src/components/event-toast-bridge.tsx

• Reads userConfig.notification_toast_level and userConfig.notification_mute_categories
• Preference hierarchy applied before showing toast:
  1. Muted category → suppress
  2. Toast level "none" → suppress all
  3. Toast level "errors" + severity != "error" → suppress
  4. Otherwise → show toast
• Gracefully handles missing/null userConfig (defaults to "all", no muted categories)

NC-PR4-002: Extend toast-rules.ts with Category/Severity Mapping

File: apps/web/src/components/toast-rules.ts

• Added mapEventToCategory(event) — maps event types to categories:
  • instance.* → "instance"
  • health.* → "health"
  • default → "system"
• Added mapEventToSeverity(event) — maps event types to severity:
  • instance.error → "error"
  • health.error → "error"
  • health.unhealthy → "warning"
  • health.recovered → "success"
  • others → "info"
• Added shouldShowToast(event, config) — combines mapping with preference checks

NC-PR4-003: Notification Preference Controls in Settings Page

File: apps/web/src/pages/settings.tsx

• Added "Notification Preferences" section with:
  • Toast level dropdown: "All notifications" / "Errors only" / "None"
  • Mute categories checkboxes: "Instance events" / "Health events" / "System events"
• Preferences loaded from UserConfig API
• Changes saved via PATCH /user-config
• Visual feedback on save

File: apps/web/src/api/settings.ts

• Extended settings API types with notification preference fields
• Added notification_toast_level and notification_mute_categories to request/response types

NC-PR4-004: Toast Bridge Tests

File: apps/web/src/components/event-toast-bridge.test.tsx (new)

• 6 tests covering:
  • Shows toast when level="all" and category not muted
  • Suppresses toast when level="none"
  • Suppresses info toast when level="errors"
  • Shows error toast when level="errors"
  • Suppresses toast when category is muted
  • Defaults to showing toast when no config present

File: apps/web/src/components/toast-rules.test.ts (modified)

• Extended existing tests with category/severity mapping tests
• Added preference filtering tests

Changed Files

1. apps/web/src/components/event-toast-bridge.tsx — Preference checks before toast
2. apps/web/src/components/toast-rules.ts — Category/severity mapping
3. apps/web/src/components/toast-rules.test.ts — Extended tests
4. apps/web/src/pages/settings.tsx — Notification preferences UI
5. apps/web/src/api/settings.ts — API types for preferences
6. apps/web/src/components/event-toast-bridge.test.tsx (new) — Bridge tests

TDD Cycle Evidence

Cycle	Task	RED	GREEN	Evidence
1	toast-rules mapping	Tests written against missing functions	Implemented mapEventToCategory, mapEventToSeverity	Tests pass
2	EventToastBridge preferences	Tests written against missing config checks	Added preference checks to bridge	Tests pass
3	Settings UI	Manual verification	Added preference section to settings page	Functional
4	REFACTOR	—	tsc + eslint clean	All pass

Test Commands & Exit Codes

# Toast rules + bridge tests (17 tests)
cd apps/web && npx vitest run src/components/toast-rules.test.ts src/components/event-toast-bridge.test.tsx
# Exit: 0 — 17 passed

# Type check
cd apps/web && npx tsc --noEmit
# Exit: 0 — clean

# Lint
cd apps/web && npx eslint src/components/event-toast-bridge.tsx src/components/toast-rules.ts src/components/toast-rules.test.ts src/pages/settings.tsx src/components/event-toast-bridge.test.tsx src/api/settings.ts --ext ts,tsx --max-warnings 0
# Exit: 0 — clean

Surprises / Decisions

1. Settings page uses existing form patterns — Leveraged existing settings form infrastructure rather than creating a new preferences component.
2. Graceful config fallback — When userConfig is missing or lacks notification keys, defaults to showing all toasts (no muted categories).

Risks

• None: All changes are additive. Preference defaults are safe (show all toasts).