feat(web): notify 5 minutes before an upcoming event

e2e/onboarding/shortcut-showcase.spec.ts

@@ -57,6 +57,11 @@ test("the welcome-started practice runs create then D through graduation", async
     await page.keyboard.press("d");
   }
 
+  // Not a mission, so it carries no chip; N passes without prompting.
+  await expect(showcase).toContainText("Never miss a meeting");
+  await expect(showcase).not.toContainText("Mission 7 of");
+  await page.keyboard.press("n");
+
   await expect(showcase).toContainText("young cap'n");
   await page.keyboard.press("Enter");
   await expect(showcase).toHaveCount(0);
@@ -66,6 +71,39 @@ test("the welcome-started practice runs create then D through graduation", async
   ).toBeVisible();
 });
 
+test("taking the notifications offer opts in and moves on", async ({
+  page,
+  context,
+}) => {
+  // Granted up front so the offer resolves without a real browser prompt,
+  // which Playwright cannot click.
+  await context.grantPermissions(["notifications"]);
+  await page.goto("/week", { waitUntil: "domcontentloaded" });
+  await leaveWelcome(page);
+
+  const showcase = page.getByRole("region", { name: "Shortcut practice" });
+  await page.keyboard.press("c");
+  await page.keyboard.type("Practice Event");
+  await page.keyboard.press("Enter");
+
+  // D assists through the remaining missions to reach the offer.
+  for (let i = 0; i < 5; i += 1) {
+    await page.keyboard.press("d");
+  }
+
+  await expect(showcase).toContainText("Never miss a meeting");
+  await page.keyboard.press("Enter");
+
+  await expect(showcase).toContainText("young cap'n");
+  await expect
+    .poll(() =>
+      page.evaluate(() =>
+        localStorage.getItem("compass.notifications.enabled"),
+      ),
+    )
+    .toBe("true");
+});
+
 test("Skip to sign up leaves the practice for the signup form on step 1", async ({
   page,
 }) => {

packages/web/src/__tests__/helpers/web-test-seams.ts

@@ -20,6 +20,12 @@ import {
   type ToastApi,
   type ToastPort,
 } from "@web/common/utils/toast/toast.port";
+import {
+  type NotificationPort,
+  registerNotificationPort,
+  resetNotificationPort,
+} from "@web/notifications/notification.port";
+import { resetNotificationStoreForTests } from "@web/notifications/notification.store";
 import { mock } from "bun:test";
 
 export function createDefaultTestSessionPort(): SessionApiPort {
@@ -84,6 +90,48 @@ export function createTestToastPort() {
   };
 }
 
+/**
+ * jsdom has no Notification global, so without a seam every test would see an
+ * unsupported browser and the notification UI would silently vanish. The
+ * default port is supported but ungranted — the state a first-run user is in.
+ */
+export function createTestNotificationPort(options?: {
+  permission?: NotificationPermission;
+  /** What requestPermission resolves to; defaults to the current permission. */
+  respondWith?: NotificationPermission;
+  supported?: boolean;
+}) {
+  let permission: NotificationPermission = options?.permission ?? "default";
+  const permissionListeners = new Set<() => void>();
+
+  const show = mock();
+  const requestPermission = mock(async () => {
+    permission = options?.respondWith ?? permission;
+    return permission;
+  });
+
+  const setPermission = (next: NotificationPermission) => {
+    permission = next;
+    for (const listener of permissionListeners) listener();
+  };
+
+  const isSupported = () => options?.supported ?? true;
+
+  const port: NotificationPort = {
+    isSupported,
+    // Matches production: with no Notification API there is nothing to grant.
+    getPermission: () => (isSupported() ? permission : "denied"),
+    requestPermission,
+    show,
+    observePermission: (onChange) => {
+      permissionListeners.add(onChange);
+      return () => permissionListeners.delete(onChange);
+    },
+  };
+
+  return { port, setPermission, mocks: { show, requestPermission } };
+}
+
 export function createDefaultTestGoogleAuthorizationHook(): UseStartGoogleAuthorization {
   return () => ({
     loading: false,
@@ -110,6 +158,11 @@ export function createTestEmailPasswordPort() {
 export function installDefaultWebTestSeams(): void {
   registerSessionApiPort(createDefaultTestSessionPort());
   registerToastPort(createTestToastPort().port);
+  registerNotificationPort(createTestNotificationPort().port);
+  // Re-seed after the port is in place: store resets run in afterEach, while
+  // the previous test's port is still registered, so a test that granted
+  // permission would otherwise leak "granted" into the next one.
+  resetNotificationStoreForTests();
   registerUseStartGoogleAuthorizationForTests(
     createDefaultTestGoogleAuthorizationHook(),
   );
@@ -121,6 +174,7 @@ export function installDefaultWebTestSeams(): void {
 export function resetWebTestSeams(): void {
   resetSessionApiPort();
   resetToastPort();
+  resetNotificationPort();
   resetUseStartGoogleAuthorizationForTests();
   // AuthModal owns emailpassword reset — production SuperTokens patches XHR vs MSW.
   resetUseCompleteAuthenticationForTests();

packages/web/src/__tests__/utils/state/reset-stores.ts

@@ -33,6 +33,7 @@ import {
   useUndoHistoryStore,
 } from "@web/events/stores/undo.store";
 import { initialViewState, useViewStore } from "@web/events/stores/view.store";
+import { resetNotificationStoreForTests } from "@web/notifications/notification.store";
 import {
   initialSettingsState,
   useSettingsStore,
@@ -70,6 +71,7 @@ const storeResets: StoreReset[] = [
     useTimezoneDialogStore.setState({ isOpen: false, purpose: "pin" }, true),
   resetCollapsedAccountsStoreForTests,
   resetRecentCommandsStoreForTests,
+  resetNotificationStoreForTests,
   () => useFeedbackStore.setState(useFeedbackStore.getInitialState(), true),
   () => useShortcutShowcaseStore.setState(initialShortcutShowcaseState, true),
   () => useFirstEventPromptStore.setState(initialFirstEventPromptState, true),

packages/web/src/auth/posthog/track.ts

@@ -22,7 +22,10 @@ export type ProductEvent =
   | "trial_gate_shown"
   | "trial_gate_cta_clicked"
   | "billing_gate_shown"
-  | "billing_gate_cta_clicked";
+  | "billing_gate_cta_clicked"
+  | "notifications_enabled"
+  | "notifications_disabled"
+  | "notifications_enable_denied";
 
 /**
  * Fire-and-forget capture for the small set of product-activation events.

packages/web/src/common/constants/storage.constants.ts

@@ -37,7 +37,11 @@ type StorageKey =
   | "compass.timezone.time-travel"
   // Browser IANA id the pin-mismatch banner is snoozed for. Absent means the
   // banner can show. It returns when the browser zone no longer matches.
-  | "compass.timezone.mismatch-snoozed-browser";
+  | "compass.timezone.mismatch-snoozed-browser"
+  // Device-local opt-in for upcoming-event browser notifications. Only ever
+  // written "true" right after the browser grants permission, so a stale flag
+  // can never outlive a revoked grant (the permission is re-read on load).
+  | "compass.notifications.enabled";
 
 export const STORAGE_KEYS: Record<
   | "AUTH"
@@ -60,7 +64,8 @@ export const STORAGE_KEYS: Record<
   | "RECENT_COMMANDS"
   | "DEFAULT_TIMEZONE"
   | "TIME_TRAVEL_TIMEZONE"
-  | "TIMEZONE_MISMATCH_SNOOZED_BROWSER",
+  | "TIMEZONE_MISMATCH_SNOOZED_BROWSER"
+  | "NOTIFICATIONS_ENABLED",
   StorageKey
 > = {
   AUTH: "compass.auth",
@@ -88,4 +93,5 @@ export const STORAGE_KEYS: Record<
   TIME_TRAVEL_TIMEZONE: "compass.timezone.time-travel",
   TIMEZONE_MISMATCH_SNOOZED_BROWSER:
     "compass.timezone.mismatch-snoozed-browser",
+  NOTIFICATIONS_ENABLED: "compass.notifications.enabled",
 } as const;

packages/web/src/common/constants/toast.constants.ts

@@ -17,6 +17,7 @@ export const ACCOUNT_DISCONNECTED_TOAST_ID: Id = "account-disconnected";
 export const EXPORT_MY_DATA_TOAST_ID: Id = "export-my-data";
 export const LOGGED_OUT_TOAST_ID: Id = "logged-out";
 export const EVENT_SAVE_UNAVAILABLE_TOAST_ID: Id = "event-save-unavailable";
+export const NOTIFICATIONS_STATUS_TOAST_ID: Id = "notifications-status";
 
 const toastPalette: Record<
   ThemeName,

packages/web/src/components/CommandPalette/CommandPalette.tsx

@@ -34,6 +34,7 @@ import { shortcutShowcaseActions } from "@web/components/ShortcutShowcase/showca
 import { ShortcutKeys } from "@web/components/Shortcuts/ShortcutKeys";
 import { type EventMutationDependencies } from "@web/events/mutations/useEventMutations";
 import { useUndoRedo } from "@web/events/mutations/useUndoRedo";
+import { useNotificationCmdItems } from "@web/notifications/useNotificationCmdItems";
 import {
   selectIsCmdPaletteOpen,
   settingsActions,
@@ -297,6 +298,7 @@ export const CommandPalette = ({
   const logoutCmdItems = useLogoutCmdItems();
   const themeCmdItems = useThemeCmdItems();
   const timezoneCmdItems = useTimezoneCmdItems();
+  const notificationCmdItems = useNotificationCmdItems();
   const { undo, redo, canUndo, canRedo } = useUndoRedo(mutationDependencies);
   const recentCommandIds = useRecentCommandIds();
 
@@ -352,6 +354,7 @@ export const CommandPalette = ({
       heading: "Settings",
       items: [
         ...timezoneCmdItems,
+        ...notificationCmdItems,
         ...authCmdItems,
         ...showAccountsCmdItems,
         ...logoutCmdItems,
@@ -420,6 +423,9 @@ export const LifeCommandPalette = ({
           heading: "Appearance",
           items: themeCmdItems,
         },
+        // No event notifications here: the Life route sits outside the
+        // authenticated layout that mounts the notifier, so offering the
+        // toggle would promise nudges this route can never deliver.
         {
           id: "settings",
           heading: "Settings",