feat(messaging): Web 알림 전경 계약을 추가한다

Flutter Web foreground 알림 흐름을 이어가기 위해 permission API와 payload mapper를 패키지 내부 계약으로 고정한다.
2026-06-07 15:08:40 +09:00 · 2026-06-07 15:08:40 +09:00 · ea77708c4f
commit ea77708c4f
parent c67cb557a5
21 changed files with 1351 additions and 8 deletions
--- a/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md
+++ b/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md
@ -36,15 +36,15 @@

 Flutter Web을 패키지 지원 플랫폼으로 올릴 때 기존 Android-first 계약을 깨지 않도록 기준선을 만든다.

- [ ] [plugin-web] `nexo_messaging`에 Flutter Web plugin 등록과 web 전용 구현 파일을 추가한다.
- [ ] [api-options] 기존 `initialize()` 호출을 깨지 않는 옵션 모델을 추가하고, web notification permission/display 정책과 token prefix 경계를 문서화한다.
- [ ] [interop] browser `Notification` API 연동은 `package:web` 기반으로 작성하고, Android/iOS/macOS import와 분리한다.
+- [x] [plugin-web] `nexo_messaging`에 Flutter Web plugin 등록과 web 전용 구현 파일을 추가한다.
+- [x] [api-options] 기존 `initialize()` 호출을 깨지 않는 옵션 모델을 추가하고, web notification permission/display 정책과 token prefix 경계를 문서화한다.
+- [x] [interop] browser `Notification` API 연동은 `package:web` 기반으로 작성하고, Android/iOS/macOS import와 분리한다.

 ### Epic: [foreground] Chrome foreground 알림

 웹앱이 열려 있는 상태에서 Chrome browser notification을 패키지 책임으로 표시하고 routing event를 재사용한다.

- [ ] [permission] Web notification 지원 여부와 permission 상태를 조회/요청하는 API를 제공한다.
+- [x] [permission] Web notification 지원 여부와 permission 상태를 조회/요청하는 API를 제공한다.
 - [ ] [display] foreground payload를 browser notification으로 표시하고 click 이벤트를 `NotificationOpenedEvent`와 host navigation callback으로 변환한다.
 - [ ] [event-map] Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다.

