Typed events: foundation + volume-space-changed reference

- Turn on tauri-specta's event support (`tauri_specta::Event` + `collect_events!` + `Builder::events()`), mounted once via `mount_events` in `lib.rs` setup. Events now generate typed names + payload types into `bindings.ts` and fold into the existing `bindings-fresh` check, the same machinery commands already use.
- Migrate `volume-space-changed` end-to-end as the proven reference: `VolumeSpaceChanged` payload derives `Event`, emits via `payload.emit(app)`, and the FE listens through a typed `onVolumeSpaceChanged` wrapper instead of a hand-typed `listen('volume-space-changed')`.
- Plan + categorized inventory in `docs/specs/typed-events-plan.md`; pattern documented in `lib/ipc/CLAUDE.md`.

Author: vdavid

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

@@ -46,9 +46,10 @@
 
 #[cfg(test)]
 use specta_typescript::Typescript;
-use tauri_specta::Builder;
+use tauri_specta::{Builder, collect_events};
 
 use crate::ipc_collectors::collect_all_types;
+use crate::space_poller::VolumeSpaceChanged;
 
 /// Public greeting used by the example webview surface; kept here as the
 /// foundational smoke test for the specta wiring.
@@ -561,7 +562,13 @@ pub fn builder() -> Builder<tauri::Wry> {
     // Build the final Commands combining the runtime handler with all type info.
     // `internal::command` takes the handler fn and the type-collector fn pointer.
     let combined_commands = tauri_specta::internal::command(runtime_handler, collect_all_types);
-    Builder::<tauri::Wry>::new().commands(combined_commands)
+    Builder::<tauri::Wry>::new()
+        .commands(combined_commands)
+        // Typed events. Each registered struct derives `tauri_specta::Event`;
+        // its kebab-cased name is the wire event name and its TS type + a typed
+        // `events.<name>.listen(...)` helper are generated into `bindings.ts`.
+        // Mounted onto the app via `mount_events` in `crate::run`.
+        .events(collect_events![VolumeSpaceChanged])
 }
 
 #[cfg(test)]

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

