@peers-app/peers-ui 0.25.8 → 0.25.9

package/dist/tabs-layout/network-status-indicator.js

@@ -14,6 +14,7 @@ const moment_1 = __importDefault(require("moment"));
 const react_1 = require("react");
 const identity_routes_1 = require("../screens/identity/identity-routes");
 const network_viewer_ipc_1 = require("../screens/network-viewer/network-viewer-ipc");
+const network_viewer_section_1 = require("../screens/network-viewer/network-viewer-section");
 const tabs_state_1 = require("./tabs-state");
 const use_network_status_1 = require("./use-network-status");
 /** How long continuous raw syncing stays a green pulse before the indeterminate circle. */
@@ -32,6 +33,19 @@ function disconnectedLabelSuffix(disconnectedContextCount) {
 function connectedLabelSuffix(connectedContextCount) {
     return `; ${connectedContextCount} ${connectedContextCount === 1 ? "group" : "groups"} connected`;
 }
+function withStuckAttention(presentation, stuckRecoveryCount) {
+    if (stuckRecoveryCount <= 0) {
+        return presentation;
+    }
+    const attention = stuckRecoveryCount === 1
+        ? "1 record needs attention"
+        : `${stuckRecoveryCount} records need attention`;
+    const labeled = { ...presentation, label: `${presentation.label}; ${attention}` };
+    if (presentation.colorClass === "text-danger") {
+        return labeled;
+    }
+    return { ...labeled, colorClass: "text-warning" };
+}
 function connectedGroupsOverlay(connectionCount, connectedContextCount) {
     if (connectionCount <= 0) {
         return undefined;
@@ -60,7 +74,7 @@ function getNetworkStatusPresentation(viewState, opts) {
             colorClass: "text-secondary",
         };
     }
-    const { connectedContextCount, connectionCount, disconnectedContextCount, errorCount, state, syncingContextCount, } = viewState.status;
+    const { connectedContextCount, connectionCount, disconnectedContextCount, errorCount, state, stuckRecoveryCount, syncingContextCount, } = viewState.status;
     const disconnectedOverlay = disconnectedContextCount > 0 && state !== "offline"
         ? { count: disconnectedContextCount }
         : undefined;
@@ -70,38 +84,38 @@ function getNetworkStatusPresentation(viewState, opts) {
     const groupsOverlay = connectedGroupsOverlay(connectionCount, connectedContextCount);
     const connectedSuffix = groupsOverlay ? connectedLabelSuffix(connectedContextCount) : "";
     if (state === "error") {
-        return {
+        return withStuckAttention({
             label: `Network error; ${errorCount} sync ${errorCount === 1 ? "error" : "errors"}; ${connectionCount} active ${connectionCount === 1 ? "connection" : "connections"}${connectedSuffix}${disconnectedSuffix}`,
             shortLabel: "Error",
             colorClass: "text-danger",
             mark: "solid",
             disconnectedGroupsOverlay: disconnectedOverlay,
             connectedGroupsOverlay: groupsOverlay,
-        };
+        }, stuckRecoveryCount);
     }
     if (state === "syncing" || opts?.holdSyncingVisual) {
         const longSync = state === "syncing" && opts?.syncingLongerThanGreenMs === true;
         const contextsLabel = state === "syncing"
             ? `${syncingContextCount} ${syncingContextCount === 1 ? "context" : "contexts"}`
             : "recent activity";
-        return {
+        return withStuckAttention({
             label: `Network syncing ${contextsLabel}; ${connectionCount} active ${connectionCount === 1 ? "connection" : "connections"}${connectedSuffix}${disconnectedSuffix}`,
             shortLabel: "Syncing",
             colorClass: longSync ? "text-primary" : "text-success",
             mark: longSync ? "indeterminate" : "pulse",
             disconnectedGroupsOverlay: disconnectedOverlay,
             connectedGroupsOverlay: groupsOverlay,
-        };
+        }, stuckRecoveryCount);
     }
     if (state === "offline") {
-        return {
+        return withStuckAttention({
             label: "Network offline; no active connections",
             shortLabel: "Offline",
             iconClass: "bi-cloud-slash-fill",
             colorClass: "text-secondary",
-        };
+        }, stuckRecoveryCount);
     }
-    return {
+    return withStuckAttention({
         label: `Network synced; ${connectionCount} active ${connectionCount === 1 ? "connection" : "connections"}${connectedSuffix}${disconnectedSuffix}`,
         shortLabel: "Synced",
         iconClass: "bi-check-circle-fill",
@@ -109,7 +123,7 @@ function getNetworkStatusPresentation(viewState, opts) {
         compactIcon: true,
         disconnectedGroupsOverlay: disconnectedOverlay,
         connectedGroupsOverlay: groupsOverlay,
-    };
+    }, stuckRecoveryCount);
 }
 function statusMarkBgClass(colorClass) {
     if (colorClass === "text-danger") {
@@ -118,6 +132,9 @@ function statusMarkBgClass(colorClass) {
     if (colorClass === "text-primary") {
         return "bg-primary";
     }
+    if (colorClass === "text-warning") {
+        return "bg-warning";
+    }
     return "bg-success";
 }
 function StatusMark({ mode, colorClass }) {
@@ -190,8 +207,14 @@ function ConnectedDevicesList({ loadState }) {
     }
     return ((0, jsx_runtime_1.jsx)("ul", { className: "small mb-0 ps-0", style: { maxHeight: "180px", overflowY: "auto" }, children: loadState.connections.map((connection) => ((0, jsx_runtime_1.jsx)(ConnectedDeviceRow, { connection: connection }, connection.deviceId))) }));
 }
-function NetworkStatusDetails({ detailsId, status, unavailable, connectionsLoadState, onUseInvite, onOpenIdentity, onOpenViewer, }) {
-    return ((0, jsx_runtime_1.jsx)("div", { id: detailsId, role: "dialog", "aria-label": "Network status details", className: "card shadow position-absolute end-0 mt-1", style: { top: "100%", width: "320px", zIndex: 1100 }, children: (0, jsx_runtime_1.jsxs)("div", { className: "card-body p-3", children: [(0, jsx_runtime_1.jsxs)("div", { className: "d-flex gap-2 mb-3", children: [(0, jsx_runtime_1.jsxs)("button", { type: "button", className: "btn btn-sm btn-outline-primary flex-fill", onClick: onUseInvite, children: [(0, jsx_runtime_1.jsx)("i", { className: "bi bi-qr-code me-1", "aria-hidden": "true" }), "Use Invite"] }), (0, jsx_runtime_1.jsxs)("button", { type: "button", className: "btn btn-sm btn-outline-primary flex-fill", onClick: onOpenIdentity, children: [(0, jsx_runtime_1.jsx)("i", { className: "bi bi-person-badge me-1", "aria-hidden": "true" }), "Identity"] })] }), (0, jsx_runtime_1.jsx)("h6", { className: "card-title mb-2", children: "Network status" }), unavailable || !status ? ((0, jsx_runtime_1.jsx)("p", { className: "small text-muted mb-3", children: "Network diagnostics are temporarily unavailable. The local host may still be starting or reconnecting." })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)("dl", { className: "row small mb-2", children: [(0, jsx_runtime_1.jsx)("dt", { className: "col-7", children: "Connections" }), (0, jsx_runtime_1.jsx)("dd", { className: "col-5 text-end", children: status.connectionCount }), (0, jsx_runtime_1.jsx)("dt", { className: "col-7", children: "Syncing contexts" }), (0, jsx_runtime_1.jsx)("dd", { className: "col-5 text-end", children: status.syncingContextCount }), (0, jsx_runtime_1.jsx)("dt", { className: "col-7", children: "Sync errors" }), (0, jsx_runtime_1.jsx)("dd", { className: "col-5 text-end", children: status.errorCount }), (0, jsx_runtime_1.jsx)("dt", { className: "col-7", children: "Groups connected" }), (0, jsx_runtime_1.jsx)("dd", { className: "col-5 text-end", children: status.connectedContextCount }), (0, jsx_runtime_1.jsx)("dt", { className: "col-7", children: "Groups offline" }), (0, jsx_runtime_1.jsx)("dd", { className: "col-5 text-end", children: status.disconnectedContextCount }), status.lastSuccessfulSyncAt != null && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("dt", { className: "col-7", children: "Last sync" }), (0, jsx_runtime_1.jsx)("dd", { className: "col-5 text-end text-truncate", title: new Date(status.lastSuccessfulSyncAt).toLocaleString(), children: formatRelativeSyncTime(status.lastSuccessfulSyncAt) })] }))] }), status.errors.length > 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "alert alert-danger py-2 px-2 small mb-2", children: [status.errors[0].message, status.errors.length > 1 && ` (+${status.errors.length - 1} more)`] })), (0, jsx_runtime_1.jsxs)("div", { className: "border-top pt-2 mt-1 mb-2", children: [(0, jsx_runtime_1.jsx)("div", { className: "small text-muted mb-1", children: "Devices" }), (0, jsx_runtime_1.jsx)(ConnectedDevicesList, { loadState: connectionsLoadState })] })] })), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "btn btn-sm btn-outline-primary w-100", onClick: onOpenViewer, children: "Open Network Viewer" })] }) }));
+function StatusCountRow({ label, value, className, }) {
+    const tone = className ? ` ${className}` : "";
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("dt", { className: `col-7${tone}`, children: label }), (0, jsx_runtime_1.jsx)("dd", { className: `col-5 text-end${tone}`, children: value })] }));
+}
+function NetworkStatusDetails({ detailsId, status, unavailable, connectionsLoadState, onUseInvite, onOpenIdentity, onOpenViewer, onOpenRecovery, }) {
+    return ((0, jsx_runtime_1.jsx)("div", { id: detailsId, role: "dialog", "aria-label": "Network status details", className: "card shadow position-absolute end-0 mt-1", style: { top: "100%", width: "320px", zIndex: 1100 }, children: (0, jsx_runtime_1.jsxs)("div", { className: "card-body p-3", children: [(0, jsx_runtime_1.jsxs)("div", { className: "d-flex gap-2 mb-3", children: [(0, jsx_runtime_1.jsxs)("button", { type: "button", className: "btn btn-sm btn-outline-primary flex-fill", onClick: onUseInvite, children: [(0, jsx_runtime_1.jsx)("i", { className: "bi bi-qr-code me-1", "aria-hidden": "true" }), "Use Invite"] }), (0, jsx_runtime_1.jsxs)("button", { type: "button", className: "btn btn-sm btn-outline-primary flex-fill", onClick: onOpenIdentity, children: [(0, jsx_runtime_1.jsx)("i", { className: "bi bi-person-badge me-1", "aria-hidden": "true" }), "Identity"] })] }), (0, jsx_runtime_1.jsx)("h6", { className: "card-title mb-2", children: "Network status" }), unavailable || !status ? ((0, jsx_runtime_1.jsx)("p", { className: "small text-muted mb-3", children: "Network diagnostics are temporarily unavailable. The local host may still be starting or reconnecting." })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)("dl", { className: "row small mb-2", children: [(0, jsx_runtime_1.jsx)(StatusCountRow, { label: "Connections", value: status.connectionCount }), (0, jsx_runtime_1.jsx)(StatusCountRow, { label: "Groups connected", value: status.connectedContextCount }), status.syncingContextCount > 0 && ((0, jsx_runtime_1.jsx)(StatusCountRow, { label: "Syncing contexts", value: status.syncingContextCount })), status.disconnectedContextCount > 0 && ((0, jsx_runtime_1.jsx)(StatusCountRow, { label: "Groups offline", value: status.disconnectedContextCount, className: "text-warning" })), status.errorCount > 0 && ((0, jsx_runtime_1.jsx)(StatusCountRow, { label: "Sync errors", value: status.errorCount })), status.lastSuccessfulSyncAt != null && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("dt", { className: "col-7", children: "Last sync" }), (0, jsx_runtime_1.jsx)("dd", { className: "col-5 text-end text-truncate", title: new Date(status.lastSuccessfulSyncAt).toLocaleString(), children: formatRelativeSyncTime(status.lastSuccessfulSyncAt) })] }))] }), status.errors.length > 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "alert alert-danger py-2 px-2 small mb-2", children: [status.errors[0].message, status.errors.length > 1 && ` (+${status.errors.length - 1} more)`] })), status.stuckRecoveryCount > 0 && ((0, jsx_runtime_1.jsx)("div", { className: "alert alert-warning py-2 px-2 small mb-2", children: status.stuckRecoveryCount === 1
+                                ? "1 record needs attention"
+                                : `${status.stuckRecoveryCount} records need attention` })), (0, jsx_runtime_1.jsxs)("div", { className: "border-top pt-2 mt-1 mb-2", children: [(0, jsx_runtime_1.jsx)("div", { className: "small text-muted mb-1", children: "Connected Devices" }), (0, jsx_runtime_1.jsx)(ConnectedDevicesList, { loadState: connectionsLoadState })] })] })), (0, jsx_runtime_1.jsx)("button", { type: "button", className: `btn btn-sm btn-outline-primary w-100${status && status.stuckRecoveryCount > 0 ? " mb-2" : ""}`, onClick: onOpenViewer, children: "Open Network Viewer" }), status && status.stuckRecoveryCount > 0 && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "btn btn-sm btn-warning w-100", onClick: onOpenRecovery, children: "Sync recovery" }))] }) }));
 }
 /** Accessible reactive network status button and details popover. */
 function NetworkStatusIndicator({ compact = false }) {
@@ -314,6 +337,11 @@ function NetworkStatusIndicator({ compact = false }) {
                     (0, tabs_state_1.goToTabPath)(identity_routes_1.IDENTITY_ACCOUNT_PATH);
                 }, onOpenViewer: () => {
                     setOpen(false);
+                    (0, network_viewer_section_1.networkViewerSection)("main");
+                    (0, tabs_state_1.goToTabPath)("network-viewer");
+                }, onOpenRecovery: () => {
+                    setOpen(false);
+                    (0, network_viewer_section_1.networkViewerSection)("sync-recovery");
                     (0, tabs_state_1.goToTabPath)("network-viewer");
                 } }))] }));
 }

