refactor(errors): defer mutation errors to global handler

Now that MutationCache toasts via toUserMessage by default, the per-hook
onError duplicates drop away. Also normalizes inline query-error UI and
surfaces a previously-silent failure.

Mutations — removed redundant onError toasts:
- network-selector: useAcceptInvitation, createNetwork (inline)
- network-settings: useInviteMembers, useRevokeInvitation, useRemoveMember
- network-billing: useCreateCheckoutSession, useCreatePortalSession
  (onSuccess toasts stay — they carry domain context like network name)

Queries — consistent inline error UX via toUserMessage:
- network-selector: failed-to-load state gets a "Try again" button
- network-billing: "Couldn't load billing" includes friendly reason
- network-settings: useNetworkInvitations failure now surfaces a hint
  (previously rendered as "0 pending" — silently wrong)

Trimmed noisy JSDoc from PR 1 files (errors.ts, query-client.ts,
app-error-boundary.tsx, error-fallback.tsx, ipc-utils.ts).

js/src/components/app-error-boundary.tsx

@@ -8,10 +8,7 @@ import {
   TopLevelErrorFallback,
 } from "@/components/error-fallback";
 
-/**
- * Catches render crashes OUTSIDE react-router. Used once at the root so a
- * broken bootstrap still shows a recovery UI instead of a white screen.
- */
+/** Catches render crashes OUTSIDE the router so bootstrap failures still recover. */
 export function TopLevelErrorBoundary({ children }: PropsWithChildren) {
   return (
     <ErrorBoundary
@@ -29,8 +26,7 @@ export function TopLevelErrorBoundary({ children }: PropsWithChildren) {
 }
 
 /**
- * Catches render crashes INSIDE the router. Auto-resets when the route
- * changes (so clicking "Go home" clears the error) and resets the React
+ * Route-scoped boundary. Resets on pathname change and clears the React
  * Query error cache on retry so stale failures don't stick.
  */
 export function RouteErrorBoundary({ children }: PropsWithChildren) {

js/src/components/error-fallback.tsx

@@ -57,10 +57,7 @@ function ErrorCard({
   );
 }
 
-/**
- * Fallback for the boundary mounted OUTSIDE the router. `useNavigate` isn't
- * available here, so "Go home" drops the hash fragment directly.
- */
+// Outside the router `useNavigate` is unavailable, so "Go home" drops the hash directly.
 export function TopLevelErrorFallback({
   error,
   resetErrorBoundary,
@@ -78,10 +75,6 @@ export function TopLevelErrorFallback({
   );
 }
 
-/**
- * Fallback for boundaries mounted INSIDE the router. Uses react-router's
- * navigate so the browser history stays consistent.
- */
 export function RouteErrorFallback({
   error,
   resetErrorBoundary,

js/src/features/network-billing.tsx

@@ -1,6 +1,5 @@
 import { useState } from "react";
 import { ExternalLink } from "lucide-react";
-import { toast } from "sonner";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Label } from "@/components/ui/label";
@@ -9,6 +8,7 @@ import { Separator } from "@/components/ui/separator";
 import { Muted } from "@/components/ui/typography";
 import { CopyableEmail } from "@/components/copyable-email";
 import { cn } from "@/lib/utils";
+import { toUserMessage } from "@/lib/errors";
 import { SUPPORT_EMAIL } from "@/lib/constants";
 import {
   useCreateCheckoutSession,
@@ -172,7 +172,6 @@ function FreeBilling({
   const handleUpgrade = () => {
     createCheckout.mutate(cadence, {
       onSuccess: ({ url }) => window.electronLink.openExternal(url),
-      onError: (err) => toast.error(err.message || "Failed to start checkout"),
     });
   };
 
@@ -230,8 +229,6 @@ function ProBilling({
   const handleManage = () => {
     createPortal.mutate(undefined, {
       onSuccess: ({ url }) => window.electronLink.openExternal(url),
-      onError: (err) =>
-        toast.error(err.message || "Failed to open billing portal"),
     });
   };
 
@@ -342,7 +339,7 @@ function AdminBillingControls({ networkId }: { networkId: string }) {
   if (error) {
     return (
       <div className="px-4 py-3">
-        <Muted className="text-sm">Failed to load billing.</Muted>
+        <Muted className="text-sm">Couldn't load billing: {toUserMessage(error)}</Muted>
       </div>
     );
   }

js/src/features/network-selector.tsx

@@ -22,6 +22,7 @@ import { useNetworks } from "@/hooks/use-networks";
 import { useMyInvitations, useAcceptInvitation } from "@/hooks/use-member-management";
 import { apiClient } from "@/api/client";
 import { Progress } from "@/components/ui/progress";
+import { toUserMessage } from "@/lib/errors";
 import type { Network, Invitation } from "@/api/types";
 
 function NetworkRow({
@@ -86,9 +87,6 @@ function InvitationRow({ invitation }: { invitation: Invitation }) {
       onSuccess: () => {
         toast.success(`Joined ${invitation.network_name}`);
       },
-      onError: (err) => {
-        toast.error(err.message || "Failed to accept invitation");
-      },
     });
   };
 
@@ -138,9 +136,6 @@ function CreateNetworkDialog({
       setName("");
       navigate(`/${network.id}/settings`);
     },
-    onError: (err) => {
-      toast.error(err.message || "Failed to create network");
-    },
   });
 
   const handleSubmit = (e: React.FormEvent) => {
@@ -200,9 +195,12 @@ export default function NetworkSelector() {
 
   if (error) {
     return (
-      <div className="flex h-full items-center justify-center">
-        <p className="text-destructive text-sm">Failed to load networks</p>
-        <p>{error.message}</p>
+      <div className="flex h-full flex-col items-center justify-center gap-3 p-6 text-center">
+        <p className="text-sm font-medium">Couldn't load your networks</p>
+        <p className="text-muted-foreground text-xs">{toUserMessage(error)}</p>
+        <Button size="sm" variant="outline" onClick={() => refetch()}>
+          Try again
+        </Button>
       </div>
     );
   }

js/src/features/network-settings.tsx

@@ -79,9 +79,6 @@ function InviteForm({ networkId }: { networkId: string }) {
         toast.success(`Invitation sent to ${trimmed}`);
         setEmail("");
       },
-      onError: (err) => {
-        toast.error(err.message || "Failed to send invitation");
-      },
     });
   };
 
@@ -119,9 +116,6 @@ function PendingInvitationRow({
       onSuccess: () => {
         toast.success(`Invitation to ${email} revoked`);
       },
-      onError: (err) => {
-        toast.error(err.message || "Failed to revoke invitation");
-      },
     });
   };
 
@@ -188,7 +182,7 @@ export default function NetworkSettingsPage() {
   const [searchParams] = useSearchParams();
   const { data: networks } = useNetworks();
   const network = networks?.find((n) => n.id === networkId);
-  const { data: invitations } = useNetworkInvitations(networkId!);
+  const { data: invitations, error: invitationsError } = useNetworkInvitations(networkId!);
   const currentUser = useAuthStore((s) => s.user);
   const isAdmin = currentUser?.id === network?.admin_human.id;
   const [memberToRemove, setMemberToRemove] = useState<Human | null>(null);
@@ -286,6 +280,14 @@ export default function NetworkSettingsPage() {
             />
             <Separator />
             <InviteForm networkId={networkId!} />
+            {invitationsError && (
+              <>
+                <Separator />
+                <p className="text-muted-foreground px-4 py-3 text-xs">
+                  Couldn't load pending invitations.
+                </p>
+              </>
+            )}
             {pendingCount > 0 && (
               <>
                 <Separator />
@@ -354,9 +356,6 @@ export default function NetworkSettingsPage() {
                 toast.success(`Removed ${target.email}`);
                 setMemberToRemove(null);
               },
-              onError: (err) => {
-                toast.error(err.message || "Failed to remove member");
-              },
             });
           }}
           onClose={() => {

js/src/lib/errors.ts

@@ -1,9 +1,6 @@
 import { z } from "zod";
 import { appEnv } from "@/config/env";
 
-/**
- * Thrown by the API client for any non-2xx response.
- */
 export class ApiError extends Error {
   constructor(
     public status: number,
@@ -16,9 +13,8 @@ export class ApiError extends Error {
 
 /**
  * Thrown when a free-plan network attempts to create a non-container particle
- * after hitting its daily message limit. Callers should surface an upgrade
- * prompt; compose UI should also disable triggers proactively via
- * `useNetworkUsage` rather than relying on this throw.
+ * after hitting its daily message limit. Compose UI also disables triggers
+ * proactively via `useNetworkUsage` — this throw is a last-line defense.
  */
 export class QuotaExceededError extends Error {
   constructor(public readonly networkId: string) {
@@ -33,11 +29,6 @@ function normalizeMessage(message: string): string {
   return message.replace(IPC_PREFIX, "").replace(/^Error:\s*/, "").trim();
 }
 
-/**
- * Maps any thrown value to a short, user-facing string. Used by the global
- * MutationCache toast handler, the error-boundary fallback, and any call site
- * that wants to surface an error in the UI.
- */
 export function toUserMessage(err: unknown): string {
   if (err instanceof ApiError) {
     if (err.status === 401) return "Please sign in again.";
@@ -69,11 +60,7 @@ export function toUserMessage(err: unknown): string {
 
 type ErrorContext = Record<string, unknown>;
 
-/**
- * For expected-but-worth-recording failures (silent-catch sites). In dev,
- * prints to console. In prod today this is a no-op; PR 4 wires this up to
- * Sentry breadcrumbs without touching call sites.
- */
+/** Expected-but-recordable failures. Dev logs; prod is currently a no-op. */
 export function logError(err: unknown, context?: ErrorContext): void {
   if (appEnv === "dev") {
     // eslint-disable-next-line no-console
@@ -81,11 +68,7 @@ export function logError(err: unknown, context?: ErrorContext): void {
   }
 }
 
-/**
- * For unexpected failures the user may not have seen (render crashes, query
- * errors, background mutations). Always surfaces somewhere. PR 4 wires this
- * up to `Sentry.captureException`.
- */
+/** Unexpected failures the user may not see. Always surfaces somewhere. */
 export function reportError(err: unknown, context?: ErrorContext): void {
   // eslint-disable-next-line no-console
   console.error("[error]", err, context ?? {});

js/src/lib/query-client.ts

@@ -8,14 +8,8 @@ import { ApiError, logError, reportError, toUserMessage } from "@/lib/errors";
 
 declare module "@tanstack/react-query" {
   interface Register {
-    queryMeta: {
-      /** Show a sonner error toast automatically on query failure. */
-      toastOnError?: boolean;
-    };
-    mutationMeta: {
-      /** Opt out of the default sonner error toast (caller handles feedback). */
-      suppressToast?: boolean;
-    };
+    queryMeta: { toastOnError?: boolean };
+    mutationMeta: { suppressToast?: boolean };
   }
 }
 

js/src/main/ipc-utils.ts

@@ -6,9 +6,8 @@ type InvokeHandler = (
 ) => Promise<unknown> | unknown;
 
 /**
- * Wraps `ipcMain.handle` so handler failures log the full stack in the main
- * process and re-throw a sanitized message to the renderer. Without this,
- * main-process exceptions silently reject the renderer promise with no trace.
+ * Wraps `ipcMain.handle` so handler failures log with full stack in main and
+ * re-throw a sanitized message to the renderer.
  */
 export function safeHandle(channel: string, handler: InvokeHandler): void {
   ipcMain.handle(channel, async (event, ...args) => {