Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix([issue-11675]): keep the app shell after page render errors (#11712)

[._.]/c2a5c043ed22
diff --git a/client/src/a11yConventions.test.js b/client/src/a11yConventions.test.js
index 7dc63692f5..2bad26b0f1 100644
--- a/client/src/a11yConventions.test.js
+++ b/client/src/a11yConventions.test.js
@@ -3936,6 +3936,9 @@ function B() { const sensors = useSensors(useSensor(PointerSensor)); return <Dnd
// barrel and thin-wrapper idioms. `seen` bounds the chase so a forwarding
// cycle resolves to "no" rather than recursing.
const suppliesPageHeading = (file, exportedName, seen = new Set()) => {
+ // Error boundaries own a recovery heading only while their children fail.
+ // Crediting that heading to a layout exempts every healthy outlet page.
+ if (/ErrorBoundary\.jsx$/.test(file)) return false;
const key = `${file}#${exportedName}`;
if (seen.has(key) || seen.size >= 8) return false;
seen.add(key);
@@ -4055,7 +4058,8 @@ function B() { const sensors = useSensors(useSensor(PointerSensor)); return <Dnd
'src/pages/ProbeLazyBad.jsx': 'export default function ProbeLazyBad() { return <h2>Lazy</h2>; }',
'src/pages/ProbeLazyGood.jsx': "import PageHeader from '../components/PageHeader';\nexport default function ProbeLazyGood() { return <PageHeader title=\"Lazy\" />; }",
'src/pages/ProbeShell.jsx': 'export default function ProbeShell() { return <h1>Shell</h1>; }',
- 'src/pages/ProbeShellBare.jsx': 'export default function ProbeShellBare() { return <div />; }',
+ 'src/pages/ProbeShellBare.jsx': "import ProbeErrorBoundary from '../components/ProbeErrorBoundary';\nexport default function ProbeShellBare() { return <ProbeErrorBoundary><div /></ProbeErrorBoundary>; }",
+ 'src/components/ProbeErrorBoundary.jsx': 'export default function ProbeErrorBoundary({ children }) { return failed ? <h1>Recovery only</h1> : children; }',
}, () => {
const offenders = routedPageElements('src/ProbeApp.jsx')
.filter((e) => !e.shelled)
diff --git a/client/src/components/ErrorBoundary.jsx b/client/src/components/ErrorBoundary.jsx
index bb0ab9e497..bcf2ac618c 100644
--- a/client/src/components/ErrorBoundary.jsx
+++ b/client/src/components/ErrorBoundary.jsx
@@ -13,6 +13,16 @@ export default class ErrorBoundary extends Component {
return { hasError: true, error };
}
+ componentDidUpdate(previousProps) {
+ if (this.state.hasError && previousProps.resetKey !== this.props.resetKey) {
+ this.resetError();
+ }
+ }
+
+ resetError = () => {
+ this.setState({ hasError: false, error: null });
+ };
+
componentDidCatch(error, errorInfo) {
const report = () => {
console.error(`💥 React Error: ${error.message}`, errorInfo);
@@ -41,7 +51,11 @@ export default class ErrorBoundary extends Component {
// Callers can supply a custom fallback (including `null`) — used to degrade
// gracefully inside non-DOM trees like the R3F Canvas, where the default
// full-screen DOM error UI can't render.
- if (this.props.fallback !== undefined) return this.props.fallback;
+ if (this.props.fallback !== undefined) {
+ return typeof this.props.fallback === 'function'
+ ? this.props.fallback(this.state.error, this.resetError)
+ : this.props.fallback;
+ }
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-md w-full">
diff --git a/client/src/components/Layout.jsx b/client/src/components/Layout.jsx
index 699e21b63d..3f62058cad 100644
--- a/client/src/components/Layout.jsx
+++ b/client/src/components/Layout.jsx
@@ -1,4 +1,5 @@
import MaintenanceBanner from './MaintenanceBanner.jsx';
+import PageErrorBoundary from './PageErrorBoundary';
import { useState, useEffect, useLayoutEffect, useMemo, useRef, useCallback } from 'react';
import useFocusTrap from '../hooks/useFocusTrap.js';
import { Outlet, NavLink, useLocation, useNavigate } from 'react-router';
@@ -1096,7 +1097,9 @@ export default function Layout() {
const isFullWidth = isFullWidthRoute(location.pathname);
return (
<main ref={mainRef} id="main-content" tabIndex={-1} className={`focus:outline-none flex-1 min-h-0 print:overflow-visible print:min-h-0 ${isFullWidth ? 'relative overflow-clip-safe' : 'overflow-auto p-4 md:p-6'}`}>
- <Outlet />
+ <PageErrorBoundary>
+ <Outlet />
+ </PageErrorBoundary>
</main>
);
})()}
diff --git a/client/src/components/Layout.test.jsx b/client/src/components/Layout.test.jsx
index 3698ca1a5c..9d56a2adb9 100644
--- a/client/src/components/Layout.test.jsx
+++ b/client/src/components/Layout.test.jsx
@@ -1,6 +1,7 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { render, screen, within, act, fireEvent, waitFor } from '@testing-library/react';
-import { MemoryRouter, useLocation } from 'react-router';
+import { MemoryRouter, Routes, Route, createMemoryRouter, RouterProvider, useLocation } from 'react-router';
+import { reloadOnceForStaleChunk } from '../utils/staleChunkReload';
import { PINNED_KEY } from '../utils/navWorkingSet.js';
import * as api from '../services/api';
import socket from '../services/socket';
@@ -54,7 +55,11 @@ vi.mock('./Logo', () => ({ default: () => null }));
vi.mock('./NotificationDropdown', () => ({ default: () => null }));
vi.mock('./voice/VoiceToggleButton', () => ({ default: () => null }));
vi.mock('./voice/VoiceWidget', () => ({ default: () => null }));
-vi.mock('./CmdKSearch', () => ({ default: () => null }));
+vi.mock('./CmdKSearch', () => ({ default: () => <div data-testid="command-palette" /> }));
+vi.mock('../utils/staleChunkReload', async (importOriginal) => ({
+ ...await importOriginal(),
+ reloadOnceForStaleChunk: vi.fn().mockResolvedValue(false),
+}));
vi.mock('./KeyboardHelp', () => ({ default: () => null }));
// --- Socket: record handlers, never connect. ---
@@ -798,3 +803,84 @@ describe('Layout — keyboard navigation shell', () => {
expect(sidebar).toHaveAttribute('inert');
});
});
+
+
+describe('Layout — page error containment', () => {
+ const renderFailingPage = async (failure) => {
+ const Page = () => {
+ if (failure.error) throw failure.error;
+ return <div>Recovered page</div>;
+ };
+ const router = createMemoryRouter([{ path: '*', element: (
+ <Routes>
+ <Route element={<Layout />}>
+ <Route path="broken" element={<Page />} />
+ <Route index element={<div>Dashboard page</div>} />
+ </Route>
+ </Routes>
+ ) }], { initialEntries: ['/broken'] });
+ render(<RouterProvider router={router} />);
+ await act(async () => {});
+ return router;
+ };
+
+ it('keeps command-palette access usable and retries the failed page', async () => {
+ const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const failure = { error: new Error('Malformed page record') };
+ try {
+ await renderFailingPage(failure);
+ expect(screen.getByRole('heading', { name: 'This page hit an error' })).toBeInTheDocument();
+ expect(screen.getByRole('alert')).toHaveTextContent('/broken');
+ expect(screen.getByText('Malformed page record').closest('details')).not.toHaveAttribute('open');
+ expect(screen.getByTestId('command-palette')).toBeInTheDocument();
+ const opened = vi.fn();
+ document.addEventListener(CMD_K_SEARCH_OPEN_EVENT, opened, { once: true });
+ fireEvent.click(screen.getAllByRole('button', { name: 'Open command palette' })[0]);
+ expect(opened).toHaveBeenCalledOnce();
+
+ failure.error = null;
+ fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+ expect(screen.getByText('Recovered page')).toBeInTheDocument();
+ } finally {
+ errorLog.mockRestore();
+ }
+ });
+
+ it('resets failures on sidebar and same-path search navigation', async () => {
+ const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
+ try {
+ const failure = { error: new Error('Broken record') };
+ const router = await renderFailingPage(failure);
+ fireEvent.click(screen.getByRole('link', { name: 'Dashboard' }));
+ expect(screen.getByText('Dashboard page')).toBeInTheDocument();
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ await act(async () => router.navigate('/broken'));
+ expect(screen.getByRole('alert')).toBeInTheDocument();
+ failure.error = null;
+ await act(async () => router.navigate('/broken?record=fixed'));
+ expect(screen.getByText('Recovered page')).toBeInTheDocument();
+ } finally {
+ errorLog.mockRestore();
+ }
+ });
+
+ it('keeps automatic stale-chunk recovery and cache-purging retry inside the shell', async () => {
+ const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
+ reloadOnceForStaleChunk.mockResolvedValue(false);
+ try {
+ await renderFailingPage({ error: new Error('Failed to fetch dynamically imported module') });
+ expect(reloadOnceForStaleChunk).toHaveBeenCalledOnce();
+ expect(screen.getByTestId('command-palette')).toBeInTheDocument();
+ reloadOnceForStaleChunk.mockResolvedValue(true);
+ await act(async () => fireEvent.click(screen.getByRole('button', { name: 'Retry' })));
+ expect(reloadOnceForStaleChunk).toHaveBeenLastCalledWith({ forceCachePurge: true });
+ const reload = vi.fn();
+ vi.stubGlobal('location', { reload });
+ reloadOnceForStaleChunk.mockResolvedValue(false);
+ await act(async () => fireEvent.click(screen.getByRole('button', { name: 'Retry' })));
+ expect(reload).toHaveBeenCalledOnce();
+ } finally {
+ errorLog.mockRestore();
+ }
+ });
+});
diff --git a/client/src/components/PageErrorBoundary.jsx b/client/src/components/PageErrorBoundary.jsx
new file mode 100644
index 0000000000..754ab3be63
--- /dev/null
+++ b/client/src/components/PageErrorBoundary.jsx
@@ -0,0 +1,48 @@
+import { useLocation, useNavigate } from 'react-router';
+import ErrorBoundary from './ErrorBoundary';
+import { isStaleChunkError, reloadOnceForStaleChunk } from '../utils/staleChunkReload';
+
+export default function PageErrorBoundary({ children }) {
+ const location = useLocation();
+ const navigate = useNavigate();
+
+ return (
+ <ErrorBoundary
+ resetKey={location.key}
+ fallback={(error, resetError) => (
+ <section role="alert" className="bg-port-card border border-port-border rounded-xl p-6 max-w-lg max-h-full overflow-y-auto mx-auto text-port-text">
+ <h1 className="text-xl font-bold mb-2">This page hit an error</h1>
+ <p className="text-sm text-port-text-muted mb-4">
+ An error occurred while rendering <code className="break-all">{location.pathname}</code>. You can retry or use navigation to open another page.
+ </p>
+ <details className="mb-4">
+ <summary className="cursor-pointer">Error details</summary>
+ <pre className="text-xs whitespace-pre-wrap break-all mt-2">{error?.message || 'Unknown error'}</pre>
+ </details>
+ <div className="flex flex-col sm:flex-row gap-2">
+ <button
+ type="button"
+ className="px-4 py-2 bg-port-accent hover:bg-port-accent/80 text-port-on-accent rounded-lg"
+ onClick={async () => {
+ if (isStaleChunkError(error, { duringRender: true })) {
+ const reloaded = await reloadOnceForStaleChunk({ forceCachePurge: true });
+ if (reloaded) return;
+ window.location.reload();
+ return;
+ }
+ resetError();
+ }}
+ >
+ Retry
+ </button>
+ <button type="button" onClick={() => navigate('/')} className="px-4 py-2 border border-port-border hover:bg-port-card-hover rounded-lg">
+ Go to dashboard
+ </button>
+ </div>
+ </section>
+ )}
+ >
+ {children}
+ </ErrorBoundary>
+ );
+}
diff --git a/client/src/components/RouteErrorFallback.jsx b/client/src/components/RouteErrorFallback.jsx
index 30068ec938..c9f6abd751 100644
--- a/client/src/components/RouteErrorFallback.jsx
+++ b/client/src/components/RouteErrorFallback.jsx
@@ -15,6 +15,7 @@ export default function RouteErrorFallback() {
const error = useRouteError();
const navigate = useNavigate();
const message = getErrorMessage(error);
+ const isLoadError = isStaleChunkError(error, { duringRender: true }) || isRouteErrorResponse(error);
const retry = async () => {
if (isStaleChunkError(error, { duringRender: true })) {
@@ -38,7 +39,9 @@ export default function RouteErrorFallback() {
</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.
+ {isLoadError
+ ? 'The server may still be restarting, or this browser may have an outdated app asset. Try again in a moment.'
+ : 'PortOS encountered an unexpected app error. Try again or return to the dashboard.'}
</p>
<Banner tone="error" size="md" className="mb-4">
<p className="text-xs font-mono break-all">{message}</p>
diff --git a/client/src/components/RouteErrorFallback.test.jsx b/client/src/components/RouteErrorFallback.test.jsx
index 2aa4ddd3a5..a8745d0d77 100644
--- a/client/src/components/RouteErrorFallback.test.jsx
+++ b/client/src/components/RouteErrorFallback.test.jsx
@@ -64,6 +64,8 @@ describe('RouteErrorFallback', () => {
it('returns to the dashboard without reloading', async () => {
const user = userEvent.setup();
await renderRouteError(new Error('Server unavailable'));
+ expect(screen.getByText(/unexpected app error/)).toBeInTheDocument();
+ expect(screen.queryByText(/server may still be restarting/)).not.toBeInTheDocument();
await user.click(screen.getByRole('button', { name: 'Go to dashboard' }));
@@ -74,6 +76,7 @@ describe('RouteErrorFallback', () => {
await renderRouteError(new Response(null, { status: 503, statusText: 'Service Unavailable' }));
expect(screen.getByText('Service Unavailable')).toBeInTheDocument();
+ expect(screen.getByText(/server may still be restarting/)).toBeInTheDocument();
});
it('reloads when retry is clicked', async () => {