From 67415a9d70a5ff355dc9f1e070d7d8315e3e292f Mon Sep 17 00:00:00 2001
From: Patrick Pimentel <ppimentel@bitwarden.com>
Date: Tue, 22 Jul 2025 15:24:10 -0400
Subject: [PATCH] docs(notification-processing): [PM-19877] System Notification
 Implementation - Added markdown document.

---
 .../browser-system-notification.service.ts    |  2 -
 libs/common/src/platform/actions/README.md    | 40 +++++++++++++++++++
 .../src/platform/actions/actions-service.ts   | 19 ---------
 3 files changed, 40 insertions(+), 21 deletions(-)
 create mode 100644 libs/common/src/platform/actions/README.md

diff --git a/apps/browser/src/platform/system-notifications/browser-system-notification.service.ts b/apps/browser/src/platform/system-notifications/browser-system-notification.service.ts
index 2fe3196eb18..b2a73c0d2f0 100644
--- a/apps/browser/src/platform/system-notifications/browser-system-notification.service.ts
+++ b/apps/browser/src/platform/system-notifications/browser-system-notification.service.ts
@@ -60,8 +60,6 @@ export class BrowserSystemNotificationService implements SystemNotificationsServ
 
           break;
         case DeviceType.FirefoxExtension:
-          this.logService.info("Creating firefox notification");
-
           await browser.notifications.create(createInfo.id, {
             iconUrl: "https://avatars.githubusercontent.com/u/15990069?s=200",
             message: createInfo.title,
diff --git a/libs/common/src/platform/actions/README.md b/libs/common/src/platform/actions/README.md
new file mode 100644
index 00000000000..179fc203360
--- /dev/null
+++ b/libs/common/src/platform/actions/README.md
@@ -0,0 +1,40 @@
+# Platform Actions API
+
+## ActionsService.openPopup()
+
+This document outlines the current behavior of `ActionsService.openPopup()` across different browsers, specifically in two contexts:
+
+- **Window Context**: When the call is triggered from an active browser window (e.g., from a tab's script).
+- **Background Service Worker Context**: When the call is made from a background context, such as a service worker.
+
+The `openPopup()` method has limitations in some environments due to browser-specific restrictions or bugs. Below is a compatibility chart detailing the observed behavior.
+
+---
+
+## Compatibility Table
+
+| Browser | Window Context      | Background Service Worker Context |
+| ------- | ------------------- | --------------------------------- |
+| Safari  | ✅ Works            | ❌ Fails                          |
+| Firefox | ❌ Fails            | ❌ Fails                          |
+| Chrome  | ✅ Works            | ✅ Works                          |
+| Edge    | 🟡 Untested         | 🟡 Untested                       |
+| Vivaldi | ⚠️ Ambiguous (Bug?) | ⚠️ Ambiguous (Bug?)               |
+| Opera   | ✅ Works            | ❌ Fails silently                 |
+
+---
+
+## Notes
+
+- **Safari**: Only works when `openPopup()` is triggered from a window context. Attempts from background service workers fail.
+- **Firefox**: Does not appear to support `openPopup()` in either context.
+- **Chrome**: Fully functional in both contexts.
+- **Edge**: Behavior has not been tested.
+- **Vivaldi**: `openPopup()` results in an error that _might_ be related to running in a background context, but the cause is currently unclear.
+- **Opera**: Works from window context. Background calls fail silently with no error message.
+
+---
+
+## Summary
+
+When implementing `ActionsService.openPopup()`, prefer triggering it from a window context whenever possible to maximize cross-browser compatibility. Full background service worker support is only reliable in **Chrome**.
diff --git a/libs/common/src/platform/actions/actions-service.ts b/libs/common/src/platform/actions/actions-service.ts
index 602aee7432f..499f727ac81 100644
--- a/libs/common/src/platform/actions/actions-service.ts
+++ b/libs/common/src/platform/actions/actions-service.ts
@@ -1,25 +1,6 @@
 export abstract class ActionsService {
   /**
    * Opens the popup if it is supported.
-   *
-   * --- Limitations ---
-   *
-   * These are conditions that work where can open a popup programmatically from:
-   *
-   * Safari Web Browser -> Safari Extension
-   *   - Requires gesture
-   * Chrome Web Browser -> Chrome Extension
-   * Chrome Extension Service Worker -> Chrome Extension
-   *
-   * These are conditions that are known to not work:
-   * Firefox Web Browser -> Firefox Extension
-   * Vivaldi Extension Background Service Worker -> Vivaldi Extension
-   * Safari Extension Background Service Worker -> Safari Extension
-   * Firefox Extension Background Service Worker -> Firefox Extension
-   * Opera Extension Background Service Worker -> Opera Extension
-   *
-   * These are unknown conditions:
-   * Edge
    */
   abstract openPopup(): Promise<void>;
 }