package/dist/tabs-layout/network-status-indicator.test.js

@@ -8,6 +8,7 @@ const peers_sdk_1 = require("@peers-app/peers-sdk");
 const react_1 = require("@testing-library/react");
 const moment_1 = __importDefault(require("moment"));
 const identity_routes_1 = require("../screens/identity/identity-routes");
+const network_viewer_section_1 = require("../screens/network-viewer/network-viewer-section");
 const network_status_indicator_1 = require("./network-status-indicator");
 const goToTabPath = jest.fn();
 const getConnections = jest.fn();
@@ -33,6 +34,7 @@ function status(overrides) {
         errorCount: 0,
         disconnectedContextCount: 0,
         connectedContextCount: 0,
+        stuckRecoveryCount: 0,
         errors: [],
         ...overrides,
     };
@@ -128,6 +130,28 @@ describe("getNetworkStatusPresentation", () => {
             mark: "indeterminate",
         });
     });
+    it("turns yellow for stuck recovery without hiding sync activity or errors", () => {
+        expect((0, network_status_indicator_1.getNetworkStatusPresentation)({
+            availability: "ready",
+            status: status({ state: "synced", stuckRecoveryCount: 2 }),
+        })).toMatchObject({
+            colorClass: "text-warning",
+            iconClass: "bi-check-circle-fill",
+            label: expect.stringContaining("2 records need attention"),
+        });
+        expect((0, network_status_indicator_1.getNetworkStatusPresentation)({
+            availability: "ready",
+            status: status({ state: "syncing", syncingContextCount: 1, stuckRecoveryCount: 1 }),
+        }, { syncingLongerThanGreenMs: true })).toMatchObject({
+            colorClass: "text-warning",
+            mark: "indeterminate",
+            label: expect.stringContaining("1 record needs attention"),
+        });
+        expect((0, network_status_indicator_1.getNetworkStatusPresentation)({
+            availability: "ready",
+            status: status({ state: "error", errorCount: 1, stuckRecoveryCount: 4 }),
+        }).colorClass).toBe("text-danger");
+    });
     it("holds a green pulse while waiting for stable synced", () => {
         expect((0, network_status_indicator_1.getNetworkStatusPresentation)({ availability: "ready", status: status({ state: "synced" }) }, { holdSyncingVisual: true, syncingLongerThanGreenMs: true })).toMatchObject({
             shortLabel: "Syncing",
@@ -186,10 +210,25 @@ describe("getNetworkStatusPresentation", () => {
             }),
         }).connectedGroupsOverlay).toBeUndefined();
     });
