# Plan - WEBDISPLAY ## 이 파일을 읽는 구현 에이전트에게 이 task는 Chrome foreground 알림 Epic의 `display` Task를 완료하기 위한 구현 계획이다. `03+02_event_map`이 PASS되어 `complete.log`가 생긴 뒤 구현한다. 구현 후 반드시 active `CODE_REVIEW-local-G08.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운 뒤, active 파일을 그대로 두고 리뷰 준비를 보고한다. 사용자에게 직접 질문하지 말고, 선택지를 채팅으로 제시하지 말고, `request_user_input`을 호출하지 않는다. 사용자만 결정할 수 있는 차단이 생기면 `CODE_REVIEW-local-G08.md`의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 멈춘다. 구현 에이전트는 `USER_REVIEW.md`, `complete.log`, `*.log` archive를 만들지 않는다. ## 배경 Permission API와 foreground mapper가 준비되면 Web foreground payload를 browser notification으로 표시하고 click/open routing을 기존 Dart stream/callback 계약으로 연결할 수 있다. 이 작업은 browser interop, public method, click event bridge가 함께 필요하므로 바로 구현하지 않고 독립 계획으로 남긴다. ## 사용자 리뷰 요청 흐름 구현 중 차단은 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 직접 사용자 프롬프트는 금지되며, code-review가 요청 정당성을 검증하고 필요할 때만 `USER_REVIEW.md`를 작성한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백은 사용자 리뷰 요청이 아니다. ## Roadmap Targets - Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` - Task ids: - `display`: foreground payload를 browser notification으로 표시하고 click 이벤트를 `NotificationOpenedEvent`와 host navigation callback으로 변환한다. - Completion mode: check-on-pass ## 분석 결과 ### 읽은 파일 - `agent-roadmap/current.md` - `agent-roadmap/phase/messaging-runtime/PHASE.md` - `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` - `agent-test/local/rules.md` - `agent-test/local/messaging-flutter-smoke.md` - `agent-test/local/client-app-smoke.md` - `packages/messaging_flutter/pubspec.yaml` - `packages/messaging_flutter/lib/nexo_messaging.dart` - `packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart` - `packages/messaging_flutter/lib/src/nexo_messaging_web.dart` - `packages/messaging_flutter/lib/src/notification_opened_event.dart` - `packages/messaging_flutter/lib/src/push_notification_type.dart` - `packages/messaging_flutter/lib/src/web/browser_notification_interop.dart` - `packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart` - `packages/messaging_flutter/lib/src/web_notification_permission.dart` - `packages/messaging_flutter/test/nexo_messaging_test.dart` - `apps/flutter-test/lib/main.dart` - `apps/flutter-test/test/widget_test.dart` - `agent-task/archive/2026/06/m-flutter-web-notification/02+01_web_plugin_baseline/complete.log` ### 테스트 환경 규칙 - `test_env=local`. - 적용 profile: - `agent-test/local/messaging-flutter-smoke.md` - `agent-test/local/client-app-smoke.md`는 app host가 변경될 경우에만 적용한다. - 기본 적용 명령: - `cd packages/messaging_flutter && flutter pub get` - `cd packages/messaging_flutter && flutter test` - `cd packages/messaging_flutter && flutter analyze --no-fatal-infos` - `apps/flutter-test/**`를 수정하면 추가로 `cd apps/flutter-test && flutter pub get`, `cd apps/flutter-test && flutter test`, `cd apps/flutter-test && flutter analyze --no-fatal-infos`를 실행한다. ### 테스트 커버리지 공백 - 기존 tests는 native opened event routing을 검증하지만 browser Notification display/click을 검증하지 않는다. - 이 plan은 browser interop를 fake 가능한 boundary로 두고, display call과 click callback이 `handleNativeEvent()`로 이어지는지 Dart unit test로 검증해야 한다. - 실제 Chrome permission prompt와 OS notification tray 표시는 local unit test 대상이 아니다. ### 심볼 참조 - renamed/removed symbol: none. - 새 display API는 `NexoMessagingPlugin` public API와 web-only interop boundary를 함께 확인해야 한다. - `apps/flutter-test` host UI는 smoke Epic의 `test-host` Task가 별도라 기본 범위에서 제외한다. ### 분할 판단 - split decision policy를 평가했다. - shared task group: `m-flutter-web-notification`. - predecessor `02`는 `agent-task/archive/2026/06/m-flutter-web-notification/02+01_web_plugin_baseline/complete.log`로 충족됐다. - predecessor `03`은 `agent-task/m-flutter-web-notification/03+02_event_map/complete.log` 또는 archive의 matching complete.log가 생겨야 충족된다. - 이 task directory `04+02,03_display`는 `02` baseline과 `03` mapper에 의존한다. - display는 browser interop, public API, stream/callback routing을 포함하므로 `event-map`과 분리한다. ### 범위 결정 근거 - 포함: package public display method, browser Notification display/click interop, click -> existing opened routing bridge, focused tests. - 제외: Firebase `onMessage` subscription wiring, `apps/flutter-test` web UI scaffold, Full Web Push/service worker/VAPID, server/push-proxy changes. - 제외 이유: display Task는 foreground payload를 표시하고 click routing으로 변환하는 package contract까지이며, Firebase source wiring과 host smoke UI는 별도 Task다. ### 빌드 등급 - `local-G08`: browser interop와 public routing이 함께 바뀌지만 deterministic fake interop tests로 검증 가능하고 scope는 package 내부로 제한된다. ## 구현 체크리스트 - [ ] 구현 시작 전 predecessor `03+02_event_map` complete.log가 active 또는 archive 경로에 있는지 확인한다. - [ ] browser Notification 표시를 담당하는 web-only interop method를 추가하되 공용 Dart/API가 `package:web`를 직접 import하지 않게 유지한다. - [ ] `NexoMessagingPlugin`에 foreground web notification display public method를 추가하고 permission이 granted가 아니거나 unsupported면 표시하지 않는 결과를 반환한다. - [ ] display click event가 normalized payload를 `PushNotificationType.opened`/`userInteraction=true` map으로 변환해 기존 `handleNativeEvent()` routing을 재사용하게 한다. - [ ] fake interop/client 기반 unit test로 unsupported/permission denied/granted display/click routing을 검증한다. - [ ] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다. - [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. ## [WEBDISPLAY-1] Browser Foreground Display And Click Routing ### 문제 현재 [NexoMessagingPlugin](/config/workspace/nexo/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart:17)은 native event stream과 web permission API를 제공하지만, Web foreground payload를 browser notification으로 표시하는 public method가 없다. click/open routing도 `NotificationOpenedEvent`와 host navigation callback으로 이어지지 않는다. ### 해결 방법 구현자는 `03+02_event_map`의 mapper를 사용해 payload를 normalized map으로 만든 뒤, web-only display interop와 public plugin method를 연결한다. 권장 public method 예시: ```dart Future showWebForegroundNotification(Map payload) ``` 요구 사항: - unsupported 또는 permission not granted 상태에서는 browser notification을 만들지 않고 testable result를 반환한다. - granted 상태에서는 title/body/tag/data 등 최소 fields를 browser Notification API에 전달한다. - click callback은 normalized map을 opened event로 변환하고 기존 `handleNativeEvent()`를 호출한다. - Android/iOS/macOS common code는 `package:web`를 직접 import하지 않는다. ### 수정 파일 및 체크리스트 - [ ] `packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart` public method 추가 - [ ] `packages/messaging_flutter/lib/src/web/browser_notification_interop.dart` display/click boundary 추가 - [ ] `packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart` browser implementation 추가 - [ ] 필요 시 result/status value object 추가 및 `lib/nexo_messaging.dart` export - [ ] `packages/messaging_flutter/test/`에 fake 기반 unit tests 추가 - [ ] README의 Web foreground 상태를 display API에 맞게 갱신 ### 테스트 작성 - unsupported/non-granted 상태에서 display가 no-op result를 반환하는지 검증한다. - granted 상태에서 fake interop가 notification display call을 받는지 검증한다. - fake click callback이 기존 `onNotificationOpened`, `onNotification`, `onNavigateToChannel`/`onNavigateToThread` 경로로 이어지는지 검증한다. ### 중간 검증 ```sh cd packages/messaging_flutter && flutter test cd packages/messaging_flutter && flutter analyze --no-fatal-infos ``` 기대 결과: tests와 analyzer가 통과한다. ## 수정 파일 요약 | 파일 | 항목 | | --- | --- | | `packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart` | WEBDISPLAY-1 | | `packages/messaging_flutter/lib/src/web/browser_notification_interop.dart` | WEBDISPLAY-1 | | `packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart` | WEBDISPLAY-1 | | `packages/messaging_flutter/lib/src/web/**` | WEBDISPLAY-1 | | `packages/messaging_flutter/test/**` | WEBDISPLAY-1 | | `packages/messaging_flutter/README.md` | WEBDISPLAY-1 | ## 최종 검증 ```sh cd packages/messaging_flutter && flutter pub get cd packages/messaging_flutter && flutter test cd packages/messaging_flutter && flutter analyze --no-fatal-infos ``` 기대 결과: 세 명령 모두 exit code `0`. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.