@@ -162,6 +162,10 @@ pub fn run() {
     // path silently overwrites the committed file with raw specta output on
     // every dev launch.
     let specta_builder = ipc::builder();
+    // `invoke_handler()` returns an owned closure (it clones the command map
+    // internally), so we grab it here before moving `specta_builder` into the
+    // `setup` closure where `mount_events` registers the typed events.
+    let invoke_handler = specta_builder.invoke_handler();
     let builder = tauri::Builder::default();
 
     // Window state plugin is only available on desktop platforms. The filter
@@ -264,7 +268,12 @@ pub fn run() {
         .plugin(tauri_plugin_dialog::init())
         .plugin(tauri_plugin_notification::init())
         .plugin(downloads::global_shortcut::plugin_builder())
-        .setup(|app| {
+        .setup(move |app| {
+            // Mount the typed `tauri-specta` events onto the app. Required before
+            // any `Event::emit` / `Event::listen` call resolves the event name
+            // from the registry. See `ipc.rs` for the event collection.
+            specta_builder.mount_events(app);
+
             // === Logging setup ===
             //
             // Hand-rolled fern dispatch tree (`logging::dispatch::init`) replaces
@@ -712,7 +721,7 @@ pub fn run() {
             Ok(())
         })
         .on_menu_event(menu::handle_menu_event)
-        .invoke_handler(specta_builder.invoke_handler())
+        .invoke_handler(invoke_handler)
         .on_window_event(|window, event| {
             // Main-window focus re-checks the FDA gate so the Downloads
             // watcher starts/stops on transitions. Covers the "user

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

@@ -15,12 +15,13 @@
 //! same single `statfs` per tick with the permanent watcher.
 
 use log::{debug, info, warn};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::{Mutex, OnceLock};
 use std::time::Duration;
 use tauri::{AppHandle, Emitter};
+use tauri_specta::Event;
 
 use crate::file_system::get_volume_manager;
 use crate::file_system::volume::DEFAULT_VOLUME_ID;
@@ -84,13 +85,16 @@ struct CachedSpace {
     available_bytes: u64,
 }
 
-/// Payload for the `volume-space-changed` Tauri event.
-#[derive(Clone, Serialize)]
+/// Typed `volume-space-changed` Tauri event. The struct name kebab-cases to the
+/// wire event name (`volume-space-changed`) via `tauri_specta::Event`. Both the
+/// TS payload type and a typed `events.volumeSpaceChanged.listen(...)` helper are
+/// generated into `apps/desktop/src/lib/ipc/bindings.ts`.
+#[derive(Clone, Serialize, Deserialize, specta::Type, Event)]
 #[serde(rename_all = "camelCase")]
-struct VolumeSpaceChangedPayload {
-    volume_id: String,
-    total_bytes: u64,
-    available_bytes: u64,
+pub struct VolumeSpaceChanged {
+    pub volume_id: String,
+    pub total_bytes: u64,
+    pub available_bytes: u64,
 }
 
 /// Payload for the `low-disk-space` Tauri event.
@@ -385,13 +389,13 @@ fn update_cache(volume_id: &str, space: &CachedSpace) {
 
 fn emit(volume_id: &str, space: &CachedSpace) {
     let Some(app) = APP_HANDLE.get() else { return };
-    let payload = VolumeSpaceChangedPayload {
+    let payload = VolumeSpaceChanged {
         volume_id: volume_id.to_string(),
         total_bytes: space.total_bytes,
         available_bytes: space.available_bytes,
     };
     debug!("volume-space-changed: {} ({} avail)", volume_id, space.available_bytes);
-    if let Err(e) = app.emit("volume-space-changed", &payload) {
+    if let Err(e) = payload.emit(app) {
         warn!("Failed to emit volume-space-changed: {}", e);
     }
 }

apps/desktop/src/lib/file-explorer/pane/FilePane.svelte

@@ -30,6 +30,7 @@
         listDirectoryStart,
         listen,
         onMtpDeviceDisconnected,
+        onVolumeSpaceChanged,
         openFile,
         refreshListingIndexSizes,
         resolvePathVolume,
@@ -2511,18 +2512,15 @@
             userHomePath = h.endsWith('/') ? h.slice(0, -1) : h
         })
 
-        // Listen for live disk-space updates from the backend poller
-        void listen<{ volumeId: string; totalBytes: number; availableBytes: number }>(
-            'volume-space-changed',
-            (event) => {
-                if (event.payload.volumeId === volumeId) {
-                    volumeSpace = {
-                        totalBytes: event.payload.totalBytes,
-                        availableBytes: event.payload.availableBytes,
-                    }
+        // Listen for live disk-space updates from the backend poller (typed event)
+        void onVolumeSpaceChanged((payload) => {
+            if (payload.volumeId === volumeId) {
+                volumeSpace = {
+                    totalBytes: payload.totalBytes,
+                    availableBytes: payload.availableBytes,
                 }
-            },
-        ).then((fn) => {
+            }
+        }).then((fn) => {
             unlistenSpaceChanged = fn
         })
 

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

@@ -34,6 +34,31 @@ For commands that return `Result<T, E>` on the Rust side, the TS wrapper returns
 `{ status: 'ok', data: T } | { status: 'error', error: E }`. Most call sites unwrap via `throwIpcError` from
 `$lib/tauri-commands/ipc-types`.
 
+## Typed events
+
+Events are wired through the same `tauri-specta` machinery as commands, but not all events are migrated yet — many are
+still raw `app.emit("name", payload)` on the Rust side with a hand-mirrored TS `listen<{…}>(...)`. See
+[`docs/specs/typed-events-plan.md`](../../../../../docs/specs/typed-events-plan.md) for the migration plan, the proven
+pattern, and the full event inventory.
+
+A typed event is a Rust struct deriving `tauri_specta::Event` (kebab-cased struct name = wire event name), registered
+via `collect_events![Struct]` in `ipc.rs::builder()`, and mounted with `specta_builder.mount_events(app)` in `lib.rs`'s
+`setup` (required, else `Event::emit` panics). Regen generates an `events.<name>` helper into `bindings.ts`:
+
+```ts
+events.volumeSpaceChanged.listen((event) => {
+  /* event.payload is typed */
+})
+```
+
+As with commands, don't call `events.*` raw in components — add a thin `on<Event>(cb)` wrapper in `tauri-commands/`
+(returns `UnlistenFn`) and import it from the barrel. The reference event is `volume-space-changed`
+(`onVolumeSpaceChanged` in `tauri-commands/storage.ts`).
+
+The same type-shape constraints apply (no `skip_serializing_if`, no `serde_json::Value`). Events with a runtime-built
+name or a `serde_json::Value` payload (the `mcp-*` MCP-dispatch relay, `viewer:file-changed:<session-id>`) stay
+string-based; the plan doc explains why.
+
 ## Call-site convention: name your arguments
 
 Specta-generated wrappers take **positional** arguments (in declaration order), not an object. That's elegant when the

apps/desktop/src/lib/ipc/bindings.ts

@@ -3,6 +3,7 @@
 // This file has been generated by Tauri Specta. Do not edit this file manually.
 
 import { invoke as __TAURI_INVOKE } from '@tauri-apps/api/core'
+import * as __TAURI_EVENT from '@tauri-apps/api/event'
 
 /** Commands */
 export const commands = {
@@ -2236,6 +2237,11 @@ export const commands = {
     typedError<FriendlyError, string>(__TAURI_INVOKE('preview_friendly_error', { errorCode, variant, providerPath })),
 }
 
+/** Events */
+export const events = {
+  volumeSpaceChanged: makeEvent<VolumeSpaceChanged>('volume-space-changed'),
+}
+
 /* Types */
 // Active settings snapshot cached at startup for inclusion in crash reports.
 export type ActiveSettings = {
@@ -4164,6 +4170,18 @@ export type VolumeCopyScanResult = {
   conflicts: ScanConflict[]
 }
 
+/**
+ *  Typed `volume-space-changed` Tauri event. The struct name kebab-cases to the
+ *  wire event name (`volume-space-changed`) via `tauri_specta::Event`. Both the
+ *  TS payload type and a typed `events.volumeSpaceChanged.listen(...)` helper are
+ *  generated into `apps/desktop/src/lib/ipc/bindings.ts`.
+ */
+export type VolumeSpaceChanged = {
+  volumeId: string
+  totalBytes: number
+  availableBytes: number
+}
+
 // Information about volume space.
 export type VolumeSpaceInfo = {
   // In bytes.
@@ -4290,3 +4308,23 @@ async function typedError<T, E>(
     return { status: 'error', error: e as any }
   }
 }
+
+function makeEvent<T>(name: string) {
+  const base = {
+    listen: (cb: __TAURI_EVENT.EventCallback<T>) => __TAURI_EVENT.listen(name, cb),
+    once: (cb: __TAURI_EVENT.EventCallback<T>) => __TAURI_EVENT.once(name, cb),
+    emit: ((payload: T) => __TAURI_EVENT.emit(name, payload) as unknown) as T extends null
+      ? () => Promise<void>
+      : (payload: T) => Promise<void>,
+  }
+
+  const fn = (target: import('@tauri-apps/api/webview').Webview | import('@tauri-apps/api/window').Window) => ({
+    listen: (cb: __TAURI_EVENT.EventCallback<T>) => target.listen(name, cb),
+    once: (cb: __TAURI_EVENT.EventCallback<T>) => target.once(name, cb),
+    emit: ((payload: T) => target.emit(name, payload) as unknown) as T extends null
+      ? () => Promise<void>
+      : (payload: T) => Promise<void>,
+  })
+
+  return Object.assign(fn, base)
+}

apps/desktop/src/lib/tauri-commands/index.ts

@@ -125,6 +125,7 @@ export {
   onVolumeContextAction,
   watchVolumeSpace,
   unwatchVolumeSpace,
+  onVolumeSpaceChanged,
   setDiskSpaceThreshold,
   setLowDiskSpaceConfig,
   checkFullDiskAccess,

apps/desktop/src/lib/tauri-commands/storage.ts

@@ -4,7 +4,7 @@ import { listen, type UnlistenFn } from '@tauri-apps/api/event'
 import type { VolumeInfo } from '../file-explorer/types'
 import type { TimedOut } from './ipc-types'
 import { getAppLogger } from '$lib/logging/logger'
-import { commands } from '$lib/ipc/bindings'
+import { commands, events, type VolumeSpaceChanged } from '$lib/ipc/bindings'
 import { throwIpcError } from './ipc-types'
 
 const log = getAppLogger('storage')
@@ -156,6 +156,18 @@ export async function unwatchVolumeSpace(watcherId: string): Promise<void> {
   await commands.unwatchVolumeSpace(watcherId)
 }
 
+/**
+ * Subscribes to live disk-space updates from the backend poller. The payload is
+ * the typed `tauri-specta` event, so `volumeId` / `totalBytes` / `availableBytes`
+ * are checked at compile time against the Rust `VolumeSpaceChanged` struct.
+ * Call the returned `UnlistenFn` in `onDestroy` to avoid leaks.
+ */
+export async function onVolumeSpaceChanged(callback: (payload: VolumeSpaceChanged) => void): Promise<UnlistenFn> {
+  return events.volumeSpaceChanged.listen((event) => {
+    callback(event.payload)
+  })
+}
+
 /**
  * Updates the disk space change threshold at runtime (in MB).
  */