--- a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log
+++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log
@ -0,0 +1,182 @@
+<!-- task=m-flutter-web-notification/03+02_event_map plan=0 tag=EVENTMAP -->
+
+# Code Review Reference - EVENTMAP
+
+> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
+> The task is NOT complete until every implementation-owned section below is filled in.
+> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
+> Fill implementation-owned sections, then stop with active files in place and report ready for review.
+> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
+> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record the needed decision in `사용자 리뷰 요청` and stop for code-review.
+> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
+
+## 개요
+
+date=2026-06-07
+task=m-flutter-web-notification/03+02_event_map, plan=0, tag=EVENTMAP
+
+## Roadmap Targets
+
+- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md`
+- Task ids:
+  - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다.
+- Completion mode: check-on-pass
+
+## 이 파일을 읽는 리뷰 에이전트에게
+
+> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
+
+각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
+
+## 구현 항목별 완료 여부
+
+| 항목 | 완료 여부 |
+|------|---------|
+| [EVENTMAP-1] Foreground Payload Mapper | [x] |
+
+## 구현 체크리스트
+
+- [x] `packages/messaging_flutter/lib/src/web/` 아래에 foreground payload mapper를 추가하고 공용 Dart/API가 `package:web`를 직접 import하지 않게 유지한다.
+- [x] mapper가 host-injected `Map<String, dynamic>` payload를 기존 `PushNotificationType.message` map으로 정규화하도록 구현한다.
+- [x] mapper가 `RemoteMessage` data map에 준하는 입력과 CRT/thread/channel fields를 보존하고 `userInteraction` 기본값을 `false`로 둔다.
+- [x] mapper 단위 테스트를 추가해 message type 기본값, opened routing field 보존, explicit type/userInteraction override를 검증한다.
+- [x] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다.
+- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+
+## 코드리뷰 전용 체크리스트
+
+> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
+
+- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
+- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
+- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G07_0.log`로 아카이브한다.
+- [x] active `PLAN-*-G??.md`를 `plan_local_G07_0.log`로 아카이브한다.
+- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
+- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
+- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-web-notification/03+02_event_map/`로 이동한다.
+- [ ] PASS이고 task group이 `m-flutter-web-notification`이면 런타임 완료 이벤트 메타데이터를 보고한다.
+- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G08.md`와 `CODE_REVIEW-local-G08.md`를 작성하고 `complete.log`를 작성하지 않는다.
+
+## 계획 대비 변경 사항
+
+없음. 계획 명세를 그대로 따랐다.
+
+## 주요 설계 결정
+
+- mapper 파일을 `lib/src/web/foreground_message_mapper.dart`로 추가했다. `lib/src/web/` 디렉터리에 두되 `import 'package:web'`, Firebase, browser Notification을 import하지 않아 VM 분석기에서도 문제없이 컴파일된다.
+- 테스트에서 `package:nexo_messaging/src/web/foreground_message_mapper.dart`를 직접 import해 mapper 함수를 단위 테스트로 검증한다. 이 함수는 공개 API가 아닌 내부 헬퍼이므로 `lib/nexo_messaging.dart`로 re-export하지 않았다.
+- null routing field는 결과 map에 포함하지 않아 `NotificationOpenedEvent.fromMap`이 null 기본값을 그대로 적용하게 했다.
+
+## 사용자 리뷰 요청
+
+_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
+
+- 상태: 없음
+- 사유 유형: 없음
+- 결정 필요: 없음
+- 차단 근거: 없음
+- 실행한 검증/명령: 없음
+- 자동 후속 불가 이유: 없음
+- 재개 조건: 없음
+
+## 리뷰어를 위한 체크포인트
+
+- mapper가 `package:web`와 Firebase runtime을 직접 import하지 않는지 확인한다.
+- normalized map이 기존 `PushNotificationType`과 `NotificationOpenedEvent.fromMap` 계약을 깨지 않는지 확인한다.
+- display/click routing 구현이 이 task에 섞이지 않았는지 확인한다.
+
+## 검증 결과
+
+### EVENTMAP-1 중간 검증
+
+```text
+$ cd packages/messaging_flutter && flutter test
+00:00 +22: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message
+00:00 +23: normalizeWebForegroundMessage existing type is preserved
+00:00 +24: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload
+00:00 +25: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it
+00:00 +26: normalizeWebForegroundMessage userInteraction in payload overrides parameter
+00:00 +27: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap
+00:00 +28: normalizeWebForegroundMessage null routing field values are not included in result
+00:00 +29: normalizeWebForegroundMessage absent routing fields are not included in result
+00:00 +30: All tests passed!
+
+$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+Analyzing messaging_flutter...
+No issues found! (ran in 3.9s)
+```
+
+### 최종 검증
+
+```text
+$ cd packages/messaging_flutter && flutter pub get
+Resolving dependencies...
+Got dependencies!
+11 packages have newer versions incompatible with dependency constraints.
+
+$ cd packages/messaging_flutter && flutter test
+00:00 +0: loading /config/workspace/nexo/packages/messaging_flutter/test/nexo_messaging_test.dart
+00:00 +1: NotificationOpenedEvent.fromMap parses server_url, channel_id, root_id, is_crt_enabled
+00:00 +2: NotificationOpenedEvent.fromMap defaults isCRTEnabled to false when flag is absent or non-true
+00:00 +3: NotificationOpenedEvent.fromMap accepts boolean and numeric-string CRT truthy flags
+00:00 +4: NexoMessagingPlugin.handleNativeEvent opened event emits NotificationOpenedEvent on stream
+00:00 +5: NexoMessagingPlugin.handleNativeEvent message event with userInteraction routes through opened handler
+00:00 +6: NexoMessagingPlugin.handleNativeEvent message event without userInteraction does not trigger navigation
+00:00 +7: NexoMessagingPlugin.handleNativeEvent opened event with CRT and rootId routes to thread callback
+00:00 +8: NexoMessagingPlugin.handleNativeEvent opened event with boolean CRT and rootId routes to thread callback
+00:00 +9: NexoMessagingPlugin.handleNativeEvent opened event with CRT but empty rootId falls back to channel callback
+00:00 +10: NexoMessagingPlugin.handleNativeEvent opened event without server_url skips navigation callbacks
+00:00 +11: NexoMessagingPlugin.handleNativeEvent every event is forwarded to onNotification stream
+00:00 +12: NexoMessagingPlugin.handleNativeEvent token_refresh event saves formatted device token and invokes callback
+00:00 +13: NexoMessagingPlugin.handleNativeEvent debugSendNativeEventForTesting invokes native debug method
+00:00 +14: Channel constants notification and action channel names are preserved
+00:00 +15: NexoMessagingInitializeOptions has all default values set to true
+00:00 +16: NexoMessagingInitializeOptions can override all fields to false
+00:00 +17: NexoMessagingInitializeOptions can override individual fields
+00:00 +18: NexoMessagingPlugin web notification permission reports unsupported status on non-web platforms
+00:00 +19: NexoMessagingPlugin web notification permission request is a no-op unsupported status on non-web platforms
+00:00 +20: NexoMessagingTokenPrefix androidV2 has the expected value
+00:00 +21: NexoMessagingTokenPrefix appleV2 has the expected value
+00:00 +22: NexoMessagingTokenPrefix webV2 has the expected value
+00:00 +23: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message
+00:00 +24: normalizeWebForegroundMessage existing type is preserved
+00:00 +25: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload
+00:00 +26: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it
+00:00 +27: normalizeWebForegroundMessage userInteraction in payload overrides parameter
+00:00 +28: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap
+00:00 +29: normalizeWebForegroundMessage null routing field values are not included in result
+00:00 +30: normalizeWebForegroundMessage absent routing fields are not included in result
+00:00 +30: All tests passed!
+
+$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+Analyzing messaging_flutter...
+No issues found! (ran in 3.9s)
+```
+
+---
+
+> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
+
+## 코드리뷰 결과
+
+- 종합 판정: FAIL
+
+### 차원별 평가
+
+| 차원 | 판정 | 근거 |
+|------|------|------|
+| Correctness | Fail | `normalizeWebForegroundMessage`가 새 map을 만들면서 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 기존 `message` event 필드를 드롭한다. |
+| Completeness | Fail | 계획의 `RemoteMessage data map에 준하는 입력` 보존 요구와 README의 `message` event optional stable fields 계약이 모두 충족되지 않았다. |
+| Test coverage | Fail | mapper tests가 type/userInteraction/routing field만 검증하고, 기존 message payload field 보존을 검증하지 않는다. |
+| API contract | Fail | `onNotification` raw map과 후속 display/click routing이 기대할 payload compatibility data가 mapper 단계에서 손실될 수 있다. |
+| Code quality | Pass | 구현은 작고 deterministic하며 browser/Firebase/web import boundary는 지켰다. |
+| Plan deviation | Fail | 제한된 field allowlist 구현이 payload normalization의 보존 계약보다 좁다. |
+| Verification trust | Pass | `flutter pub get`, `flutter test`, `flutter analyze --no-fatal-infos`를 재실행했고 모두 exit code 0으로 재현됐다. |
+
+### 발견된 문제
+
+- Required: [foreground_message_mapper.dart](/config/workspace/nexo/packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart:15)에서 `result`를 빈 map으로 시작하고 4개 routing field만 복사해, README의 `message` event optional stable fields인 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 등이 손실된다. `payload`의 non-null entry를 먼저 복사한 뒤 `type`과 `userInteraction` 기본값만 채우는 방식으로 바꾸고, null 제거 정책을 전체 entry에 일관되게 적용한다. [nexo_messaging_test.dart](/config/workspace/nexo/packages/messaging_flutter/test/nexo_messaging_test.dart:377)에 이 field 보존을 검증하는 mapper test를 추가한다.
+
+### 다음 단계
+
+- FAIL follow-up: 동일 task directory에 후속 `PLAN-local-G08.md`와 `CODE_REVIEW-local-G08.md`를 작성한다.
--- a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log
+++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log
@ -0,0 +1,205 @@
+<!-- task=m-flutter-web-notification/03+02_event_map plan=1 tag=REVIEW_EVENTMAP -->
+
+# Code Review Reference - REVIEW_EVENTMAP
+
+> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
+> The task is NOT complete until every implementation-owned section below is filled in.
+> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
+> Fill implementation-owned sections, then stop with active files in place and report ready for review.
+> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
+> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record the needed decision in `사용자 리뷰 요청` and stop for code-review.
+> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
+
+## 개요
+
+date=2026-06-07
+task=m-flutter-web-notification/03+02_event_map, plan=1, tag=REVIEW_EVENTMAP
+
+## Roadmap Targets
+
+- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md`
+- Task ids:
+  - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다.
+- Completion mode: check-on-pass
+
+## 이 파일을 읽는 리뷰 에이전트에게
+
+> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
+
+각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
+리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
+
+1. 판정을 append한다.
+2. `CODE_REVIEW-local-G08.md` -> `code_review_local_G08_N.log`, `PLAN-local-G08.md` -> `plan_local_G08_M.log`로 아카이브한다.
+3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-web-notification/03+02_event_map/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다.
+4. PASS이고 task group이 `m-flutter-web-notification`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
+5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
+
+---
+
+## 구현 항목별 완료 여부
+
+| 항목 | 완료 여부 |
+|------|---------|
+| [REVIEW_EVENTMAP-1] Preserve Foreground Payload Fields | [x] |
+
+## 구현 체크리스트
+
+- [x] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart`가 payload의 non-null entry 전체를 보존하고 `type`과 `userInteraction` 기본값만 보강하도록 수정한다.
+- [x] `packages/messaging_flutter/test/nexo_messaging_test.dart`에 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 message payload field 보존 테스트를 추가한다.
+- [x] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다.
+- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+
+## 코드리뷰 전용 체크리스트
+
+> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
+> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
+
+- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
+- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
+- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G08_1.log`로 아카이브한다.
+- [x] active `PLAN-*-G??.md`를 `plan_local_G08_1.log`로 아카이브한다.
+- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
+- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
+- [x] PASS이면 active task 디렉터리 `agent-task/m-flutter-web-notification/03+02_event_map/`를 `agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
+- [x] PASS이고 task group이 `m-flutter-web-notification`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
+- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-flutter-web-notification/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
+- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
+- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
+- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
+
+## 계획 대비 변경 사항
+
+없음. 계획의 해결 방법 코드 스니펫을 그대로 적용했다.
+
+## 주요 설계 결정
+
+- `payload.entries`를 map collection literal로 순회해 non-null entry를 먼저 전부 복사한 뒤, `putIfAbsent`로 `type`과 `userInteraction` 기본값만 주입했다. 이 방식은 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 stable/compatibility field와 미래 추가 field를 allowlist 없이 투명하게 통과시킨다.
+- 기존 테스트 8개는 변경 없이 모두 통과한다. 새로 추가한 테스트 2개(`message stable fields`, `unknown extra fields`)가 field 보존 회귀를 잡는다.
+
+## 사용자 리뷰 요청
+
+_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
+
+- 상태: 없음
+- 사유 유형: 없음
+- 결정 필요: 없음
+- 차단 근거: 없음
+- 실행한 검증/명령: 없음
+- 자동 후속 불가 이유: 없음
+- 재개 조건: 없음
+
+## 리뷰어를 위한 체크포인트
+
+- mapper가 `package:web`, browser Notification, Firebase runtime을 직접 import하지 않는지 확인한다.
+- normalized map이 기존 `message` event optional stable fields와 compatibility data를 드롭하지 않는지 확인한다.
+- 추가 테스트가 field 보존 회귀를 실제로 잡을 수 있는지 확인한다.
+
+## 검증 결과
+
+_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
+
+필수 규칙:
+- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
+- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
+- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
+- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
+- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.
+
+### REVIEW_EVENTMAP-1 중간 검증
+
+```text
+$ cd packages/messaging_flutter && flutter test
+00:00 +22: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message
+00:00 +23: normalizeWebForegroundMessage existing type is preserved
+00:00 +24: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload
+00:00 +25: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it
+00:00 +26: normalizeWebForegroundMessage userInteraction in payload overrides parameter
+00:00 +27: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap
+00:00 +28: normalizeWebForegroundMessage null routing field values are not included in result
+00:00 +29: normalizeWebForegroundMessage absent routing fields are not included in result
+00:00 +30: normalizeWebForegroundMessage message stable fields are preserved in normalized result
+00:00 +31: normalizeWebForegroundMessage unknown extra fields from payload are preserved
+00:00 +32: All tests passed!
+
+$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+Analyzing messaging_flutter...
+No issues found! (ran in 4.0s)
+```
+
+### 최종 검증
+
+```text
+$ cd packages/messaging_flutter && flutter pub get
+Resolving dependencies...
+Got dependencies!
+11 packages have newer versions incompatible with dependency constraints.
+
+$ cd packages/messaging_flutter && flutter test
+00:00 +0: loading /config/workspace/nexo/packages/messaging_flutter/test/nexo_messaging_test.dart
+00:00 +1: NotificationOpenedEvent.fromMap parses server_url, channel_id, root_id, is_crt_enabled
+00:00 +2: NotificationOpenedEvent.fromMap defaults isCRTEnabled to false when flag is absent or non-true
+00:00 +3: NotificationOpenedEvent.fromMap accepts boolean and numeric-string CRT truthy flags
+00:00 +4: NexoMessagingPlugin.handleNativeEvent opened event emits NotificationOpenedEvent on stream
+00:00 +5: NexoMessagingPlugin.handleNativeEvent message event with userInteraction routes through opened handler
+00:00 +6: NexoMessagingPlugin.handleNativeEvent message event without userInteraction does not trigger navigation
+00:00 +7: NexoMessagingPlugin.handleNativeEvent opened event with CRT and rootId routes to thread callback
+00:00 +8: NexoMessagingPlugin.handleNativeEvent opened event with boolean CRT and rootId routes to thread callback
+00:00 +9: NexoMessagingPlugin.handleNativeEvent opened event with CRT but empty rootId falls back to channel callback
+00:00 +10: NexoMessagingPlugin.handleNativeEvent opened event without server_url skips navigation callbacks
+00:00 +11: NexoMessagingPlugin.handleNativeEvent every event is forwarded to onNotification stream
+00:00 +12: NexoMessagingPlugin.handleNativeEvent token_refresh event saves formatted device token and invokes callback
+00:00 +13: NexoMessagingPlugin.handleNativeEvent debugSendNativeEventForTesting invokes native debug method
+00:00 +14: Channel constants notification and action channel names are preserved
+00:00 +15: NexoMessagingInitializeOptions has all default values set to true
+00:00 +16: NexoMessagingInitializeOptions can override all fields to false
+00:00 +17: NexoMessagingInitializeOptions can override individual fields
+00:00 +18: NexoMessagingPlugin web notification permission reports unsupported status on non-web platforms
+00:00 +19: NexoMessagingPlugin web notification permission request is a no-op unsupported status on non-web platforms
+00:00 +20: NexoMessagingTokenPrefix androidV2 has the expected value
+00:00 +21: NexoMessagingTokenPrefix appleV2 has the expected value
+00:00 +22: NexoMessagingTokenPrefix webV2 has the expected value
+00:00 +23: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message
+00:00 +24: normalizeWebForegroundMessage existing type is preserved
+00:00 +25: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload
+00:00 +26: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it
+00:00 +27: normalizeWebForegroundMessage userInteraction in payload overrides parameter
+00:00 +28: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap
+00:00 +29: normalizeWebForegroundMessage null routing field values are not included in result
+00:00 +30: normalizeWebForegroundMessage absent routing fields are not included in result
+00:00 +31: normalizeWebForegroundMessage message stable fields are preserved in normalized result
+00:00 +32: normalizeWebForegroundMessage unknown extra fields from payload are preserved
+00:00 +32: All tests passed!
+
+$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+Analyzing messaging_flutter...
+No issues found! (ran in 4.0s)
+```
+
+---
+
+> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
+
+## 코드리뷰 결과
+
+- 종합 판정: PASS
+
+### 차원별 평가
+
+| 차원 | 판정 | 근거 |
+|------|------|------|
+| Correctness | Pass | mapper가 payload의 non-null entry를 먼저 복사한 뒤 `type`과 `userInteraction` 기본값만 보강해 기존 `message` event field를 보존한다. |
+| Completeness | Pass | G08 계획의 field 보존 수정, 테스트 추가, 필수 검증, review stub 작성이 모두 완료됐다. |
+| Test coverage | Pass | `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 보존과 unknown extra field 보존 테스트가 추가됐다. |
+| API contract | Pass | README의 `message` event optional stable fields와 raw `onNotification` compatibility data 계약을 깨지 않는다. |
+| Code quality | Pass | mapper는 순수 Dart helper로 유지되고 `package:web`, browser Notification, Firebase runtime import가 없다. |
+| Plan deviation | Pass | 계획의 해결 방법을 그대로 적용했고 범위 밖 display/click/Firebase wiring은 추가하지 않았다. |
+| Verification trust | Pass | `flutter pub get`, `flutter test`, `flutter analyze --no-fatal-infos`를 재실행했고 모두 exit code 0으로 재현됐다. |
+
+### 발견된 문제
+
+- 없음
+
+### 다음 단계
+
+- PASS: `complete.log`를 작성하고 task directory를 `agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/`로 이동한다.
--- a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/complete.log
+++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/complete.log
@ -0,0 +1,44 @@
+# Complete - m-flutter-web-notification/03+02_event_map
+
+## 완료 일시
+
+2026-06-07
+
+## 요약
+
+Flutter Web foreground payload mapper의 event-map 작업을 2회 리뷰 루프로 검토했고 최종 판정은 PASS다.
+
+## 루프 이력
+
+| Plan | Review | Verdict | 메모 |
+|------|--------|---------|------|
+| `plan_local_G07_0.log` | `code_review_local_G07_0.log` | FAIL | mapper가 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 기존 `message` event field를 드롭해 follow-up을 생성했다. |
+| `plan_local_G08_1.log` | `code_review_local_G08_1.log` | PASS | mapper가 payload의 non-null entry 전체를 보존하고 `type`/`userInteraction` 기본값만 보강하도록 수정했으며 field 보존 테스트와 검증이 통과했다. |
+
+## 구현/정리 내용
+
+- `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart`를 추가해 host-injected 또는 Firebase foreground payload를 기존 `PushNotificationType.message` map 계약으로 정규화한다.
+- mapper가 non-null payload entry를 보존하고 누락된 `type`과 `userInteraction` 기본값만 추가하도록 정리했다.
+- `packages/messaging_flutter/test/nexo_messaging_test.dart`에 mapper 기본값, routing field, null 제거, stable/compatibility field 보존, unknown extra field 보존 테스트를 추가했다.
+- README의 Web baseline 설명에 foreground payload mapper 경계를 반영했다.
+
+## 최종 검증
+
+- `cd packages/messaging_flutter && flutter pub get` - PASS; dependency resolution completed with only newer-version notices.
+- `cd packages/messaging_flutter && flutter test` - PASS; 32 tests passed.
+- `cd packages/messaging_flutter && flutter analyze --no-fatal-infos` - PASS; `No issues found!`.
+
+## Roadmap Completion
+
+- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md`
+- Completed task ids:
+  - `event-map`: PASS; evidence=`agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log`, `agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log`; verification=`cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`
+- Not completed task ids: 없음
+
+## 잔여 Nit
+
+- 없음
+
+## 후속 작업
+
+- 없음
--- a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log
+++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log
@ -0,0 +1,165 @@
+<!-- task=m-flutter-web-notification/03+02_event_map plan=0 tag=EVENTMAP -->
+
+# Plan - EVENTMAP
+
+## 이 파일을 읽는 구현 에이전트에게
+
+이 task는 Chrome foreground 알림 Epic의 `event-map` Task를 완료하기 위한 구현 계획이다. 구현 후 반드시 active `CODE_REVIEW-local-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운 뒤, active 파일을 그대로 두고 리뷰 준비를 보고한다.
+
+사용자에게 직접 질문하지 말고, 선택지를 채팅으로 제시하지 말고, `request_user_input`을 호출하지 않는다. 사용자만 결정할 수 있는 차단이 생기면 `CODE_REVIEW-local-G07.md`의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 멈춘다. 구현 에이전트는 `USER_REVIEW.md`, `complete.log`, `*.log` archive를 만들지 않는다.
+
+## 배경
+
+현재 web baseline은 browser Notification interop와 permission API까지 갖췄지만, foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화하는 순수 mapper가 없다. Display/click routing을 구현하기 전에 payload normalization을 독립 단위로 고정해야 후속 browser 표시 로직이 기존 `handleNativeEvent()` 계약을 재사용할 수 있다.
+
+## 사용자 리뷰 요청 흐름
+
+구현 중 차단은 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 직접 사용자 프롬프트는 금지되며, code-review가 요청 정당성을 검증하고 필요할 때만 `USER_REVIEW.md`를 작성한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백은 사용자 리뷰 요청이 아니다.
+
+## Roadmap Targets
+
+- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md`
+- Task ids:
+  - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다.
+- 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`
+- `packages/messaging_flutter/pubspec.yaml`
+- `packages/messaging_flutter/lib/nexo_messaging.dart`
+- `packages/messaging_flutter/lib/src/nexo_messaging_options.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/lib/src/web_notification_permission_client.dart`
+- `packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart`
+- `packages/messaging_flutter/test/nexo_messaging_test.dart`
+- `packages/messaging_flutter/README.md`
+- `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`.
+- 적용 명령:
+  - `cd packages/messaging_flutter && flutter pub get`
+  - `cd packages/messaging_flutter && flutter test`
+  - `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`
+- 이 task는 package-internal mapper와 unit tests만 다루므로 client-app smoke는 범위 밖이다.
+
+### 테스트 커버리지 공백
+
+- 기존 tests는 native event handling과 web permission unsupported path를 다루지만, web foreground payload normalization은 다루지 않는다.
+- 이 plan은 mapper 단위 테스트를 추가해 `PushNotificationType.message`, `server_url`, `channel_id`, `root_id`, `is_crt_enabled`, `userInteraction` 기본값과 override를 검증한다.
+- 실제 browser Notification 표시/click은 후속 `04+02,03_display` 계획 대상이다.
+
+### 심볼 참조
+
+- renamed/removed symbol: none.
+- 새 mapper는 기존 `PushNotificationType`과 `NotificationOpenedEvent.fromMap` 계약을 보존해야 한다.
+
+### 분할 판단
+
+- 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`로 충족됐다.
+- sibling plans:
+  - `03+02_event_map`: foreground payload mapper와 tests.
+  - `04+02,03_display`: browser Notification 표시/click routing. 이 plan의 PASS 후 진행해야 한다.
+- mapper는 순수 Dart 단위로 검증 가능하고 display는 browser interop와 event routing을 포함하므로 분리한다.
+
+### 범위 결정 근거
+
+- 포함: package-internal web foreground payload mapper, mapper tests, 필요한 README의 짧은 계약 설명.
+- 제외: `Notification` 표시, click listener, Firebase `onMessage` 구독 wiring, `apps/flutter-test` UI, Full Web Push/service worker/VAPID.
+- 제외 이유: event-map은 후속 display가 소비할 normalized map 계약을 만드는 선행 단위다.
+
+### 빌드 등급
+
+- `local-G07`: public event contract와 후속 display dependency가 있지만 범위는 pure mapper와 tests로 제한되고 deterministic Flutter commands로 검증 가능하다.
+
+## 구현 체크리스트
+
+- [ ] `packages/messaging_flutter/lib/src/web/` 아래에 foreground payload mapper를 추가하고 공용 Dart/API가 `package:web`를 직접 import하지 않게 유지한다.
+- [ ] mapper가 host-injected `Map<String, dynamic>` payload를 기존 `PushNotificationType.message` map으로 정규화하도록 구현한다.
+- [ ] mapper가 `RemoteMessage` data map에 준하는 입력과 CRT/thread/channel fields를 보존하고 `userInteraction` 기본값을 `false`로 둔다.
+- [ ] mapper 단위 테스트를 추가해 message type 기본값, opened routing field 보존, explicit type/userInteraction override를 검증한다.
+- [ ] `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의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+
+## [EVENTMAP-1] Foreground Payload Mapper
+
+### 문제
+
+[NexoMessagingPlugin.handleNativeEvent](/config/workspace/nexo/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart:150)는 이미 `PushNotificationType` map을 처리하지만, Web foreground payload를 이 map으로 변환하는 package-owned helper가 없다. 후속 display 작업이 browser click을 기존 opened routing으로 연결하려면 먼저 normalized map 계약이 필요하다.
+
+### 해결 방법
+
+`packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` 같은 내부 파일을 추가한다. 함수명은 구현자가 코드 맥락에 맞게 정하되, 다음 계약을 만족해야 한다.
+
+```dart
+Map<String, dynamic> normalizeWebForegroundMessage(
+  Map<String, dynamic> payload, {
+  bool userInteraction = false,
+})
+```
+
+요구 사항:
+
+- `type`이 없으면 `PushNotificationType.message`를 넣는다.
+- `userInteraction`이 없으면 인자 기본값을 넣는다.
+- `server_url`, `channel_id`, `root_id`, `is_crt_enabled`는 기존 key 이름 그대로 보존한다.
+- null value는 normalized map에 억지로 넣지 않는다.
+- `package:web`, browser `Notification`, Firebase runtime을 import하지 않는다.
+
+### 수정 파일 및 체크리스트
+
+- [ ] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` 또는 동등한 내부 mapper 파일 추가
+- [ ] `packages/messaging_flutter/test/nexo_messaging_test.dart` 또는 focused test file에 mapper tests 추가
+- [ ] 필요하면 README에 mapper/display 경계 한 줄 보강
+
+### 테스트 작성
+
+- type 누락 payload가 `PushNotificationType.message`로 정규화되는지 검증한다.
+- existing type과 `userInteraction`이 있는 경우 보존되는지 검증한다.
+- CRT/thread/channel routing fields가 `NotificationOpenedEvent.fromMap`과 호환되게 남는지 검증한다.
+
+### 중간 검증
+
+```sh
+cd packages/messaging_flutter && flutter test
+cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+```
+
+기대 결과: tests와 analyzer가 통과한다.
+
+## 수정 파일 요약
+
+| 파일 | 항목 |
+| --- | --- |
+| `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` | EVENTMAP-1 |
+| `packages/messaging_flutter/test/nexo_messaging_test.dart` 또는 focused test file | EVENTMAP-1 |
+| `packages/messaging_flutter/README.md` | EVENTMAP-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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
--- a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log
+++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log
@ -0,0 +1,116 @@
+<!-- task=m-flutter-web-notification/03+02_event_map plan=1 tag=REVIEW_EVENTMAP -->
+
+# Plan - REVIEW_EVENTMAP
+
+## 이 파일을 읽는 구현 에이전트에게
+
+이 task는 이전 `EVENTMAP` 리뷰의 Required 문제만 고치는 후속 계획이다. 구현 후 반드시 active `CODE_REVIEW-local-G08.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운 뒤, active 파일을 그대로 두고 리뷰 준비를 보고한다.
+
+사용자에게 직접 질문하지 말고, 선택지를 채팅으로 제시하지 말고, `request_user_input`을 호출하지 않는다. 사용자만 결정할 수 있는 차단이 생기면 `CODE_REVIEW-local-G08.md`의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 멈춘다. 구현 에이전트는 `USER_REVIEW.md`, `complete.log`, `*.log` archive를 만들지 않는다.
+
+## Roadmap Targets
+
+- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md`
+- Task ids:
+  - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다.
+- Completion mode: check-on-pass
+
+## 이전 리뷰 요약
+
+- 이전 plan: `agent-task/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log`
+- 이전 review: `agent-task/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log`
+- 이전 판정: FAIL
+- Required: `normalizeWebForegroundMessage`가 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 기존 `message` event field를 드롭한다. 기존 payload의 non-null entry를 보존하고 `type`/`userInteraction` 기본값만 보강해야 한다.
+
+## 범위 결정 근거
+
+- 포함: mapper의 field 보존 방식 수정, mapper 단위 테스트 보강, 기존 검증 명령 재실행.
+- 제외: browser Notification 표시, click listener, Firebase `onMessage` 구독 wiring, public API export 변경, README 추가 확장.
+- 이유: 이전 구현은 browser/Firebase import boundary와 기본값 로직은 통과했으므로, follow-up은 payload 손실 문제만 고친다.
+
+## 빌드 등급
+
+- `local-G08`: 실패 원인이 명확하고 deterministic unit test로 재현 가능하다. 기존 `local-G07`보다 한 단계 높여 payload contract와 test coverage를 더 엄격히 확인한다.
+
+## 구현 체크리스트
+
+- [ ] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart`가 payload의 non-null entry 전체를 보존하고 `type`과 `userInteraction` 기본값만 보강하도록 수정한다.
+- [ ] `packages/messaging_flutter/test/nexo_messaging_test.dart`에 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 message payload field 보존 테스트를 추가한다.
+- [ ] `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의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+
+## [REVIEW_EVENTMAP-1] Preserve Foreground Payload Fields
+
+### 문제
+
+현재 mapper는 다음처럼 빈 map을 만들고 allowlist field만 복사한다.
+
+```dart
+final result = <String, dynamic>{};
+result['type'] = payload['type'] ?? PushNotificationType.message;
+result['userInteraction'] = payload['userInteraction'] ?? userInteraction;
+```
+
+이 방식은 README의 `message` event optional stable fields인 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data`를 foreground normalization 단계에서 잃어버린다. 후속 display/click routing과 raw `onNotification` compatibility data가 같은 map을 소비할 수 있으므로, mapper는 필드를 축소하지 말아야 한다.
+
+### 해결 방법
+
+`payload`의 non-null entry를 먼저 복사하고, 누락된 기본 field만 추가한다.
+
+```dart
+final result = <String, dynamic>{
+  for (final entry in payload.entries)
+    if (entry.value != null) entry.key: entry.value,
+};
+result.putIfAbsent('type', () => PushNotificationType.message);
+result.putIfAbsent('userInteraction', () => userInteraction);
+```
+
+유지할 계약:
+
+- `type`이 없으면 `PushNotificationType.message`를 넣는다.
+- `type`이 이미 있으면 그대로 둔다.
+- `userInteraction`이 없으면 인자 기본값을 넣는다.
+- `userInteraction`이 이미 있으면 그대로 둔다.
+- null value는 normalized map에 넣지 않는다.
+- 기존 stable/compatibility payload field는 값이 null이 아닌 한 보존한다.
+- `package:web`, browser `Notification`, Firebase runtime을 import하지 않는다.
+
+### 수정 파일 및 체크리스트
+
+- [ ] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart`
+- [ ] `packages/messaging_flutter/test/nexo_messaging_test.dart`
+
+### 테스트 작성
+
+- `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data`가 normalize 결과에 그대로 남는지 검증한다.
+- null field가 제거되는 기존 테스트가 계속 통과하는지 확인한다.
+- type/userInteraction 기본값과 override 테스트가 계속 통과하는지 확인한다.
+
+### 중간 검증
+
+```sh
+cd packages/messaging_flutter && flutter test
+cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+```
+
+기대 결과: tests와 analyzer가 통과한다.
+
+## 수정 파일 요약
+
+| 파일 | 항목 |
+| --- | --- |
+| `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` | REVIEW_EVENTMAP-1 |
+| `packages/messaging_flutter/test/nexo_messaging_test.dart` | REVIEW_EVENTMAP-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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
--- a/agent-task/m-flutter-web-notification/04+02,03_display/CODE_REVIEW-local-G08.md
+++ b/agent-task/m-flutter-web-notification/04+02,03_display/CODE_REVIEW-local-G08.md
@ -0,0 +1,117 @@
+<!-- task=m-flutter-web-notification/04+02,03_display plan=0 tag=WEBDISPLAY -->
+
+# Code Review Reference - WEBDISPLAY
+
+> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
+> The task is NOT complete until every implementation-owned section below is filled in.
+> Do not start until predecessor `03+02_event_map` has `complete.log`.
+> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
+> Fill implementation-owned sections, then stop with active files in place and report ready for review.
+> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
+> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation.
+> Finalization is review-agent-only.
+
+## 개요
+
+date=2026-06-07
+task=m-flutter-web-notification/04+02,03_display, plan=0, tag=WEBDISPLAY
+
+## 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
+
+## 이 파일을 읽는 리뷰 에이전트에게
+
+> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
+
+각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
+
+## 구현 항목별 완료 여부
+
+| 항목 | 완료 여부 |
+|------|---------|
+| [WEBDISPLAY-1] Browser Foreground Display And Click Routing | [ ] |
+
+## 구현 체크리스트
+
+- [ ] 구현 시작 전 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의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+
+## 코드리뷰 전용 체크리스트
+
+> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
+
+- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
+- [ ] predecessor `03+02_event_map` complete.log가 실제로 있었는지 확인한다.
+- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G08_N.log`로 아카이브한다.
+- [ ] active `PLAN-*-G??.md`를 `plan_local_G08_M.log`로 아카이브한다.
+- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
+- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
+- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-web-notification/04+02,03_display/`로 이동한다.
+- [ ] PASS이고 task group이 `m-flutter-web-notification`이면 런타임 완료 이벤트 메타데이터를 보고한다.
+
+## 계획 대비 변경 사항
+
+_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
+
+## 주요 설계 결정
+
+_구현 에이전트가 주요 설계 결정 사항을 기록한다._
+
+## 사용자 리뷰 요청
+
+_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
+
+- 상태: 없음
+- 사유 유형: 없음
+- 결정 필요: 없음
+- 차단 근거: 없음
+- 실행한 검증/명령: 없음
+- 자동 후속 불가 이유: 없음
+- 재개 조건: 없음
+
+## 리뷰어를 위한 체크포인트
+
+- `03+02_event_map` predecessor 완료가 확인됐는지 확인한다.
+- public display API가 unsupported/permission denied/granted 결과를 구분하는지 확인한다.
+- click callback이 기존 `handleNativeEvent()` routing을 재사용하는지 확인한다.
+- 실제 browser prompt/OS tray evidence를 이 task의 필수 검증으로 요구하지 않았는지 확인한다.
+
+## 검증 결과
+
+_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
+
+### WEBDISPLAY-1 중간 검증
+
+```text
+$ cd packages/messaging_flutter && flutter test
+(output)
+
+$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+(output)
+```
+
+### 최종 검증
+
+```text
+$ cd packages/messaging_flutter && flutter pub get
+(output)
+
+$ cd packages/messaging_flutter && flutter test
+(output)
+
+$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos
+(output)
+```
+
+---
+
+> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
--- a/agent-task/m-flutter-web-notification/04+02,03_display/PLAN-local-G08.md
+++ b/agent-task/m-flutter-web-notification/04+02,03_display/PLAN-local-G08.md
@ -0,0 +1,172 @@
+<!-- task=m-flutter-web-notification/04+02,03_display plan=0 tag=WEBDISPLAY -->
+
+# 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<NexoMessagingWebNotificationDisplayResult>
+showWebForegroundNotification(Map<String, dynamic> 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
--- a/packages/messaging_flutter/README.md
+++ b/packages/messaging_flutter/README.md
@ -53,7 +53,7 @@ copying upstream mobile code.
 | iOS | Stub | Plugin scaffold exists, behavior is not implemented yet |
 | macOS | Stub | Plugin scaffold exists; user-provided signing, machine, APNs/Firebase scope, and evidence handoff requirements are documented in [`../../docs/macos-notification-test-guide.md`](../../docs/macos-notification-test-guide.md) |
 | Windows | Not registered | No Flutter plugin scaffold yet; user-provided Windows runner, packaging, identity, signing, and evidence handoff requirements are documented in [`../../docs/windows-notification-test-guide.md`](../../docs/windows-notification-test-guide.md) |
-| Web | Baseline | Plugin registration (`NexoMessagingWeb.registerWith()`), `package:web` dependency, and browser Notification interop boundary (`BrowserNotificationInterop`) are in place. Public permission/request/display APIs are reserved for a future Epic. Full Web Push (service worker, VAPID, server device-token registration) follows. |
+| Web | Baseline | Plugin registration (`NexoMessagingWeb.registerWith()`), `package:web` dependency, browser Notification interop boundary (`BrowserNotificationInterop`), and foreground payload mapper (`normalizeWebForegroundMessage`) are in place. The mapper normalizes host-injected payloads to the `PushNotificationType` map contract; browser Notification display and click routing follow in a subsequent Epic. Full Web Push (service worker, VAPID, server device-token registration) follows. |

 ## Repository Layout

@ -305,9 +305,17 @@ registration.

 Remaining for the foreground Epic:

- Public permission / display / click routing APIs.
+- Public display / click routing APIs.
 - Notification event forwarding through the main plugin stream.

+Foreground browser permission APIs are available on the plugin singleton:
+
+- `getWebNotificationPermissionStatus()` returns support and current browser
+  permission state.
+- `requestWebNotificationPermission()` requests browser notification permission
+  on Flutter Web and returns the resulting state. On non-web platforms it
+  returns an unsupported status without touching native permission APIs.
+
 ## Public API Contract

 Apps should import only `package:nexo_messaging/nexo_messaging.dart`. The
@ -663,7 +671,7 @@ Evidence to capture:
 - iOS and macOS are scaffolded but no-op.
 - Web baseline (`NexoMessagingWeb.registerWith()`, `BrowserNotificationInterop`,
  `package:web` dependency) is implemented. However:
-  - Public permission / display / click routing APIs are not yet exposed.
+  - Public display / click routing APIs are not yet exposed.
  - Notification events are not yet forwarded through the main plugin stream.
  - Full Web Push (service worker, VAPID, server device-token registration) is
    not implemented.
--- a/packages/messaging_flutter/lib/nexo_messaging.dart
+++ b/packages/messaging_flutter/lib/nexo_messaging.dart
@ -1,4 +1,5 @@
 export 'src/nexo_messaging_options.dart';
 export 'src/nexo_messaging_plugin.dart';
+export 'src/web_notification_permission.dart';
 export 'src/notification_opened_event.dart';
 export 'src/push_notification_type.dart';
--- a/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart
+++ b/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart
@ -7,6 +7,9 @@ import 'package:flutter/services.dart';
 import 'nexo_messaging_options.dart';
 import 'notification_opened_event.dart';
 import 'push_notification_type.dart';
+import 'web_notification_permission.dart';
+import 'web_notification_permission_client.dart';
+import 'web_notification_permission_client_factory.dart';

 const String _kNotificationChannelName =
    'com.tokilabs.nexo.messaging/notifications';
@ -41,6 +44,9 @@ class NexoMessagingPlugin {
  Stream<NotificationOpenedEvent> get onNotificationOpened =>
      _openedController.stream;

+  final WebNotificationPermissionClient _webPermissionClient =
+      createWebNotificationPermissionClient();
+
  void Function(String serverUrl, String channelId)? onNavigateToChannel;
  void Function(String serverUrl, String rootId)? onNavigateToThread;
  void Function(String deviceToken)? onDeviceTokenReady;
@ -114,6 +120,25 @@ class NexoMessagingPlugin {
    );
  }

+  /// Returns whether browser notifications are supported and the current
+  /// browser permission state.
+  ///
+  /// On non-web platforms this returns an unsupported status without touching
+  /// native notification permission APIs.
+  Future<NexoMessagingWebNotificationStatus>
+  getWebNotificationPermissionStatus() {
+    return _webPermissionClient.currentStatus();
+  }
+
+  /// Requests browser notification permission when running on Flutter Web.
+  ///
+  /// On non-web platforms this returns an unsupported status without prompting
+  /// the user or touching native notification permission APIs.
+  Future<NexoMessagingWebNotificationStatus>
+  requestWebNotificationPermission() {
+    return _webPermissionClient.requestPermission();
+  }
+
  /// Reads the current FCM/APNs token and saves it via [_saveDeviceToken].
  /// Called during [initialize] when [NexoMessagingInitializeOptions.registerDeviceToken] is `true`.
  Future<void> _saveCurrentDeviceToken() async {
--- a/packages/messaging_flutter/lib/src/nexo_messaging_web.dart
+++ b/packages/messaging_flutter/lib/src/nexo_messaging_web.dart
@ -15,7 +15,8 @@ import 'web/browser_notification_interop_web.dart';
 class NexoMessagingWeb {
  /// The browser notification interop instance used by this plugin.
  /// On web builds this resolves to [BrowserNotificationInteropImpl].
-  static BrowserNotificationInterop interop = const BrowserNotificationInteropImpl();
+  static BrowserNotificationInterop interop =
+      const BrowserNotificationInteropImpl();

  /// Register this plugin for web platforms.
  static void registerWith(Registrar registrar) {
--- a/packages/messaging_flutter/lib/src/web/browser_notification_interop.dart
+++ b/packages/messaging_flutter/lib/src/web/browser_notification_interop.dart
@ -10,6 +10,9 @@
 abstract class BrowserNotificationInterop {
  const BrowserNotificationInterop();

+  /// Whether the browser exposes the Notification API.
+  bool get isSupported;
+
  /// Current browser notification permission state (`granted`, `denied`, or
  /// `default`).
  String get permission;
--- a/packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart
+++ b/packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart
@ -1,4 +1,5 @@
 import 'dart:js_interop';
+import 'dart:js_interop_unsafe';

 import 'package:web/web.dart' as web;

@ -11,6 +12,9 @@ import 'browser_notification_interop.dart';
 class BrowserNotificationInteropImpl extends BrowserNotificationInterop {
  const BrowserNotificationInteropImpl();

+  @override
+  bool get isSupported => globalContext.has('Notification');
+
  @override
  String get permission => web.Notification.permission.toString();

--- a/packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart
+++ b/packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart
@ -0,0 +1,23 @@
+import '../push_notification_type.dart';
+
+/// Normalizes a host-injected or Firebase foreground message payload into the
+/// canonical [PushNotificationType] map contract consumed by
+/// [NexoMessagingPlugin.handleNativeEvent].
+///
+/// Copies all non-null entries from [payload], then fills in defaults for
+/// `type` and `userInteraction` if absent. No other fields are added or
+/// removed.
+///
+/// Does NOT import `package:web`, browser Notification, or Firebase runtime.
+Map<String, dynamic> normalizeWebForegroundMessage(
+  Map<String, dynamic> payload, {
+  bool userInteraction = false,
+}) {
+  final result = <String, dynamic>{
+    for (final entry in payload.entries)
+      if (entry.value != null) entry.key: entry.value,
+  };
+  result.putIfAbsent('type', () => PushNotificationType.message);
+  result.putIfAbsent('userInteraction', () => userInteraction);
+  return result;
+}
--- a/packages/messaging_flutter/lib/src/web/web_notification_permission_client_stub.dart
+++ b/packages/messaging_flutter/lib/src/web/web_notification_permission_client_stub.dart
@ -0,0 +1,21 @@
+import '../web_notification_permission.dart';
+import '../web_notification_permission_client.dart';
+
+class UnsupportedWebNotificationPermissionClient
+    extends WebNotificationPermissionClient {
+  const UnsupportedWebNotificationPermissionClient();
+
+  @override
+  Future<NexoMessagingWebNotificationStatus> currentStatus() async {
+    return const NexoMessagingWebNotificationStatus.unsupported();
+  }
+
+  @override
+  Future<NexoMessagingWebNotificationStatus> requestPermission() async {
+    return const NexoMessagingWebNotificationStatus.unsupported();
+  }
+}
+
+WebNotificationPermissionClient createWebNotificationPermissionClient() {
+  return const UnsupportedWebNotificationPermissionClient();
+}
--- a/packages/messaging_flutter/lib/src/web/web_notification_permission_client_web.dart
+++ b/packages/messaging_flutter/lib/src/web/web_notification_permission_client_web.dart
@ -0,0 +1,36 @@
+import '../web_notification_permission.dart';
+import '../web_notification_permission_client.dart';
+import 'browser_notification_interop.dart';
+import 'browser_notification_interop_web.dart';
+
+class BrowserWebNotificationPermissionClient
+    extends WebNotificationPermissionClient {
+  const BrowserWebNotificationPermissionClient({
+    BrowserNotificationInterop interop = const BrowserNotificationInteropImpl(),
+  }) : _interop = interop;
+
+  final BrowserNotificationInterop _interop;
+
+  @override
+  Future<NexoMessagingWebNotificationStatus> currentStatus() async {
+    if (!_interop.isSupported) {
+      return const NexoMessagingWebNotificationStatus.unsupported();
+    }
+    return NexoMessagingWebNotificationStatus.fromBrowserPermission(
+      _interop.permission,
+    );
+  }
+
+  @override
+  Future<NexoMessagingWebNotificationStatus> requestPermission() async {
+    if (!_interop.isSupported) {
+      return const NexoMessagingWebNotificationStatus.unsupported();
+    }
+    final permission = await _interop.requestPermission();
+    return NexoMessagingWebNotificationStatus.fromBrowserPermission(permission);
+  }
+}
+
+WebNotificationPermissionClient createWebNotificationPermissionClient() {
+  return const BrowserWebNotificationPermissionClient();
+}
--- a/packages/messaging_flutter/lib/src/web_notification_permission.dart
+++ b/packages/messaging_flutter/lib/src/web_notification_permission.dart
@ -0,0 +1,62 @@
+/// Browser notification permission states exposed by [NexoMessagingPlugin].
+enum NexoMessagingWebNotificationPermission {
+  /// Browser Notification API is not available on this platform/runtime.
+  unsupported,
+
+  /// Browser permission has not been granted or denied yet.
+  defaultPermission,
+
+  /// Browser permission was denied.
+  denied,
+
+  /// Browser permission was granted.
+  granted,
+
+  /// Browser returned an unknown permission string.
+  unknown,
+}
+
+/// Current browser notification support and permission status.
+class NexoMessagingWebNotificationStatus {
+  const NexoMessagingWebNotificationStatus({
+    required this.isSupported,
+    required this.permission,
+    this.rawPermission,
+  });
+
+  /// Creates an unsupported status for non-web or unsupported web runtimes.
+  const NexoMessagingWebNotificationStatus.unsupported()
+    : isSupported = false,
+      permission = NexoMessagingWebNotificationPermission.unsupported,
+      rawPermission = null;
+
+  /// Creates a supported status from a browser `Notification.permission` value.
+  factory NexoMessagingWebNotificationStatus.fromBrowserPermission(
+    String permission,
+  ) {
+    final normalized = permission.trim().toLowerCase();
+    return NexoMessagingWebNotificationStatus(
+      isSupported: true,
+      permission: switch (normalized) {
+        'default' => NexoMessagingWebNotificationPermission.defaultPermission,
+        'denied' => NexoMessagingWebNotificationPermission.denied,
+        'granted' => NexoMessagingWebNotificationPermission.granted,
+        _ => NexoMessagingWebNotificationPermission.unknown,
+      },
+      rawPermission: permission,
+    );
+  }
+
+  /// Whether the current runtime exposes browser notifications.
+  final bool isSupported;
+
+  /// Normalized browser notification permission.
+  final NexoMessagingWebNotificationPermission permission;
+
+  /// Raw browser permission string, when available.
+  final String? rawPermission;
+
+  /// Whether browser notification display is currently allowed.
+  bool get isGranted =>
+      permission == NexoMessagingWebNotificationPermission.granted;
+}
--- a/packages/messaging_flutter/lib/src/web_notification_permission_client.dart
+++ b/packages/messaging_flutter/lib/src/web_notification_permission_client.dart
@ -0,0 +1,9 @@
+import 'web_notification_permission.dart';
+
+abstract class WebNotificationPermissionClient {
+  const WebNotificationPermissionClient();
+
+  Future<NexoMessagingWebNotificationStatus> currentStatus();
+
+  Future<NexoMessagingWebNotificationStatus> requestPermission();
+}
--- a/packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart
+++ b/packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart
@ -0,0 +1,8 @@
+import 'web/web_notification_permission_client_stub.dart'
+    if (dart.library.js_interop) 'web/web_notification_permission_client_web.dart'
+    as impl;
+import 'web_notification_permission_client.dart';
+
+WebNotificationPermissionClient createWebNotificationPermissionClient() {
+  return impl.createWebNotificationPermissionClient();
+}
--- a/packages/messaging_flutter/test/nexo_messaging_test.dart
+++ b/packages/messaging_flutter/test/nexo_messaging_test.dart
@ -3,6 +3,7 @@ import 'dart:async';
 import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:nexo_messaging/nexo_messaging.dart';
+import 'package:nexo_messaging/src/web/foreground_message_mapper.dart';

 void main() {
  TestWidgetsFlutterBinding.ensureInitialized();
@ -325,6 +326,40 @@ void main() {
    });
  });

+  group('NexoMessagingPlugin web notification permission', () {
+    late NexoMessagingPlugin plugin;
+
+    setUp(() {
+      plugin = NexoMessagingPlugin.instance;
+    });
+
+    test('reports unsupported status on non-web platforms', () async {
+      final status = await plugin.getWebNotificationPermissionStatus();
+
+      expect(status.isSupported, isFalse);
+      expect(
+        status.permission,
+        NexoMessagingWebNotificationPermission.unsupported,
+      );
+      expect(status.rawPermission, isNull);
+      expect(status.isGranted, isFalse);
+    });
+
+    test(
+      'request is a no-op unsupported status on non-web platforms',
+      () async {
+        final status = await plugin.requestWebNotificationPermission();
+
+        expect(status.isSupported, isFalse);
+        expect(
+          status.permission,
+          NexoMessagingWebNotificationPermission.unsupported,
+        );
+        expect(status.rawPermission, isNull);
+      },
+    );
+  });
+
  group('NexoMessagingTokenPrefix', () {
    test('androidV2 has the expected value', () {
      expect(NexoMessagingTokenPrefix.androidV2, 'android_rn-v2');
@ -338,4 +373,110 @@ void main() {
      expect(NexoMessagingTokenPrefix.webV2, 'web_rn-v2');
    });
  });
+
+  group('normalizeWebForegroundMessage', () {
+    test('missing type defaults to PushNotificationType.message', () {
+      final result = normalizeWebForegroundMessage({
+        'server_url': 'https://nexo.example.com',
+        'channel_id': 'ch-1',
+      });
+
+      expect(result['type'], PushNotificationType.message);
+    });
+
+    test('existing type is preserved', () {
+      final result = normalizeWebForegroundMessage({
+        'type': PushNotificationType.clear,
+      });
+
+      expect(result['type'], PushNotificationType.clear);
+    });
+
+    test('userInteraction defaults to false when absent from payload', () {
+      final result = normalizeWebForegroundMessage({});
+
+      expect(result['userInteraction'], isFalse);
+    });
+
+    test('userInteraction parameter is applied when payload does not set it', () {
+      final result = normalizeWebForegroundMessage({}, userInteraction: true);
+
+      expect(result['userInteraction'], isTrue);
+    });
+
+    test('userInteraction in payload overrides parameter', () {
+      final result = normalizeWebForegroundMessage(
+        {'userInteraction': true},
+        userInteraction: false,
+      );
+
+      expect(result['userInteraction'], isTrue);
+    });
+
+    test('routing fields are preserved for NotificationOpenedEvent.fromMap', () {
+      final result = normalizeWebForegroundMessage({
+        'server_url': 'https://nexo.example.com',
+        'channel_id': 'ch-1',
+        'root_id': 'root-99',
+        'is_crt_enabled': 'true',
+      });
+
+      final event = NotificationOpenedEvent.fromMap(result);
+      expect(event.serverUrl, 'https://nexo.example.com');
+      expect(event.channelId, 'ch-1');
+      expect(event.rootId, 'root-99');
+      expect(event.isCRTEnabled, isTrue);
+    });
+
+    test('null routing field values are not included in result', () {
+      final result = normalizeWebForegroundMessage({
+        'server_url': null,
+        'channel_id': 'ch-1',
+      });
+
+      expect(result.containsKey('server_url'), isFalse);
+      expect(result['channel_id'], 'ch-1');
+    });
+
+    test('absent routing fields are not included in result', () {
+      final result = normalizeWebForegroundMessage({'type': PushNotificationType.message});
+
+      expect(result.containsKey('server_url'), isFalse);
+      expect(result.containsKey('channel_id'), isFalse);
+      expect(result.containsKey('root_id'), isFalse);
+      expect(result.containsKey('is_crt_enabled'), isFalse);
+    });
+
+    test('message stable fields are preserved in normalized result', () {
+      final result = normalizeWebForegroundMessage({
+        'server_url': 'https://nexo.example.com',
+        'channel_id': 'ch-1',
+        'server_id': 'srv-99',
+        'ack_id': 'ack-42',
+        'post_id': 'post-77',
+        'signature': 'sig-abc',
+        'id_loaded': 'true',
+        'data': {'key': 'value'},
+      });
+
+      expect(result['server_url'], 'https://nexo.example.com');
+      expect(result['channel_id'], 'ch-1');
+      expect(result['server_id'], 'srv-99');
+      expect(result['ack_id'], 'ack-42');
+      expect(result['post_id'], 'post-77');
+      expect(result['signature'], 'sig-abc');
+      expect(result['id_loaded'], 'true');
+      expect(result['data'], {'key': 'value'});
+    });
+
+    test('unknown extra fields from payload are preserved', () {
+      final result = normalizeWebForegroundMessage({
+        'custom_field': 'custom_value',
+        'another': 123,
+      });
+
+      expect(result['custom_field'], 'custom_value');
+      expect(result['another'], 123);
+    });
+  });
 }