From 062371b919af5d477ebadab4d020697ef71a87f8 Mon Sep 17 00:00:00 2001 From: zoumo Date: Sat, 14 Feb 2026 16:44:49 +0800 Subject: [PATCH 1/7] fix(desktop): register with macOS Notification Center at startup On macOS 26.x, the app was not appearing in System Settings > Notifications because it never explicitly registered with Notification Center. Electron's Notification API doesn't have a requestPermission() method. Registration happens implicitly when notification.show() is called. This fix shows a silent notification at startup to force registration, then immediately closes it. The app will now appear in System Settings and notifications will be delivered properly. Fixes #1461 --- apps/desktop/src/main/windows/main.ts | 28 ++++ .../macos-notification-center-registration.md | 150 ++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 docs/solutions/integration-issues/macos-notification-center-registration.md diff --git a/apps/desktop/src/main/windows/main.ts b/apps/desktop/src/main/windows/main.ts index 96ea98c409d..0d659df1c64 100644 --- a/apps/desktop/src/main/windows/main.ts +++ b/apps/desktop/src/main/windows/main.ts @@ -180,6 +180,34 @@ export async function MainWindow() { }); notificationManager.start(); + // Register with macOS Notification Center on startup + // This ensures the app appears in System Settings > Notifications + // Fixes https://github.com/superset-sh/superset/issues/1461 + if (PLATFORM.IS_MAC && Notification.isSupported()) { + const registrationNotification = new Notification({ + title: productName, + body: " ", + silent: true, + }); + + let handled = false; + const cleanup = () => { + if (handled) return; + handled = true; + registrationNotification.close(); + }; + + registrationNotification.on("show", () => { + cleanup(); + console.log("[notifications] Registered with Notification Center"); + }); + + // Fallback timeout in case macOS doesn't fire events + setTimeout(cleanup, 1000); + + registrationNotification.show(); + } + notificationsEmitter.on( NOTIFICATION_EVENTS.AGENT_LIFECYCLE, (event: AgentLifecycleEvent) => { diff --git a/docs/solutions/integration-issues/macos-notification-center-registration.md b/docs/solutions/integration-issues/macos-notification-center-registration.md new file mode 100644 index 00000000000..be0b13ea693 --- /dev/null +++ b/docs/solutions/integration-issues/macos-notification-center-registration.md @@ -0,0 +1,150 @@ +--- +title: "macOS 26 Notification Center Registration" +category: integration-issues +tags: [electron, notifications, macos, notification-center] +module: Desktop +platform: macOS 26.x +symptom: "App missing from System Settings > Notifications, notifications not delivered" +root_cause: "No explicit registration with Notification Center on app startup" +solution: "Show silent notification at startup to trigger registration" +date: 2026-02-14 +github_issue: 1461 +--- + +# macOS 26 Notification Center Registration + +## Problem + +On macOS 26.x (Tahoe), the Superset desktop app was not appearing in **System Settings > Notifications**, causing: +- No notifications delivered when tasks complete +- No task status indicators (green progress bar) visible +- Users unable to configure notification preferences for the app + +This issue affected macOS 26.2 specifically. Older macOS versions (13, 15) worked correctly. + +## Root Cause + +Electron's Notification API behaves differently from web browsers: + +1. **No explicit permission API** - Unlike web's `Notification.requestPermission()`, Electron has no such method +2. **Implicit registration** - Registration with macOS Notification Center happens when `notification.show()` is called +3. **Missing trigger** - The app only checked `Notification.isSupported()` but never actually showed a notification +4. **macOS 26 changes** - New "Liquid Glass" notification architecture may require more explicit registration + +### Key Misconceptions Corrected + +| Assumption | Reality | +|------------|---------| +| Need entitlements for notifications | NOT required for notifications on macOS | +| `notification.on("error", ...)` exists | Only `failed` event exists (Windows only) | +| Permission prompt appears automatically | Registration is implicit via `show()` | + +## Solution + +Show a silent notification at app startup to force registration with macOS Notification Center. The notification is closed immediately after showing. + +### Code + +```typescript +// apps/desktop/src/main/windows/main.ts +// After notificationManager.start() + +// Register with macOS Notification Center on startup +// This ensures the app appears in System Settings > Notifications +// Fixes https://github.com/superset-sh/superset/issues/1461 +if (PLATFORM.IS_MAC && Notification.isSupported()) { + const registrationNotification = new Notification({ + title: productName, + body: " ", + silent: true, + }); + + let handled = false; + const cleanup = () => { + if (handled) return; + handled = true; + registrationNotification.close(); + }; + + registrationNotification.on("show", () => { + cleanup(); + console.log("[notifications] Registered with Notification Center"); + }); + + // Fallback timeout in case macOS doesn't fire events + setTimeout(cleanup, 1000); + + registrationNotification.show(); +} +``` + +### Why This Works + +1. `notification.show()` triggers macOS Notification Center registration +2. The `show` event fires when notification is displayed +3. Cleanup closes the notification immediately (invisible to user) +4. App now appears in System Settings > Notifications +5. Future notifications work normally + +## Files Modified + +- `apps/desktop/src/main/windows/main.ts` - Added registration code (~25 lines) + +## Testing + +### Verification Steps + +1. Launch the app on macOS 26.x +2. Open **System Settings > Notifications** +3. Confirm "Superset" appears in the application list +4. Run a task and verify notifications are delivered + +### Test Checklist + +- [ ] Fresh install test: Delete app, reinstall, verify registration +- [ ] Permission denied test: Disable notifications, verify graceful handling +- [ ] macOS regression test: Test on macOS 13/15 to ensure no breakage +- [ ] Do Not Disturb test: Enable Focus mode, verify notifications queue correctly + +### Debug Mode + +Enable extra logging for notification debugging: + +```bash +ELECTRON_DEBUG_NOTIFICATIONS=1 bun run dev +``` + +## Prevention + +### Code Review Points + +1. **Never use `notification.on("error", ...)`** - This event doesn't exist in Electron's Notification API +2. **Always use `productName`** - Avoid hardcoded app name strings +3. **Include fallback timeout** - Ensures cleanup even if events don't fire +4. **Use `handled` flag** - Prevents double cleanup scenarios + +### Electron Notification Events Reference + +| Event | Platform | Description | +|-------|----------|-------------| +| `show` | All | Emitted when notification is displayed | +| `click` | All | User clicked notification | +| `close` | All | Notification closed | +| `failed` | Windows only | Error during show | +| `action` | macOS | Button click | +| `reply` | macOS | Inline reply | + +## Related Issues + +- [GitHub #1461](https://github.com/superset-sh/superset/issues/1461) - Original bug report + +## References + +- [Electron Notification API](https://www.electronjs.org/docs/latest/api/notification) +- [Electron Notifications Tutorial](https://www.electronjs.org/docs/latest/tutorial/notifications) + +## Notes + +- The related macOS 26.3 "non-stop notifications" issue is a separate bug in notification deduplication logic +- No entitlements changes were required for this fix +- Content sanitization could be added if sensitive data appears in notifications (fix data flow, not display) \ No newline at end of file From f448a3fce6e4beb5de8613d31374164648fdabd8 Mon Sep 17 00:00:00 2001 From: zoumo Date: Sat, 14 Feb 2026 17:06:27 +0800 Subject: [PATCH 2/7] fix(docs): use correct debug environment variable Update debug command from ELECTRON_DEBUG_NOTIFICATIONS=1 to SUPERSET_DEBUG=1 to match the actual debug implementation in apps/desktop/src/shared/debug.ts --- .../macos-notification-center-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/solutions/integration-issues/macos-notification-center-registration.md b/docs/solutions/integration-issues/macos-notification-center-registration.md index be0b13ea693..ba292f9bf9a 100644 --- a/docs/solutions/integration-issues/macos-notification-center-registration.md +++ b/docs/solutions/integration-issues/macos-notification-center-registration.md @@ -111,7 +111,7 @@ if (PLATFORM.IS_MAC && Notification.isSupported()) { Enable extra logging for notification debugging: ```bash -ELECTRON_DEBUG_NOTIFICATIONS=1 bun run dev +SUPERSET_DEBUG=1 bun run desktop ``` ## Prevention From 6f516f4e9b9a53999b1b28a86f51a3ab981a6b06 Mon Sep 17 00:00:00 2001 From: zoumo Date: Sat, 14 Feb 2026 16:44:49 +0800 Subject: [PATCH 3/7] fix(desktop): register with macOS Notification Center at startup On macOS 26.x, the app was not appearing in System Settings > Notifications because it never explicitly registered with Notification Center. Electron's Notification API doesn't have a requestPermission() method. Registration happens implicitly when notification.show() is called. This fix shows a silent notification at startup to force registration, then immediately closes it. The app will now appear in System Settings and notifications will be delivered properly. Fixes #1461 --- apps/desktop/src/main/windows/main.ts | 28 ++++ .../macos-notification-center-registration.md | 150 ++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 docs/solutions/integration-issues/macos-notification-center-registration.md diff --git a/apps/desktop/src/main/windows/main.ts b/apps/desktop/src/main/windows/main.ts index 96ea98c409d..0d659df1c64 100644 --- a/apps/desktop/src/main/windows/main.ts +++ b/apps/desktop/src/main/windows/main.ts @@ -180,6 +180,34 @@ export async function MainWindow() { }); notificationManager.start(); + // Register with macOS Notification Center on startup + // This ensures the app appears in System Settings > Notifications + // Fixes https://github.com/superset-sh/superset/issues/1461 + if (PLATFORM.IS_MAC && Notification.isSupported()) { + const registrationNotification = new Notification({ + title: productName, + body: " ", + silent: true, + }); + + let handled = false; + const cleanup = () => { + if (handled) return; + handled = true; + registrationNotification.close(); + }; + + registrationNotification.on("show", () => { + cleanup(); + console.log("[notifications] Registered with Notification Center"); + }); + + // Fallback timeout in case macOS doesn't fire events + setTimeout(cleanup, 1000); + + registrationNotification.show(); + } + notificationsEmitter.on( NOTIFICATION_EVENTS.AGENT_LIFECYCLE, (event: AgentLifecycleEvent) => { diff --git a/docs/solutions/integration-issues/macos-notification-center-registration.md b/docs/solutions/integration-issues/macos-notification-center-registration.md new file mode 100644 index 00000000000..be0b13ea693 --- /dev/null +++ b/docs/solutions/integration-issues/macos-notification-center-registration.md @@ -0,0 +1,150 @@ +--- +title: "macOS 26 Notification Center Registration" +category: integration-issues +tags: [electron, notifications, macos, notification-center] +module: Desktop +platform: macOS 26.x +symptom: "App missing from System Settings > Notifications, notifications not delivered" +root_cause: "No explicit registration with Notification Center on app startup" +solution: "Show silent notification at startup to trigger registration" +date: 2026-02-14 +github_issue: 1461 +--- + +# macOS 26 Notification Center Registration + +## Problem + +On macOS 26.x (Tahoe), the Superset desktop app was not appearing in **System Settings > Notifications**, causing: +- No notifications delivered when tasks complete +- No task status indicators (green progress bar) visible +- Users unable to configure notification preferences for the app + +This issue affected macOS 26.2 specifically. Older macOS versions (13, 15) worked correctly. + +## Root Cause + +Electron's Notification API behaves differently from web browsers: + +1. **No explicit permission API** - Unlike web's `Notification.requestPermission()`, Electron has no such method +2. **Implicit registration** - Registration with macOS Notification Center happens when `notification.show()` is called +3. **Missing trigger** - The app only checked `Notification.isSupported()` but never actually showed a notification +4. **macOS 26 changes** - New "Liquid Glass" notification architecture may require more explicit registration + +### Key Misconceptions Corrected + +| Assumption | Reality | +|------------|---------| +| Need entitlements for notifications | NOT required for notifications on macOS | +| `notification.on("error", ...)` exists | Only `failed` event exists (Windows only) | +| Permission prompt appears automatically | Registration is implicit via `show()` | + +## Solution + +Show a silent notification at app startup to force registration with macOS Notification Center. The notification is closed immediately after showing. + +### Code + +```typescript +// apps/desktop/src/main/windows/main.ts +// After notificationManager.start() + +// Register with macOS Notification Center on startup +// This ensures the app appears in System Settings > Notifications +// Fixes https://github.com/superset-sh/superset/issues/1461 +if (PLATFORM.IS_MAC && Notification.isSupported()) { + const registrationNotification = new Notification({ + title: productName, + body: " ", + silent: true, + }); + + let handled = false; + const cleanup = () => { + if (handled) return; + handled = true; + registrationNotification.close(); + }; + + registrationNotification.on("show", () => { + cleanup(); + console.log("[notifications] Registered with Notification Center"); + }); + + // Fallback timeout in case macOS doesn't fire events + setTimeout(cleanup, 1000); + + registrationNotification.show(); +} +``` + +### Why This Works + +1. `notification.show()` triggers macOS Notification Center registration +2. The `show` event fires when notification is displayed +3. Cleanup closes the notification immediately (invisible to user) +4. App now appears in System Settings > Notifications +5. Future notifications work normally + +## Files Modified + +- `apps/desktop/src/main/windows/main.ts` - Added registration code (~25 lines) + +## Testing + +### Verification Steps + +1. Launch the app on macOS 26.x +2. Open **System Settings > Notifications** +3. Confirm "Superset" appears in the application list +4. Run a task and verify notifications are delivered + +### Test Checklist + +- [ ] Fresh install test: Delete app, reinstall, verify registration +- [ ] Permission denied test: Disable notifications, verify graceful handling +- [ ] macOS regression test: Test on macOS 13/15 to ensure no breakage +- [ ] Do Not Disturb test: Enable Focus mode, verify notifications queue correctly + +### Debug Mode + +Enable extra logging for notification debugging: + +```bash +ELECTRON_DEBUG_NOTIFICATIONS=1 bun run dev +``` + +## Prevention + +### Code Review Points + +1. **Never use `notification.on("error", ...)`** - This event doesn't exist in Electron's Notification API +2. **Always use `productName`** - Avoid hardcoded app name strings +3. **Include fallback timeout** - Ensures cleanup even if events don't fire +4. **Use `handled` flag** - Prevents double cleanup scenarios + +### Electron Notification Events Reference + +| Event | Platform | Description | +|-------|----------|-------------| +| `show` | All | Emitted when notification is displayed | +| `click` | All | User clicked notification | +| `close` | All | Notification closed | +| `failed` | Windows only | Error during show | +| `action` | macOS | Button click | +| `reply` | macOS | Inline reply | + +## Related Issues + +- [GitHub #1461](https://github.com/superset-sh/superset/issues/1461) - Original bug report + +## References + +- [Electron Notification API](https://www.electronjs.org/docs/latest/api/notification) +- [Electron Notifications Tutorial](https://www.electronjs.org/docs/latest/tutorial/notifications) + +## Notes + +- The related macOS 26.3 "non-stop notifications" issue is a separate bug in notification deduplication logic +- No entitlements changes were required for this fix +- Content sanitization could be added if sensitive data appears in notifications (fix data flow, not display) \ No newline at end of file From 638d068b5ce79dcab9cd49ffd6f134e98f09668f Mon Sep 17 00:00:00 2001 From: zoumo Date: Sat, 14 Feb 2026 17:06:27 +0800 Subject: [PATCH 4/7] fix(docs): use correct debug environment variable Update debug command from ELECTRON_DEBUG_NOTIFICATIONS=1 to SUPERSET_DEBUG=1 to match the actual debug implementation in apps/desktop/src/shared/debug.ts --- .../macos-notification-center-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/solutions/integration-issues/macos-notification-center-registration.md b/docs/solutions/integration-issues/macos-notification-center-registration.md index be0b13ea693..ba292f9bf9a 100644 --- a/docs/solutions/integration-issues/macos-notification-center-registration.md +++ b/docs/solutions/integration-issues/macos-notification-center-registration.md @@ -111,7 +111,7 @@ if (PLATFORM.IS_MAC && Notification.isSupported()) { Enable extra logging for notification debugging: ```bash -ELECTRON_DEBUG_NOTIFICATIONS=1 bun run dev +SUPERSET_DEBUG=1 bun run desktop ``` ## Prevention From 663e8b434515c987ecea41d74edc9ef836cb7542 Mon Sep 17 00:00:00 2001 From: Kiet Ho Date: Sat, 14 Feb 2026 01:19:23 -0800 Subject: [PATCH 5/7] Move to startup time --- apps/desktop/src/main/index.ts | 44 ++++- apps/desktop/src/main/windows/main.ts | 28 ---- .../macos-notification-center-registration.md | 150 ------------------ 3 files changed, 42 insertions(+), 180 deletions(-) delete mode 100644 docs/solutions/integration-issues/macos-notification-center-registration.md diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts index 976d45b3982..9a712e2cdb2 100644 --- a/apps/desktop/src/main/index.ts +++ b/apps/desktop/src/main/index.ts @@ -1,13 +1,25 @@ import path from "node:path"; import { pathToFileURL } from "node:url"; import { settings } from "@superset/local-db"; -import { app, BrowserWindow, dialog, net, protocol, session } from "electron"; +import { + app, + BrowserWindow, + dialog, + Notification, + net, + protocol, + session, +} from "electron"; import { makeAppSetup } from "lib/electron-app/factories/app/setup"; import { handleAuthCallback, parseAuthDeepLink, } from "lib/trpc/routers/auth/utils/auth-functions"; -import { DEFAULT_CONFIRM_ON_QUIT, PROTOCOL_SCHEME } from "shared/constants"; +import { + DEFAULT_CONFIRM_ON_QUIT, + PLATFORM, + PROTOCOL_SCHEME, +} from "shared/constants"; import { getWorkspaceName } from "shared/env.shared"; import { setupAgentHooks } from "./lib/agent-setup"; import { initAppState } from "./lib/app-state"; @@ -82,6 +94,33 @@ function focusMainWindow(): void { } } +function registerWithMacOSNotificationCenter() { + if (!PLATFORM.IS_MAC || !Notification.isSupported()) return; + + const registrationNotification = new Notification({ + title: app.name, + body: " ", + silent: true, + }); + + let handled = false; + const cleanup = () => { + if (handled) return; + handled = true; + registrationNotification.close(); + }; + + registrationNotification.on("show", () => { + cleanup(); + console.log("[notifications] Registered with Notification Center"); + }); + + // Fallback timeout in case macOS doesn't fire events + setTimeout(cleanup, 1000); + + registrationNotification.show(); +} + // macOS open-url can fire before the window exists (cold-start via protocol link). // Queue the URL and process it after initialization. let pendingDeepLinkUrl: string | null = null; @@ -217,6 +256,7 @@ if (!gotTheLock) { (async () => { await app.whenReady(); + registerWithMacOSNotificationCenter(); // Must register on both default session and the app's custom partition const iconProtocolHandler = (request: Request) => { diff --git a/apps/desktop/src/main/windows/main.ts b/apps/desktop/src/main/windows/main.ts index 0d659df1c64..96ea98c409d 100644 --- a/apps/desktop/src/main/windows/main.ts +++ b/apps/desktop/src/main/windows/main.ts @@ -180,34 +180,6 @@ export async function MainWindow() { }); notificationManager.start(); - // Register with macOS Notification Center on startup - // This ensures the app appears in System Settings > Notifications - // Fixes https://github.com/superset-sh/superset/issues/1461 - if (PLATFORM.IS_MAC && Notification.isSupported()) { - const registrationNotification = new Notification({ - title: productName, - body: " ", - silent: true, - }); - - let handled = false; - const cleanup = () => { - if (handled) return; - handled = true; - registrationNotification.close(); - }; - - registrationNotification.on("show", () => { - cleanup(); - console.log("[notifications] Registered with Notification Center"); - }); - - // Fallback timeout in case macOS doesn't fire events - setTimeout(cleanup, 1000); - - registrationNotification.show(); - } - notificationsEmitter.on( NOTIFICATION_EVENTS.AGENT_LIFECYCLE, (event: AgentLifecycleEvent) => { diff --git a/docs/solutions/integration-issues/macos-notification-center-registration.md b/docs/solutions/integration-issues/macos-notification-center-registration.md deleted file mode 100644 index ba292f9bf9a..00000000000 --- a/docs/solutions/integration-issues/macos-notification-center-registration.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "macOS 26 Notification Center Registration" -category: integration-issues -tags: [electron, notifications, macos, notification-center] -module: Desktop -platform: macOS 26.x -symptom: "App missing from System Settings > Notifications, notifications not delivered" -root_cause: "No explicit registration with Notification Center on app startup" -solution: "Show silent notification at startup to trigger registration" -date: 2026-02-14 -github_issue: 1461 ---- - -# macOS 26 Notification Center Registration - -## Problem - -On macOS 26.x (Tahoe), the Superset desktop app was not appearing in **System Settings > Notifications**, causing: -- No notifications delivered when tasks complete -- No task status indicators (green progress bar) visible -- Users unable to configure notification preferences for the app - -This issue affected macOS 26.2 specifically. Older macOS versions (13, 15) worked correctly. - -## Root Cause - -Electron's Notification API behaves differently from web browsers: - -1. **No explicit permission API** - Unlike web's `Notification.requestPermission()`, Electron has no such method -2. **Implicit registration** - Registration with macOS Notification Center happens when `notification.show()` is called -3. **Missing trigger** - The app only checked `Notification.isSupported()` but never actually showed a notification -4. **macOS 26 changes** - New "Liquid Glass" notification architecture may require more explicit registration - -### Key Misconceptions Corrected - -| Assumption | Reality | -|------------|---------| -| Need entitlements for notifications | NOT required for notifications on macOS | -| `notification.on("error", ...)` exists | Only `failed` event exists (Windows only) | -| Permission prompt appears automatically | Registration is implicit via `show()` | - -## Solution - -Show a silent notification at app startup to force registration with macOS Notification Center. The notification is closed immediately after showing. - -### Code - -```typescript -// apps/desktop/src/main/windows/main.ts -// After notificationManager.start() - -// Register with macOS Notification Center on startup -// This ensures the app appears in System Settings > Notifications -// Fixes https://github.com/superset-sh/superset/issues/1461 -if (PLATFORM.IS_MAC && Notification.isSupported()) { - const registrationNotification = new Notification({ - title: productName, - body: " ", - silent: true, - }); - - let handled = false; - const cleanup = () => { - if (handled) return; - handled = true; - registrationNotification.close(); - }; - - registrationNotification.on("show", () => { - cleanup(); - console.log("[notifications] Registered with Notification Center"); - }); - - // Fallback timeout in case macOS doesn't fire events - setTimeout(cleanup, 1000); - - registrationNotification.show(); -} -``` - -### Why This Works - -1. `notification.show()` triggers macOS Notification Center registration -2. The `show` event fires when notification is displayed -3. Cleanup closes the notification immediately (invisible to user) -4. App now appears in System Settings > Notifications -5. Future notifications work normally - -## Files Modified - -- `apps/desktop/src/main/windows/main.ts` - Added registration code (~25 lines) - -## Testing - -### Verification Steps - -1. Launch the app on macOS 26.x -2. Open **System Settings > Notifications** -3. Confirm "Superset" appears in the application list -4. Run a task and verify notifications are delivered - -### Test Checklist - -- [ ] Fresh install test: Delete app, reinstall, verify registration -- [ ] Permission denied test: Disable notifications, verify graceful handling -- [ ] macOS regression test: Test on macOS 13/15 to ensure no breakage -- [ ] Do Not Disturb test: Enable Focus mode, verify notifications queue correctly - -### Debug Mode - -Enable extra logging for notification debugging: - -```bash -SUPERSET_DEBUG=1 bun run desktop -``` - -## Prevention - -### Code Review Points - -1. **Never use `notification.on("error", ...)`** - This event doesn't exist in Electron's Notification API -2. **Always use `productName`** - Avoid hardcoded app name strings -3. **Include fallback timeout** - Ensures cleanup even if events don't fire -4. **Use `handled` flag** - Prevents double cleanup scenarios - -### Electron Notification Events Reference - -| Event | Platform | Description | -|-------|----------|-------------| -| `show` | All | Emitted when notification is displayed | -| `click` | All | User clicked notification | -| `close` | All | Notification closed | -| `failed` | Windows only | Error during show | -| `action` | macOS | Button click | -| `reply` | macOS | Inline reply | - -## Related Issues - -- [GitHub #1461](https://github.com/superset-sh/superset/issues/1461) - Original bug report - -## References - -- [Electron Notification API](https://www.electronjs.org/docs/latest/api/notification) -- [Electron Notifications Tutorial](https://www.electronjs.org/docs/latest/tutorial/notifications) - -## Notes - -- The related macOS 26.3 "non-stop notifications" issue is a separate bug in notification deduplication logic -- No entitlements changes were required for this fix -- Content sanitization could be added if sensitive data appears in notifications (fix data flow, not display) \ No newline at end of file From b2ba54507b6a1af3c8171d923cf32cbb8ead91ef Mon Sep 17 00:00:00 2001 From: zoumo Date: Sat, 14 Feb 2026 17:24:58 +0800 Subject: [PATCH 6/7] docs: add reliability caveat for notification close event Note that the close event may not fire on all platforms. --- .../macos-notification-center-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/solutions/integration-issues/macos-notification-center-registration.md b/docs/solutions/integration-issues/macos-notification-center-registration.md index ba292f9bf9a..61379e2f7c7 100644 --- a/docs/solutions/integration-issues/macos-notification-center-registration.md +++ b/docs/solutions/integration-issues/macos-notification-center-registration.md @@ -129,7 +129,7 @@ SUPERSET_DEBUG=1 bun run desktop |-------|----------|-------------| | `show` | All | Emitted when notification is displayed | | `click` | All | User clicked notification | -| `close` | All | Notification closed | +| `close` | All | Notification closed (may not fire on all platforms — reliability varies) | | `failed` | Windows only | Error during show | | `action` | macOS | Button click | | `reply` | macOS | Inline reply | From 7f14e3db7c311859d2deeb6a20d3b7fb13997b8f Mon Sep 17 00:00:00 2001 From: Kiet Ho Date: Sat, 14 Feb 2026 01:33:43 -0800 Subject: [PATCH 7/7] fix(desktop): keep macOS notification registration at app startup --- apps/desktop/src/main/windows/main.ts | 28 ---- .../macos-notification-center-registration.md | 150 ------------------ 2 files changed, 178 deletions(-) delete mode 100644 docs/solutions/integration-issues/macos-notification-center-registration.md diff --git a/apps/desktop/src/main/windows/main.ts b/apps/desktop/src/main/windows/main.ts index 0d659df1c64..96ea98c409d 100644 --- a/apps/desktop/src/main/windows/main.ts +++ b/apps/desktop/src/main/windows/main.ts @@ -180,34 +180,6 @@ export async function MainWindow() { }); notificationManager.start(); - // Register with macOS Notification Center on startup - // This ensures the app appears in System Settings > Notifications - // Fixes https://github.com/superset-sh/superset/issues/1461 - if (PLATFORM.IS_MAC && Notification.isSupported()) { - const registrationNotification = new Notification({ - title: productName, - body: " ", - silent: true, - }); - - let handled = false; - const cleanup = () => { - if (handled) return; - handled = true; - registrationNotification.close(); - }; - - registrationNotification.on("show", () => { - cleanup(); - console.log("[notifications] Registered with Notification Center"); - }); - - // Fallback timeout in case macOS doesn't fire events - setTimeout(cleanup, 1000); - - registrationNotification.show(); - } - notificationsEmitter.on( NOTIFICATION_EVENTS.AGENT_LIFECYCLE, (event: AgentLifecycleEvent) => { diff --git a/docs/solutions/integration-issues/macos-notification-center-registration.md b/docs/solutions/integration-issues/macos-notification-center-registration.md deleted file mode 100644 index 61379e2f7c7..00000000000 --- a/docs/solutions/integration-issues/macos-notification-center-registration.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "macOS 26 Notification Center Registration" -category: integration-issues -tags: [electron, notifications, macos, notification-center] -module: Desktop -platform: macOS 26.x -symptom: "App missing from System Settings > Notifications, notifications not delivered" -root_cause: "No explicit registration with Notification Center on app startup" -solution: "Show silent notification at startup to trigger registration" -date: 2026-02-14 -github_issue: 1461 ---- - -# macOS 26 Notification Center Registration - -## Problem - -On macOS 26.x (Tahoe), the Superset desktop app was not appearing in **System Settings > Notifications**, causing: -- No notifications delivered when tasks complete -- No task status indicators (green progress bar) visible -- Users unable to configure notification preferences for the app - -This issue affected macOS 26.2 specifically. Older macOS versions (13, 15) worked correctly. - -## Root Cause - -Electron's Notification API behaves differently from web browsers: - -1. **No explicit permission API** - Unlike web's `Notification.requestPermission()`, Electron has no such method -2. **Implicit registration** - Registration with macOS Notification Center happens when `notification.show()` is called -3. **Missing trigger** - The app only checked `Notification.isSupported()` but never actually showed a notification -4. **macOS 26 changes** - New "Liquid Glass" notification architecture may require more explicit registration - -### Key Misconceptions Corrected - -| Assumption | Reality | -|------------|---------| -| Need entitlements for notifications | NOT required for notifications on macOS | -| `notification.on("error", ...)` exists | Only `failed` event exists (Windows only) | -| Permission prompt appears automatically | Registration is implicit via `show()` | - -## Solution - -Show a silent notification at app startup to force registration with macOS Notification Center. The notification is closed immediately after showing. - -### Code - -```typescript -// apps/desktop/src/main/windows/main.ts -// After notificationManager.start() - -// Register with macOS Notification Center on startup -// This ensures the app appears in System Settings > Notifications -// Fixes https://github.com/superset-sh/superset/issues/1461 -if (PLATFORM.IS_MAC && Notification.isSupported()) { - const registrationNotification = new Notification({ - title: productName, - body: " ", - silent: true, - }); - - let handled = false; - const cleanup = () => { - if (handled) return; - handled = true; - registrationNotification.close(); - }; - - registrationNotification.on("show", () => { - cleanup(); - console.log("[notifications] Registered with Notification Center"); - }); - - // Fallback timeout in case macOS doesn't fire events - setTimeout(cleanup, 1000); - - registrationNotification.show(); -} -``` - -### Why This Works - -1. `notification.show()` triggers macOS Notification Center registration -2. The `show` event fires when notification is displayed -3. Cleanup closes the notification immediately (invisible to user) -4. App now appears in System Settings > Notifications -5. Future notifications work normally - -## Files Modified - -- `apps/desktop/src/main/windows/main.ts` - Added registration code (~25 lines) - -## Testing - -### Verification Steps - -1. Launch the app on macOS 26.x -2. Open **System Settings > Notifications** -3. Confirm "Superset" appears in the application list -4. Run a task and verify notifications are delivered - -### Test Checklist - -- [ ] Fresh install test: Delete app, reinstall, verify registration -- [ ] Permission denied test: Disable notifications, verify graceful handling -- [ ] macOS regression test: Test on macOS 13/15 to ensure no breakage -- [ ] Do Not Disturb test: Enable Focus mode, verify notifications queue correctly - -### Debug Mode - -Enable extra logging for notification debugging: - -```bash -SUPERSET_DEBUG=1 bun run desktop -``` - -## Prevention - -### Code Review Points - -1. **Never use `notification.on("error", ...)`** - This event doesn't exist in Electron's Notification API -2. **Always use `productName`** - Avoid hardcoded app name strings -3. **Include fallback timeout** - Ensures cleanup even if events don't fire -4. **Use `handled` flag** - Prevents double cleanup scenarios - -### Electron Notification Events Reference - -| Event | Platform | Description | -|-------|----------|-------------| -| `show` | All | Emitted when notification is displayed | -| `click` | All | User clicked notification | -| `close` | All | Notification closed (may not fire on all platforms — reliability varies) | -| `failed` | Windows only | Error during show | -| `action` | macOS | Button click | -| `reply` | macOS | Inline reply | - -## Related Issues - -- [GitHub #1461](https://github.com/superset-sh/superset/issues/1461) - Original bug report - -## References - -- [Electron Notification API](https://www.electronjs.org/docs/latest/api/notification) -- [Electron Notifications Tutorial](https://www.electronjs.org/docs/latest/tutorial/notifications) - -## Notes - -- The related macOS 26.3 "non-stop notifications" issue is a separate bug in notification deduplication logic -- No entitlements changes were required for this fix -- Content sanitization could be added if sensitive data appears in notifications (fix data flow, not display) \ No newline at end of file