Merge pull request #4530 from atomantic/cos/task-msy5dmuo/agent-145c31b9

fix: provide route error recovery UI

Author: atomantic

client/src/components/RouteErrorFallback.jsx

@@ -0,0 +1,49 @@
+import { AlertTriangle } from 'lucide-react';
+import { useNavigate, useRouteError, isRouteErrorResponse } from 'react-router';
+import Banner from './ui/Banner';
+
+const getErrorMessage = (error) => {
+  if (isRouteErrorResponse(error)) return error.statusText || `Request failed (${error.status})`;
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  return 'The page could not be loaded.';
+};
+
+export default function RouteErrorFallback() {
+  const error = useRouteError();
+  const navigate = useNavigate();
+  const message = getErrorMessage(error);
+
+  return (
+    <div className="min-h-dvh-cap bg-port-bg flex items-center justify-center p-4">
+      <div className="bg-port-card border border-port-border rounded-xl p-8 max-w-lg w-full">
+        <div className="flex items-center justify-center mb-4">
+          <AlertTriangle size={32} className="text-port-error" />
+        </div>
+        <h1 className="text-xl font-bold text-port-text text-center mb-2">PortOS could not load this page</h1>
+        <p className="text-port-text-muted text-sm text-center mb-4">
+          The server may still be restarting, or this browser may have an outdated app asset. Try again in a moment.
+        </p>
+        <Banner tone="error" size="md" className="mb-4">
+          <p className="text-xs font-mono break-all">{message}</p>
+        </Banner>
+        <div className="flex flex-col sm:flex-row gap-2">
+          <button
+            type="button"
+            onClick={() => window.location.reload()}
+            className="flex-1 px-4 py-2 bg-port-accent hover:bg-port-accent/80 text-port-on-accent rounded-lg transition-colors"
+          >
+            Try again
+          </button>
+          <button
+            type="button"
+            onClick={() => navigate('/')}
+            className="flex-1 px-4 py-2 border border-port-border hover:bg-port-card-hover text-port-text rounded-lg transition-colors"
+          >
+            Go to dashboard
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

client/src/components/RouteErrorFallback.test.jsx

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen, act } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createMemoryRouter, Outlet, RouterProvider } from 'react-router';
+import RouteErrorFallback from './RouteErrorFallback';
+
+const renderRouteError = async (error) => {
+  const router = createMemoryRouter([
+    {
+      path: '/',
+      errorElement: <RouteErrorFallback />,
+      element: <Outlet />,
+      children: [
+        { index: true, element: <div>Loaded page</div> },
+        {
+          path: 'broken',
+          loader: () => { throw error; },
+          element: <div>Broken page</div>,
+        },
+      ],
+    },
+  ], { initialEntries: ['/broken'] });
+
+  let view;
+  await act(async () => {
+    view = render(<RouterProvider router={router} />);
+    await router.initialize();
+  });
+  return view;
+};
+
+describe('RouteErrorFallback', () => {
+  it('explains that the page failed and offers recovery actions', async () => {
+    await renderRouteError(new Error('Importing a module script failed'));
+
+    expect(screen.getByRole('heading', { name: 'PortOS could not load this page' })).toBeInTheDocument();
+    expect(screen.getByText('Importing a module script failed')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Try again' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Go to dashboard' })).toBeInTheDocument();
+  });
+
+  it('returns to the dashboard without reloading', async () => {
+    const user = userEvent.setup();
+    await renderRouteError(new Error('Server unavailable'));
+
+    await user.click(screen.getByRole('button', { name: 'Go to dashboard' }));
+
+    expect(screen.getByText('Loaded page')).toBeInTheDocument();
+  });
+
+  it('handles a route error response', async () => {
+    await renderRouteError(new Response(null, { status: 503, statusText: 'Service Unavailable' }));
+
+    expect(screen.getByText('Service Unavailable')).toBeInTheDocument();
+  });
+
+  it('reloads when retry is clicked', async () => {
+    const reload = vi.fn();
+    vi.stubGlobal('location', { reload });
+    const user = userEvent.setup();
+    await renderRouteError(new Error('Server unavailable'));
+
+    await user.click(screen.getByRole('button', { name: 'Try again' }));
+
+    expect(reload).toHaveBeenCalledOnce();
+    vi.unstubAllGlobals();
+  });
+});

client/src/main.jsx

@@ -4,6 +4,7 @@ import ReactDOM from 'react-dom/client';
 import { createBrowserRouter, RouterProvider } from 'react-router';
 import { Toaster } from './components/ui/Toast';
 import ErrorBoundary from './components/ErrorBoundary';
+import RouteErrorFallback from './components/RouteErrorFallback';
 import { ThemeProvider } from './components/ThemeContext';
 import { isStaleChunkError, reloadOnceForStaleChunk } from './utils/staleChunkReload';
 import { reportClientError } from './lib/clientErrorReporter';
@@ -60,6 +61,7 @@ window.addEventListener('error', (event) => {
 const router = createBrowserRouter([
   {
     path: '*',
+    errorElement: <RouteErrorFallback />,
     element: (
       <>
         <App />