M5: Downloads notifications (toast + native, one bridge)

Adds the passive-nudge layer of the downloads watcher: when a file
lands in `~/Downloads`, fan out per the settings enum
`behavior.fileSystemWatching.downloadsNotifications` (`in-app | macos |
both | neither`, default `in-app`) to an in-app toast and/or a macOS
native notification.

- Add `tauri-plugin-notification` 2.3.3 (Rust + JS, both ≥14 days old
  on crates.io / npmjs.com); wire the plugin into `lib.rs`; add
  `notification:default` to `capabilities/default.json`.
- New `lib/downloads/event-bridge.svelte.ts`: one `download-detected`
  listener mounted from `(main)/+page.svelte`. Reads the mode per event,
  re-checks the FDA gate as defense in depth (the watcher already gates
  on it), asks the OS for notification permission the first time the
  macOS path is taken, surfaces a single INFO toast on denial without
  flipping the user's setting.
- New `lib/downloads/DownloadToastContent.svelte`: title with filename
  + size, optional "in Downloads/<subdir>/" line, snapshotted shortcut
  hint, "Jump to file" + "Stop showing these" actions, whole-body
  mouse-clickable but not keyboard-focusable (the buttons own
  keyboard activation independently).
- New `lib/downloads/notifications-mode.ts`: try/catch'd reader and
  writer for the setting key, plus the Settings deep-link target. The
  M7 registry entry isn't present yet; the wrapper safely falls back
  to `'in-app'` until M7 lands.
- New `revealPath(explorer, dir, name)` in `reveal.ts`: navigate to a
  SPECIFIC file's parent and select it, bypassing the latest-in-ring
  lookup. The toast uses this so a burst of downloads each lands the
  user on the file the toast was for, not whichever became "latest"
  while they were reading.
- New `lib/downloads/CLAUDE.md` covering architecture, the four
  dispatch branches, the snapshot-at-creation rule, the reveal-by-path
  vs reveal-latest distinction, and the FDA defense-in-depth path.
- Vitest coverage: 7 behavior tests on the toast component (filename,
  shortcut hint snapshotting, primary button calls reveal-by-path,
  body-click also reveals, stop-propagation on buttons, mouse-only
  click body), a tier-3 a11y test, and 9 bridge tests across all four
  settings values plus the macOS permission grant/deny paths.

Author: vdavid

Cargo.lock

@@ -39,6 +39,7 @@
     "@tauri-apps/api": "^2.10.1",
     "@tauri-apps/plugin-dialog": "^2.7.0",
     "@tauri-apps/plugin-fs": "^2.5.0",
+    "@tauri-apps/plugin-notification": "^2.3.3",
     "@tauri-apps/plugin-opener": "^2.5.3",
     "@tauri-apps/plugin-process": "^2.3.1",
     "@tauri-apps/plugin-store": "^2.4.2",

apps/desktop/package.json

@@ -38,6 +38,7 @@ tauri-plugin-opener = "2"
 tauri-plugin-mcp-bridge = "0.11"
 tauri-plugin-store = "2"
 tauri-plugin-dialog = "2.6"
+tauri-plugin-notification = "2.3.3"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 notify = "8"

apps/desktop/src-tauri/Cargo.toml

@@ -35,6 +35,7 @@
         "fs:allow-remove",
         "updater:default",
         "process:allow-restart",
-        "dialog:allow-ask"
+        "dialog:allow-ask",
+        "notification:default"
     ]
 }

apps/desktop/src-tauri/capabilities/default.json

