fix: keep the faults dashboard in place while the fault list refreshes

An empty fault list was indistinguishable from a list that had never
loaded: fetchFaults derived "initial load" from faults.length === 0, so
every later fetch re-entered the loading state and the dashboard swapped
itself for its first-load skeleton. The list now carries a faultsLoaded
flag, set once an answer arrives - including an error answer, so a retry
does not bring the skeleton back either.

Refreshing is also shared now. The dashboard and the sidebar badge each
ran their own timer, their own mount fetch and, in the badge, their own
visibilitychange listener, so a gateway serving both views answered two
requests per refresh. useFaultPolling keeps one timer, one listener and
one initial fetch for however many fault views are mounted, and drops the
timer while the SSE fault stream is delivering updates.

Author: bburda

e2e/faults-refresh.spec.ts

@@ -0,0 +1,93 @@
+// Copyright 2026 bburda
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * The fault dashboard against a real gateway that reports no faults - the case
+ * where "loaded" and "empty" look alike. A refresh must leave the page as it is
+ * and must cost one request, however many fault views are on screen.
+ */
+
+import { test, expect, type Page } from '@playwright/test';
+
+/**
+ * Reports whether the first-load skeleton appears at any point from now on,
+ * including for a single frame that polling a locator would step over.
+ */
+async function watchForSkeleton(page: Page): Promise<() => Promise<boolean>> {
+    await page.evaluate(() => {
+        const w = window as unknown as { __skeletonSeen?: boolean; __skeletonObserver?: MutationObserver };
+        w.__skeletonSeen = false;
+        const observer = new MutationObserver(() => {
+            if (document.querySelector('main .animate-pulse')) {
+                w.__skeletonSeen = true;
+            }
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+        w.__skeletonObserver = observer;
+    });
+
+    return async () =>
+        page.evaluate(() => {
+            const w = window as unknown as { __skeletonSeen?: boolean; __skeletonObserver?: MutationObserver };
+            w.__skeletonObserver?.disconnect();
+            return w.__skeletonSeen === true;
+        });
+}
+
+/** Opens the dashboard and waits for the gateway's (empty) fault list to be on screen. */
+async function openDashboard(page: Page): Promise<void> {
+    await page.goto('/');
+    await page.getByRole('button', { name: 'Faults Dashboard' }).click();
+    await expect(page.getByText('No faults to display')).toBeVisible({ timeout: 30_000 });
+    await expect(page.getByText('No faults detected')).toBeVisible();
+}
+
+const POLL_INTERVAL_MS = 5_000;
+const OBSERVED_WINDOW_MS = 11_000;
+
+test.describe('faults dashboard refresh', () => {
+    test('a refresh of an empty fault list leaves the page as it is', async ({ page }) => {
+        await openDashboard(page);
+        const skeletonSeen = await watchForSkeleton(page);
+
+        // The refresh a tab regaining focus triggers.
+        await page.evaluate(() => document.dispatchEvent(new Event('visibilitychange')));
+        await page.waitForTimeout(2_000);
+
+        expect(await skeletonSeen()).toBe(false);
+        await expect(page.getByText('No faults to display')).toBeVisible();
+    });
+
+    test('the fallback poll asks once per interval, not once per mounted view', async ({ page }) => {
+        // With no fault stream the app falls back to polling. The dashboard and the
+        // sidebar badge are both on screen and read the same list. An HTTP status is
+        // what makes the client give up at once - a dropped connection it retries.
+        await page.route('**/faults/stream**', (route) =>
+            route.fulfill({ status: 404, contentType: 'application/json', body: '{}' })
+        );
+        await openDashboard(page);
+
+        const faultRequests: string[] = [];
+        page.on('request', (request) => {
+            if (new URL(request.url()).pathname.endsWith('/faults')) {
+                faultRequests.push(request.url());
+            }
+        });
+        await page.waitForTimeout(OBSERVED_WINDOW_MS);
+
+        const intervals = Math.floor(OBSERVED_WINDOW_MS / POLL_INTERVAL_MS);
+        expect(faultRequests.length).toBeGreaterThanOrEqual(intervals);
+        expect(faultRequests.length).toBeLessThanOrEqual(intervals + 1);
+    });
+});

playwright.config.ts

@@ -54,5 +54,8 @@ export default defineConfig({
         // it needs a fault manager the scripts gateway does not run. Serial for
         // the same reason as scripts-serial: one shared gateway.
         { name: 'rosbag-serial', testMatch: /rosbag-.*\.spec\.ts/, fullyParallel: false, workers: 1 },
+        // Reads the scripts gateway without changing it, but counts the requests the
+        // app makes, so it must not share a run with specs driving the same app.
+        { name: 'faults-serial', testMatch: /faults-.*\.spec\.ts/, fullyParallel: false, workers: 1 },
     ],
 });

src/components/FaultsDashboard.polling.test.tsx

@@ -0,0 +1,190 @@
+// Copyright 2026 bburda
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * The dashboard and the sidebar badge read the same fault list. These tests pin
+ * what the user sees while that list refreshes: the page must not fall back to
+ * its first-load skeleton, and the two views must not each ask the gateway
+ * separately.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, act } from '@testing-library/react';
+import { FaultsDashboard, FaultsCountBadge } from './FaultsDashboard';
+import { useAppStore } from '@/lib/store';
+
+const POLL_INTERVAL_MS = 5000;
+
+const RAW_FAULT = {
+    fault_code: 'LIDAR_RANGE_INVALID',
+    description: 'range invalid',
+    severity: 2,
+    severity_label: 'ERROR',
+    status: 'CONFIRMED',
+    first_occurred: 1756636800,
+    last_occurred: 1756636800,
+    occurrence_count: 1,
+    reporting_sources: ['/lidar_driver'],
+};
+
+function clientReturning(items: unknown[]) {
+    return {
+        GET: vi.fn(async () => {
+            await Promise.resolve();
+            return { data: { items }, error: undefined };
+        }),
+    };
+}
+
+/** Records every DOM state the user could have seen while `run` executed. */
+async function framesDuring(container: HTMLElement, run: () => Promise<void>): Promise<string[]> {
+    const frames: string[] = [];
+    const record = () => frames.push(container.querySelectorAll('.animate-pulse').length > 0 ? 'skeleton' : 'content');
+    const observer = new MutationObserver(record);
+    observer.observe(container, { childList: true, subtree: true });
+    await run();
+    if (observer.takeRecords().length > 0) {
+        record();
+    }
+    observer.disconnect();
+    return frames;
+}
+
+async function settle() {
+    await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+    });
+}
+
+async function advance(ms: number) {
+    await act(async () => {
+        vi.advanceTimersByTime(ms);
+        await Promise.resolve();
+    });
+    await settle();
+}
+
+function connect(client: ReturnType<typeof clientReturning>, sseActive: boolean) {
+    useAppStore.setState({
+        isConnected: true,
+        client,
+        faults: [],
+        isLoadingFaults: false,
+        faultsLoaded: false,
+        faultStreamCleanup: sseActive ? () => {} : null,
+    } as never);
+}
+
+beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+    useAppStore.setState({ isConnected: false, client: null, faults: [], faultStreamCleanup: null } as never);
+});
+
+describe('FaultsDashboard refresh behaviour', () => {
+    it('never falls back to the first-load skeleton once the empty list has loaded', async () => {
+        connect(clientReturning([]), false);
+        const { container } = render(<FaultsDashboard />);
+        await settle();
+
+        const frames = await framesDuring(container, () => advance(POLL_INTERVAL_MS));
+
+        expect(frames).not.toContain('skeleton');
+    });
+
+    it('never falls back to the skeleton when the tab regains focus', async () => {
+        connect(clientReturning([]), true);
+        const { container } = render(
+            <>
+                <FaultsCountBadge />
+                <FaultsDashboard />
+            </>
+        );
+        await settle();
+
+        const frames = await framesDuring(container, async () => {
+            await act(async () => {
+                document.dispatchEvent(new Event('visibilitychange'));
+                await Promise.resolve();
+            });
+            await settle();
+        });
+
+        expect(frames).not.toContain('skeleton');
+    });
+
+    it('still shows the skeleton for the very first load', async () => {
+        connect(clientReturning([RAW_FAULT]), false);
+        const { container } = render(<FaultsDashboard />);
+
+        expect(container.querySelectorAll('.animate-pulse').length).toBeGreaterThan(0);
+
+        await settle();
+        expect(container.querySelectorAll('.animate-pulse').length).toBe(0);
+    });
+
+    it('asks the gateway once per interval even with the badge and the dashboard mounted', async () => {
+        const client = clientReturning([RAW_FAULT]);
+        connect(client, false);
+        render(
+            <>
+                <FaultsCountBadge />
+                <FaultsDashboard />
+            </>
+        );
+        await settle();
+        expect(client.GET).toHaveBeenCalledTimes(1);
+
+        await advance(POLL_INTERVAL_MS);
+        expect(client.GET).toHaveBeenCalledTimes(2);
+
+        await advance(POLL_INTERVAL_MS * 2);
+        expect(client.GET).toHaveBeenCalledTimes(4);
+    });
+
+    it('does not poll while the fault stream delivers updates', async () => {
+        const client = clientReturning([RAW_FAULT]);
+        connect(client, true);
+        render(
+            <>
+                <FaultsCountBadge />
+                <FaultsDashboard />
+            </>
+        );
+        await settle();
+        const afterMount = client.GET.mock.calls.length;
+
+        await advance(POLL_INTERVAL_MS * 3);
+
+        expect(client.GET.mock.calls.length).toBe(afterMount);
+    });
+
+    it('stops polling when the last fault view unmounts', async () => {
+        const client = clientReturning([RAW_FAULT]);
+        connect(client, false);
+        const { unmount } = render(<FaultsDashboard />);
+        await settle();
+        const afterMount = client.GET.mock.calls.length;
+
+        unmount();
+        await advance(POLL_INTERVAL_MS * 2);
+
+        expect(client.GET.mock.calls.length).toBe(afterMount);
+    });
+});