+    it("turns an offline indicator yellow when recovery is stuck and keeps the offline icon", () => {
+        expect((0, network_status_indicator_1.getNetworkStatusPresentation)({
+            availability: "ready",
+            status: status({ state: "offline", connectionCount: 0, stuckRecoveryCount: 2 }),
+        })).toMatchObject({
+            iconClass: "bi-cloud-slash-fill",
+            colorClass: "text-warning",
+            label: expect.stringContaining("2 records need attention"),
+        });
+        expect((0, network_status_indicator_1.getNetworkStatusPresentation)({
+            availability: "ready",
+            status: status({ state: "error", errorCount: 1, stuckRecoveryCount: 2 }),
+        }).colorClass).toBe("text-danger");
+    });
 });
 describe("NetworkStatusIndicator", () => {
     beforeEach(() => {
         mockViewState = { availability: "loading" };
+        (0, network_viewer_section_1.networkViewerSection)("main");
         getConnections.mockReset();
         getConnections.mockResolvedValue({ connections: [] });
         jest.clearAllMocks();
@@ -462,5 +501,75 @@ describe("NetworkStatusIndicator", () => {
         react_1.fireEvent.click(view.getByRole("button", { name: /Network error/ }));
         react_1.fireEvent.click(view.getByRole("button", { name: "Open Network Viewer" }));
         expect(goToTabPath).toHaveBeenCalledWith("network-viewer");
+        expect((0, network_viewer_section_1.networkViewerSection)()).toBe("main");
+    });
+    it("hides zero problem counts and Sync recovery when nothing needs attention", async () => {
+        mockViewState = {
+            availability: "ready",
+            status: status({
+                state: "synced",
+                connectionCount: 4,
+                connectedContextCount: 5,
+                lastSuccessfulSyncAt: Date.parse("2026-09-27T16:00:00.000Z"),
+            }),
+        };
+        const view = (0, react_1.render)((0, jsx_runtime_1.jsx)(network_status_indicator_1.NetworkStatusIndicator, {}));
+        await openNetworkDetails(view, /Network synced/);
+        const labels = [...view.getByRole("dialog").querySelectorAll("dt")].map((el) => el.textContent);
+        expect(labels).toEqual(["Connections", "Groups connected", "Last sync"]);
+        expect(view.queryByRole("button", { name: "Sync recovery" })).toBeNull();
+    });
+    it("orders non-zero status rows and offers Sync recovery when records are stuck", async () => {
+        mockViewState = {
+            availability: "ready",
+            status: status({
+                state: "error",
+                connectionCount: 4,
+                connectedContextCount: 5,
+                disconnectedContextCount: 1,
+                syncingContextCount: 2,
+                errorCount: 3,
+                stuckRecoveryCount: 1,
+                lastSuccessfulSyncAt: Date.parse("2026-09-27T16:00:00.000Z"),
+                errors: [{ dataContextId: "context", message: "sync failed", occurredAt: 1 }],
+            }),
+        };
+        const view = (0, react_1.render)((0, jsx_runtime_1.jsx)(network_status_indicator_1.NetworkStatusIndicator, {}));
+        await openNetworkDetails(view, /Network error/);
+        const labels = [...view.getByRole("dialog").querySelectorAll("dt")].map((el) => el.textContent);
+        expect(labels).toEqual([
+            "Connections",
+            "Groups connected",
+            "Syncing contexts",
+            "Groups offline",
+            "Sync errors",
+            "Last sync",
+        ]);
+        const groupsOffline = view.getByText("Groups offline");
+        expect(groupsOffline.className).toContain("text-warning");
+        expect(groupsOffline.nextElementSibling?.textContent).toBe("1");
+        expect(groupsOffline.nextElementSibling?.className).toContain("text-warning");
+        expect(view.getByRole("button", { name: "Sync recovery" }).className).toContain("btn-warning");
+    });
+    it("opens Sync recovery inside the Network tab", async () => {
+        (0, network_viewer_section_1.networkViewerSection)("main");
+        mockViewState = {
+            availability: "ready",
+            status: status({ state: "synced", stuckRecoveryCount: 2 }),
+        };
+        const view = (0, react_1.render)((0, jsx_runtime_1.jsx)(network_status_indicator_1.NetworkStatusIndicator, {}));
+        await openNetworkDetails(view, /Network synced/);
+        react_1.fireEvent.click(view.getByRole("button", { name: "Sync recovery" }));
+        expect((0, network_viewer_section_1.networkViewerSection)()).toBe("sync-recovery");
+        expect(goToTabPath).toHaveBeenCalledWith("network-viewer");
+        expect(goToTabPath).not.toHaveBeenCalledWith("sync-recovery");
+        expect(view.queryByRole("dialog", { name: "Network status details" })).toBeNull();
     });
 });
+async function openNetworkDetails(view, name) {
+    react_1.fireEvent.click(view.getByRole("button", { name }));
+    await (0, react_1.waitFor)(() => expect(getConnections).toHaveBeenCalled());
+    await (0, react_1.act)(async () => {
+        await Promise.resolve();
+    });
+}

package/dist/tabs-layout/use-network-status.test.js

@@ -16,6 +16,7 @@ function makeStatus(overrides = {}) {
         errorCount: 0,
         disconnectedContextCount: 0,
         connectedContextCount: 0,
+        stuckRecoveryCount: 0,
         errors: [],
         ...overrides,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-ui",
-  "version": "0.25.8",
+  "version": "0.25.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-ui.git"
@@ -28,7 +28,7 @@
     "lint:fix": "biome check --write ."
   },
   "peerDependencies": {
-    "@peers-app/peers-sdk": "^0.25.8",
+    "@peers-app/peers-sdk": "^0.25.9",
     "bootstrap": "^5.3.3",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
@@ -39,7 +39,7 @@
     "@babel/preset-react": "^7.24.1",
     "@babel/preset-typescript": "^7.27.1",
     "@biomejs/biome": "2.3.11",
-    "@peers-app/peers-sdk": "0.25.8",
+    "@peers-app/peers-sdk": "0.25.9",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",

package/src/screens/network-viewer/network-viewer-section.ts

@@ -0,0 +1,12 @@
+import { observable } from "@peers-app/peers-sdk";
+
+/** Pane shown inside the Network Viewer tab. */
+export type NetworkViewerSection = "main" | "sync-recovery";
+
+/**
+ * Which Network Viewer pane is showing.
+ *
+ * The status overlay sets this before focusing the Network tab, so Sync recovery
+ * opens inside that tab instead of replacing whatever screen is current.
+ */
+export const networkViewerSection = observable<NetworkViewerSection>("main");

package/src/screens/network-viewer/network-viewer.section.test.tsx

@@ -0,0 +1,68 @@
+import { fireEvent, render, waitFor } from "@testing-library/react";
+import { NetworkViewerList } from "./network-viewer";
+import { networkViewerSection } from "./network-viewer-section";
+
+jest.mock("../../ui-router/ui-loader", () => ({
+  registerInternalPeersUI: jest.fn(),
+}));
+
+jest.mock("./network-viewer-ipc", () => ({
+  getNetworkDiagnosticsConsumer: async () => ({
+    tools: {
+      getOverview: async () => ({
+        overview: {
+          localDeviceId: "device",
+          localUserId: "user",
+          totalConnections: 0,
+          availableSlots: 8,
+          maxConnections: 8,
+          cpuPercent: 0,
+          memPercent: 0,
+          groups: [],
+        },
+      }),
+      getConnections: async () => ({ connections: [] }),
+      getGroupSyncStatus: async () => ({ groups: [] }),
+      getDisconnectedDevices: async () => ({ devices: [] }),
+      getSyncRecoveryEntries: async () => ({ entries: [] }),
+    },
+    observables: {
+      status: {
+        subscribe: () => ({ dispose() {} }),
+      },
+    },
+  }),
+  getNetworkControlConsumer: async () => ({ tools: {} }),
+  getNetworkViewerPlatformApi: () => undefined,
+}));
+
+describe("Network Viewer sections", () => {
+  beforeEach(() => {
+    networkViewerSection("main");
+  });
+
+  it("shows Sync recovery in place and returns to the overview", async () => {
+    const view = render(<NetworkViewerList />);
+    await waitFor(() => {
+      expect(view.getByRole("heading", { name: "Network Viewer" })).toBeTruthy();
+    });
+
+    fireEvent.click(view.getByRole("button", { name: "Sync recovery" }));
+    expect(await view.findByRole("heading", { name: "Sync recovery" })).toBeTruthy();
+    expect(view.queryByRole("heading", { name: "Network Viewer" })).toBeNull();
+
+    fireEvent.click(view.getByRole("button", { name: "Back" }));
+    expect(view.getByRole("heading", { name: "Network Viewer" })).toBeTruthy();
+    view.unmount();
+  });
+
+  it("opens on Sync recovery when the overlay selects that pane", async () => {
+    networkViewerSection("sync-recovery");
+    const view = render(<NetworkViewerList />);
+
+    expect(await view.findByRole("heading", { name: "Sync recovery" })).toBeTruthy();
+    expect(await view.findByText("No records are waiting in the recovery queue.")).toBeTruthy();
+    expect(view.queryByRole("heading", { name: "Network Viewer" })).toBeNull();
+    view.unmount();
+  });
+});

package/src/screens/network-viewer/network-viewer.tsx

@@ -8,6 +8,7 @@ import {
 import { useCallback, useEffect, useState } from "react";
 import { LoadingIndicator } from "../../components/loading-indicator";
 import { TrustLevelBadge } from "../../components/trust-level-badge";
+import { useObservable } from "../../hooks";
 import { registerInternalPeersUI } from "../../ui-router/ui-loader";
 import { ConnectionTroubleshooter } from "./connection-troubleshooter";
 import { DeviceDetailsModal } from "./device-details-modal";
@@ -17,6 +18,8 @@ import {
   getNetworkDiagnosticsConsumer,
   getNetworkViewerPlatformApi,
 } from "./network-viewer-ipc";
+import { networkViewerSection } from "./network-viewer-section";
+import { SyncRecoveryScreen } from "./sync-recovery";
 import { UsageGraph } from "./usage-graph";
 
 /** Format bytes to human-readable string (KB, MB, GB) */
@@ -38,6 +41,12 @@ function formatRate(mbps: number | undefined): string {
   return `${mbps.toFixed(2)} MB/s`;
 }
 
+/**
+ * Network Viewer screen.
+ *
+ * Shows connections, group sync, and disconnected devices, and hosts the
+ * Sync Recovery pane selected from the network status indicator.
+ */
 export function NetworkViewerList() {
   const [overview, setOverview] = useState<INetworkOverview | null>(null);
   const [connections, setConnections] = useState<INetworkConnectionInfo[]>([]);
@@ -49,6 +58,7 @@ export function NetworkViewerList() {
   const [selectedGroupId, setSelectedGroupId] = useState<string | null>(null);
   const [connecting, setConnecting] = useState<Set<string>>(new Set());
   const [showTroubleshooter, setShowTroubleshooter] = useState(false);
+  const [viewerSection] = useObservable(networkViewerSection);
 
   const loadData = useCallback(async () => {
     try {
@@ -159,6 +169,16 @@ export function NetworkViewerList() {
     return () => clearInterval(interval);
   }, [loadData]);
 
+  useEffect(() => {
+    if (viewerSection === "sync-recovery") {
+      setShowTroubleshooter(false);
+    }
+  }, [viewerSection]);
+
+  if (viewerSection === "sync-recovery") {
+    return <SyncRecoveryScreen onBack={() => networkViewerSection("main")} />;
+  }
+
   if (loading) {
     return <LoadingIndicator />;
   }
@@ -190,6 +210,13 @@ export function NetworkViewerList() {
               Troubleshoot
             </button>
           )}
+          <button
+            className="btn btn-sm btn-outline-secondary"
+            onClick={() => networkViewerSection("sync-recovery")}
+            title="Records that could not be materialized"
+          >
+            Sync recovery
+          </button>
           <button className="btn btn-sm btn-primary" onClick={handleRefresh} disabled={refreshing}>
             <i className={`bi bi-arrow-clockwise ${refreshing ? "spin" : ""}`}></i>
             {refreshing ? " Refreshing..." : " Refresh"}

package/src/screens/network-viewer/sync-recovery.test.tsx

@@ -0,0 +1,114 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { SyncRecoveryScreen } from "./sync-recovery";
+
+const mockResolveSyncRecovery = jest.fn(async () => ({
+  success: false,
+  message: "Permission denied for Shared Group: requires Owner",
+}));
+
+jest.mock("./network-viewer-ipc", () => ({
+  getNetworkDiagnosticsConsumer: async () => ({
+    tools: {
+      getSyncRecoveryEntries: async () => ({
+        entries: [
+          {
+            dataContextId: "personal",
+            dataContextName: "Personal",
+            syncRecoveryId: "queue-1",
+            tableName: "Messages",
+            recordId: "00mflddy2sbk393s47smn4tgl",
+            firstFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            lastFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            attemptCount: 3,
+            latestError:
+              'Validation on insert failed for Messages: [{"code":"custom","message":"assistant id was empty","path":["assistantId"]}]',
+            status: "parked",
+            parkedReason: "schema",
+            stuck: true,
+            localRowExists: false,
+            recordSummary: "hello from the stored message",
+            queuedRecordPreview: '{\n  "message": "hello from the stored message"\n}',
+            recordPreview: '{\n  "message": "hello from the stored message"\n}',
+            changeCreatedAt: Date.parse("2026-09-10T17:16:02Z"),
+          },
+          {
+            dataContextId: "personal",
+            dataContextName: "Personal",
+            syncRecoveryId: "queue-2",
+            tableName: "UniqueNames",
+            recordId: "00mflddy2sbk393s47smn4tgm",
+            firstFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            lastFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            attemptCount: 1,
+            latestError: "UNIQUE constraint failed: UniqueNames.name",
+            status: "parked",
+            parkedReason: "unique-conflict",
+            stuck: true,
+            localRowExists: true,
+            conflictingRecordId: "00mflddy2sbk393s47smn4tgn",
+            tombstoneRecordId: "00mflddy2sbk393s47smn4tgm",
+            recordSummary: "shared",
+            keptRecordPreview: '{\n  "name": "shared",\n  "value": "local"\n}',
+            queuedRecordPreview: '{\n  "name": "shared",\n  "value": "rejected"\n}',
+            recordPreview: '{\n  "name": "shared",\n  "value": "local"\n}',
+          },
+        ],
+      }),
+    },
+    observables: {
+      status: {
+        subscribe: () => ({ dispose() {} }),
+      },
+    },
+  }),
+  getNetworkControlConsumer: async () => ({
+    tools: {
+      resolveSyncRecovery: () => mockResolveSyncRecovery(),
+    },
+  }),
+}));
+
+describe("SyncRecoveryScreen", () => {
+  it("shows the full error, status help, action help, and stored record", async () => {
+    render(<SyncRecoveryScreen onBack={() => undefined} />);
+
+    expect(await screen.findByText("hello from the stored message")).toBeTruthy();
+    expect(screen.getByText(/Validation on insert failed/)).toBeTruthy();
+    expect(screen.queryByText(/assistant id was empty/)).toBeNull();
+
+    fireEvent.click(screen.getAllByRole("button", { name: "Show error details" })[0]);
+    const error = screen.getByText(/assistant id was empty/);
+    expect(error.tagName).toBe("PRE");
+
+    fireEvent.click(screen.getByRole("button", { name: "About status Parked, schema" }));
+    expect(screen.getByText(/does not match this device's rules/)).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "About these actions" }));
+    expect(screen.getByText(/only the other row is stored/)).toBeTruthy();
+
+    fireEvent.click(screen.getAllByRole("button", { name: "Show record details" })[0]);
+    expect(screen.getByText(/Change written/)).toBeTruthy();
+    expect(screen.getByText("Queued change")).toBeTruthy();
+    expect(screen.getByText(/"message": "hello from the stored message"/)).toBeTruthy();
+  });
+
+  it("labels the row Keep will snapshot separately from a different queued change", async () => {
+    render(<SyncRecoveryScreen onBack={() => undefined} />);
+    fireEvent.click((await screen.findAllByRole("button", { name: "Show record details" }))[1]);
+    expect(screen.getByText("This device's version")).toBeTruthy();
+    expect(screen.getByText(/"value": "local"/)).toBeTruthy();
+    expect(screen.getByText("Queued change")).toBeTruthy();
+    expect(screen.getByText(/"value": "rejected"/)).toBeTruthy();
+    expect(screen.getByText(/tombstones this queued id/)).toBeTruthy();
+    expect(screen.queryByText(/Keep deletes/)).toBeNull();
+  });
+
+  it("keeps a failed action message after the list reloads", async () => {
+    render(<SyncRecoveryScreen onBack={() => undefined} />);
+    fireEvent.click((await screen.findAllByRole("button", { name: "Ignore on this device" }))[0]);
+    expect(
+      await screen.findByText("Permission denied for Shared Group: requires Owner"),
+    ).toBeTruthy();
+    expect(screen.getByText("hello from the stored message")).toBeTruthy();
+  });
+});