@@ -300,6 +300,7 @@ pub fn run() {
         .plugin(tauri_plugin_fs::init())
         .plugin(tauri_plugin_process::init())
         .plugin(tauri_plugin_dialog::init())
+        .plugin(tauri_plugin_notification::init())
         .setup(|app| {
             // === Logging setup ===
             //

apps/desktop/src-tauri/src/lib.rs

@@ -0,0 +1,82 @@
+# Downloads (frontend)
+
+Frontend half of the downloads-watcher feature. Wires the backend `download-detected` Tauri event to the right user
+surface (in-app toast, macOS native notification, both, or neither) and owns the "Reveal latest download" / "Reveal this
+specific file" navigation helpers.
+
+Backend counterpart: [`src-tauri/src/downloads/CLAUDE.md`](../../../src-tauri/src/downloads/CLAUDE.md).
+
+## Architecture
+
+| File                             | Purpose                                                                                                                               |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `reveal.ts`                      | `revealLatestDownload(explorer)` (M4): consult ring + scan fallback. `revealPath(explorer, dir, name)` (M5): jump to a specific file. |
+| `RevealEmptyToastContent.svelte` | M4 INFO toast: "Your Downloads folder is empty…" with a "Go to Downloads" action.                                                     |
+| `RevealFdaToastContent.svelte`   | M4 INFO toast: "Cmdr needs Full Disk Access…" with an "Open System Settings" action.                                                  |
+| `reveal-ids.ts`                  | Dedup ids for M4's INFO toasts.                                                                                                       |
+| `event-bridge.svelte.ts`         | M5 listener bridge: one `download-detected` subscription, dispatches per the settings enum.                                           |
+| `DownloadToastContent.svelte`    | M5 in-app toast: title with filename + size, optional subdir line, snapshotted shortcut hint, Jump + Stop-showing actions.            |
+| `notifications-mode.ts`          | Reader, writer, and deep-link helper for `behavior.fileSystemWatching.downloadsNotifications`.                                        |
+
+## Settings-gated dispatch
+
+`startDownloadsEventBridge` reads `getDownloadsNotificationsMode()` per event and fans out to:
+
+- `'in-app'` → `addToast(DownloadToastContent, ...)` only.
+- `'macos'` → `sendNotification(...)` from `@tauri-apps/plugin-notification` only.
+- `'both'` → both.
+- `'neither'` → no-op.
+
+The macOS native path also asks the OS for permission the first time a session needs it. On denial we surface a single
+INFO toast with a stable dedup id; we DON'T flip the user's setting and we DON'T retry. The user can re-enable in System
+Settings whenever; their preference stays put.
+
+## Snapshot-at-creation rule
+
+The shortcut hint shown on each in-app toast is the value of `getEffectiveShortcuts('downloads.revealLatest')[0]` at
+toast-creation time, passed as a prop. A remap that happens between this toast appearing and the user clicking does NOT
+change what's displayed — that would be confusing, because the hint would no longer match what the user actually pressed
+when the toast first showed up. The next toast picks up the new binding naturally.
+
+Pure-prop-driven: the toast component reads `event`, `shortcutHint`, `explorer`, and `toastId` once on mount. No live
+subscriptions, no module state. The `ToastItem` host extends the toast store with a `props` field (see `lib/ui/toast/`)
+which is forwarded only to component-content toasts that opt in; existing toasts that don't pass `props` keep their
+zero-prop shape.
+
+## Reveal-by-path vs reveal-latest
+
+| Helper                      | When to call                                                                                                                                                 |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `revealLatestDownload(...)` | The user pressed ⌘J (or another "jump to latest" affordance). Consults the watcher's ring; falls back to a Downloads scan when the ring is empty.            |
+| `revealPath(explorer, ...)` | The user clicked or pressed Jump on a SPECIFIC toast. Takes them to the file the toast was for, even if a newer download has landed and become "the latest." |
+
+The split matters when a burst of downloads arrives: each toast must take the user to the file IT advertised, not to
+whichever file is most recent at click time.
+
+## FDA defense-in-depth
+
+The watcher won't emit `download-detected` when the FDA gate is closed — that's the contract enforced in
+`runtime::refresh_runtime`. The bridge re-checks the gate per event anyway (one `commands.downloadsWatcherStatus()`
+call) before surfacing any toast or OS notification. This guards against a stale event slipping through during a gate
+flip and mirrors the same defensive shape `revealLatestDownload` uses.
+
+## Clickability shape
+
+The downloads toast is whole-body clickable for mouse, but the clickable surface is NOT keyboard-focusable. The two
+explicit buttons inside ("Jump to file" and "Stop showing these") own keyboard activation independently; the body click
+is a mouse-only convenience.
+
+Both buttons call `event.stopPropagation()` in their click handlers so the body-click reveal doesn't also fire
+underneath (otherwise "Stop showing these" would navigate to the file before the Settings window came up).
+
+## Settings registry note
+
+The `behavior.fileSystemWatching.downloadsNotifications` registry entry is M7's territory. M5 reads the setting via
+try-catch'd `getSetting` so the key path works whether or not the registry knows about it yet; the documented default is
+`'in-app'`. Once M7 lands the entry, the try-catch becomes belt-and-braces with no behavior change.
+
+## Deep-link target
+
+`openSettingsToDownloadsNotifications` currently opens `Behavior > Drive indexing` — that's where the "Notify on
+~/Downloads changes" sub-group will live once M7 renames the section to "File system watching." M7 swaps the section
+path and (if the deep-link helper grows sub-group anchor support) focuses the specific row.

apps/desktop/src/lib/downloads/CLAUDE.md

@@ -0,0 +1,43 @@
+import { describe, it, vi } from 'vitest'
+import { mount, tick } from 'svelte'
+import { expectNoA11yViolations } from '$lib/test-a11y'
+
+vi.mock('./reveal', () => ({
+  revealPath: vi.fn(() => Promise.resolve()),
+}))
+
+vi.mock('./notifications-mode', () => ({
+  setDownloadsNotificationsMode: vi.fn(),
+  openSettingsToDownloadsNotifications: vi.fn(() => Promise.resolve()),
+}))
+
+vi.mock('$lib/ui/toast', () => ({
+  dismissToast: vi.fn(),
+}))
+
+import DownloadToastContent from './DownloadToastContent.svelte'
+
+describe('DownloadToastContent a11y', () => {
+  it('renders with no a11y violations', async () => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    mount(DownloadToastContent, {
+      target,
+      props: {
+        toastId: 'downloads:a11y',
+        explorer: undefined,
+        event: {
+          path: '/Users/me/Downloads/report.pdf',
+          parentDir: '/Users/me/Downloads',
+          fileName: 'report.pdf',
+          observedAtMs: 1_700_000_000_000,
+          inSubdir: false,
+          sizeBytes: 1024,
+        },
+        shortcutHint: '⌘J',
+      },
+    })
+    await tick()
+    await expectNoA11yViolations(target)
+  })
+})