The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(ui): reload once when a lazy chunk or its CSS fails to load (#17349)
Devin Foley73526559b59d
diff --git a/tests/e2e/chunk-load-recovery.spec.ts b/tests/e2e/chunk-load-recovery.spec.tsnew file mode 100644index 0000000000..f3f9c4c81d--- /dev/null+++ b/tests/e2e/chunk-load-recovery.spec.ts@@ -0,0 +1,81 @@+import { randomUUID } from "node:crypto";+import { expect, test, type APIRequestContext, type Page } from "@playwright/test";++async function json(response: Awaited<ReturnType<APIRequestContext["get"]>>) {+ expect(response.ok(), `${response.status()}: ${await response.text()}`).toBe(true);+ return response.json();+}++async function failFirstTaskCss(page: Page) {+ const counts = { failed: 0, served: 0, documents: 0 };+ await page.route(/\/assets\/issue-detail-[^/]+\.css$/, async (route) => {+ if (counts.failed === 0) {+ counts.failed += 1;+ await route.abort("failed");+ return;+ }+ counts.served += 1;+ await route.continue();+ });+ page.on("request", (request) => {+ if (request.resourceType() === "document" && request.frame() === page.mainFrame()) counts.documents += 1;+ });+ return counts;+}++test.use({ serviceWorkers: "block" });++for (const entry of ["task", "agents"] as const) {+ test(`a failed task-page CSS preload recovers with one reload (${entry} page)`, async ({ page, request }) => {+ const company = await json(await request.post("/api/companies", {+ data: { name: `Chunk recovery ${randomUUID()}` },+ }));+ const issue = await json(await request.post(`/api/companies/${company.id}/issues`, {+ data: { title: "Open after a failed stylesheet", status: "backlog" },+ }));+ const counts = await failFirstTaskCss(page);++ if (entry === "task") {+ await page.goto(`/${company.issuePrefix}/issues/${issue.identifier}`);+ await expect(page.getByRole("heading", { name: issue.title, exact: true })).toBeVisible();+ } else {+ await page.goto(`/${company.issuePrefix}/agents`);+ await expect(page.getByRole("heading", { name: "Agents", exact: true }).first()).toBeVisible();+ }++ await expect(page.getByText("This page hit an error")).toHaveCount(0);+ expect(counts.failed).toBe(1);+ expect(counts.served).toBeGreaterThan(0);+ expect(counts.documents).toBe(2);+ });+}++for (const entry of ["task", "agents"] as const) {+ test(`a task-page CSS asset that stays broken reloads once, then shows the error (${entry} page)`, async ({ page, request }) => {+ const company = await json(await request.post("/api/companies", {+ data: { name: `Chunk recovery ${randomUUID()}` },+ }));+ const issue = await json(await request.post(`/api/companies/${company.id}/issues`, {+ data: { title: "Open with a broken stylesheet", status: "backlog" },+ }));+ let failed = 0;+ let documents = 0;+ await page.route(/\/assets\/issue-detail-[^/]+\.css$/, async (route) => {+ failed += 1;+ await route.abort("failed");+ });+ page.on("request", (request) => {+ if (request.resourceType() === "document" && request.frame() === page.mainFrame()) documents += 1;+ });++ await page.goto(entry === "task"+ ? `/${company.issuePrefix}/issues/${issue.identifier}`+ : `/${company.issuePrefix}/agents`);++ await expect(page.getByText("This page hit an error")).toBeVisible();+ await expect(page.getByText(/Unable to preload CSS for .*issue-detail-/)).toBeVisible();+ await page.waitForTimeout(1_000);+ expect(documents).toBe(2);+ expect(failed).toBe(2);+ });+}diff --git a/ui/src/App.tsx b/ui/src/App.tsxindex 24f19888e0..b556a3cbac 100644--- a/ui/src/App.tsx+++ b/ui/src/App.tsx@@ -54,7 +54,9 @@ const ProductionLayout = lazy(() => import("./components/Layout.production").theconst TaskChatLab = lazy(() => import("./pages/TaskChatLab").then((module) => ({ default: module.TaskChatLab })));const Issues = lazy(() => import("./pages/Issues").then((module) => ({ default: module.Issues })));-const loadIssueDetail = () => import("./pages/IssueDetail").then((module) => ({ default: module.IssueDetail }));+let issueDetailLoad: Promise<{ default: typeof import("./pages/IssueDetail").IssueDetail }> | undefined;+const loadIssueDetail = () =>+ (issueDetailLoad ??= import("./pages/IssueDetail").then((module) => ({ default: module.IssueDetail })));const IssueDetail = lazy(loadIssueDetail);const AgentChat = lazy(() => import("./pages/AgentChat").then((module) => ({ default: module.AgentChat })));const IssueChatLongThreadPerf = lazy(() => import("./pages/IssueChatLongThreadPerf").then((module) => ({ default: module.IssueChatLongThreadPerf })));diff --git a/ui/src/components/AppErrorBoundary.test.tsx b/ui/src/components/AppErrorBoundary.test.tsxindex d5bd891903..f5bdd90fa4 100644--- a/ui/src/components/AppErrorBoundary.test.tsx+++ b/ui/src/components/AppErrorBoundary.test.tsx@@ -1,16 +1,31 @@// @vitest-environment jsdom-import { act, useEffect } from "react";+import { act, lazy, Suspense, useEffect } from "react";import { createRoot } from "react-dom/client";import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { createChunkLoadRecovery, RELOAD_ABANDONED_MS } from "@/lib/chunk-load-recovery";import { AppErrorBoundary } from "./AppErrorBoundary";const captureBrowserExceptionMock = vi.hoisted(() => vi.fn());+const reloadMock = vi.hoisted(() => vi.fn());vi.mock("@/lib/sentry", () => ({captureBrowserException: (...args: unknown[]) => captureBrowserExceptionMock(...args),}));+const chunkRecovery = vi.hoisted(() => ({+ current: null as null | ReturnType<typeof import("@/lib/chunk-load-recovery").createChunkLoadRecovery>,+}));++vi.mock("@/lib/chunk-load-recovery", async (importOriginal) => {+ const actual = await importOriginal<typeof import("@/lib/chunk-load-recovery")>();+ return {+ ...actual,+ reloadForChunkLoadError: (error: unknown) => chunkRecovery.current!.reloadForChunkLoadError(error),+ onChunkLoadReloadAbandoned: (listener: () => void) => chunkRecovery.current!.onChunkLoadReloadAbandoned(listener),+ };+});+function BoomRender(): never {throw new Error("Maximum update depth exceeded");}@@ -27,6 +42,9 @@ describe("AppErrorBoundary", () => {let consoleErrorSpy: ReturnType<typeof vi.spyOn>;beforeEach(() => {+ reloadMock.mockReset();+ window.sessionStorage.clear();+ chunkRecovery.current = createChunkLoadRecovery({ reload: reloadMock });container = document.createElement("div");document.body.appendChild(container);// React logs caught render errors to console.error; silence the expected noise.@@ -68,6 +86,52 @@ describe("AppErrorBoundary", () => {});});+ it("reloads once for a failed lazy chunk, then shows the prompt if it fails again", async () => {+ const chunkError = () => new Error("Failed to fetch dynamically imported module: https://paperclip.example/assets/layout.js");+ const root = createRoot(container);+ const FailedLayout = lazy(async () => { throw chunkError(); });+ await act(async () => {+ root.render(<AppErrorBoundary><Suspense fallback={null}><FailedLayout /></Suspense></AppErrorBoundary>);+ });+ expect(reloadMock).toHaveBeenCalledTimes(1);+ expect(captureBrowserExceptionMock).not.toHaveBeenCalled();+ expect(container.querySelector('[role="status"]')?.textContent).toContain("Reloading Paperclip");+ act(() => root.unmount());++ chunkRecovery.current = createChunkLoadRecovery({ reload: reloadMock });+ const nextRoot = createRoot(container);+ const StillFailedLayout = lazy(async () => { throw chunkError(); });+ await act(async () => {+ nextRoot.render(<AppErrorBoundary><Suspense fallback={null}><StillFailedLayout /></Suspense></AppErrorBoundary>);+ });+ expect(reloadMock).toHaveBeenCalledTimes(1);+ expect(captureBrowserExceptionMock).toHaveBeenCalledTimes(1);+ expect(container.textContent).toContain("Paperclip hit an error");+ act(() => nextRoot.unmount());+ });++ it("shows and reports the error when the recovery reload is cancelled", async () => {+ vi.useFakeTimers();+ try {+ const root = createRoot(container);+ const FailedLayout = lazy(async () => {+ throw new Error("Failed to fetch dynamically imported module: https://paperclip.example/assets/layout.js");+ });+ await act(async () => {+ root.render(<AppErrorBoundary><Suspense fallback={null}><FailedLayout /></Suspense></AppErrorBoundary>);+ });+ expect(reloadMock).toHaveBeenCalledTimes(1);+ expect(captureBrowserExceptionMock).not.toHaveBeenCalled();++ act(() => { vi.advanceTimersByTime(RELOAD_ABANDONED_MS); });+ expect(container.textContent).toContain("Paperclip hit an error");+ expect(captureBrowserExceptionMock).toHaveBeenCalledTimes(1);+ act(() => root.unmount());+ } finally {+ vi.useRealTimers();+ }+ });+it("catches errors thrown from effects, not just render", () => {const root = createRoot(container);act(() => {diff --git a/ui/src/components/AppErrorBoundary.tsx b/ui/src/components/AppErrorBoundary.tsxindex 671259edbd..97780600f2 100644--- a/ui/src/components/AppErrorBoundary.tsx+++ b/ui/src/components/AppErrorBoundary.tsx@@ -1,8 +1,10 @@import { Component, type ErrorInfo, type ReactNode } from "react";+import { onChunkLoadReloadAbandoned, reloadForChunkLoadError } from "@/lib/chunk-load-recovery";import { captureBrowserException } from "@/lib/sentry";type AppErrorBoundaryState = {error: Error | null;+ reloading: boolean;};/**@@ -17,20 +19,48 @@ type AppErrorBoundaryState = {* crash being handled may have originated inside any of those providers.*/export class AppErrorBoundary extends Component<{ children: ReactNode }, AppErrorBoundaryState> {- override state: AppErrorBoundaryState = { error: null };+ override state: AppErrorBoundaryState = { error: null, reloading: false };+ private stopWaitingForReload: (() => void) | null = null;- static getDerivedStateFromError(error: unknown): AppErrorBoundaryState {+ static getDerivedStateFromError(error: unknown): Partial<AppErrorBoundaryState> {return { error: error instanceof Error ? error : new Error(String(error)) };}override componentDidCatch(error: unknown, info: ErrorInfo): void {+ this.stopWaitingForReload?.();+ this.stopWaitingForReload = null;+ if (reloadForChunkLoadError(error)) {+ this.setState({ reloading: true });+ this.stopWaitingForReload = onChunkLoadReloadAbandoned(() => {+ this.stopWaitingForReload = null;+ this.setState({ reloading: false });+ this.report(error, info);+ });+ return;+ }+ this.report(error, info);+ }++ override componentWillUnmount(): void {+ this.stopWaitingForReload?.();+ this.stopWaitingForReload = null;+ }++ private report(error: unknown, info: ErrorInfo): void {console.error("App shell crashed", { error, componentStack: info.componentStack });captureBrowserException(error, { boundary: "app", componentStack: info.componentStack });}override render() {- const { error } = this.state;+ const { error, reloading } = this.state;if (!error) return this.props.children;+ if (reloading) {+ return (+ <div role="status" className="flex min-h-screen items-center justify-center text-sm text-muted-foreground">+ Reloading Paperclip…+ </div>+ );+ }return (<div className="mx-auto flex min-h-screen max-w-2xl flex-col justify-center space-y-4 px-4 py-10">diff --git a/ui/src/components/RouteErrorBoundary.test.tsx b/ui/src/components/RouteErrorBoundary.test.tsxindex 1a50194966..81f5ee80fe 100644--- a/ui/src/components/RouteErrorBoundary.test.tsx+++ b/ui/src/components/RouteErrorBoundary.test.tsx@@ -3,11 +3,13 @@import { act, lazy } from "react";import { createRoot } from "react-dom/client";import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { createChunkLoadRecovery, RELOAD_ABANDONED_MS } from "@/lib/chunk-load-recovery";import { RouteErrorBoundary } from "./RouteErrorBoundary";const navigateMock = vi.hoisted(() => vi.fn());const routerLocation = vi.hoisted(() => ({ current: { pathname: "/co/agents/new", search: "?adapterType=claude_local" } }));const captureBrowserExceptionMock = vi.hoisted(() => vi.fn());+const reloadMock = vi.hoisted(() => vi.fn());vi.mock("@/lib/router", () => ({useLocation: () => routerLocation.current,@@ -18,6 +20,19 @@ vi.mock("@/lib/sentry", () => ({captureBrowserException: (...args: unknown[]) => captureBrowserExceptionMock(...args),}));+const chunkRecovery = vi.hoisted(() => ({+ current: null as null | ReturnType<typeof import("@/lib/chunk-load-recovery").createChunkLoadRecovery>,+}));++vi.mock("@/lib/chunk-load-recovery", async (importOriginal) => {+ const actual = await importOriginal<typeof import("@/lib/chunk-load-recovery")>();+ return {+ ...actual,+ reloadForChunkLoadError: (error: unknown) => chunkRecovery.current!.reloadForChunkLoadError(error),+ onChunkLoadReloadAbandoned: (listener: () => void) => chunkRecovery.current!.onChunkLoadReloadAbandoned(listener),+ };+});+function Boom(): never {throw new Error("Maximum update depth exceeded");}@@ -29,6 +44,9 @@ describe("RouteErrorBoundary", () => {beforeEach(() => {navigateMock.mockReset();routerLocation.current = { pathname: "/co/agents/new", search: "?adapterType=claude_local" };+ reloadMock.mockReset();+ window.sessionStorage.clear();+ chunkRecovery.current = createChunkLoadRecovery({ reload: reloadMock });container = document.createElement("div");document.body.appendChild(container);// React logs caught render errors to console.error; silence the expected noise.@@ -63,10 +81,57 @@ describe("RouteErrorBoundary", () => {act(() => root.unmount());});- it("contains a failed chunk load and recovers when navigating back to a task", async () => {+ it("reloads once for a failed route CSS preload instead of reporting it", async () => {+ const FailedPage = lazy(async () => {+ throw new Error("Unable to preload CSS for https://paperclip.example/assets/issue-detail-CIbQo9zW.css");+ });+ const root = createRoot(container);+ await act(async () => { root.render(<RouteErrorBoundary><FailedPage /></RouteErrorBoundary>); });+ expect(reloadMock).toHaveBeenCalledTimes(1);+ expect(captureBrowserExceptionMock).not.toHaveBeenCalled();+ expect(container.querySelector('[role="status"]')?.textContent).toContain("Loading");+ expect(container.textContent).not.toContain("This page hit an error");+ act(() => root.unmount());+ });++ it("shows and reports the error when the recovery reload is cancelled", async () => {+ vi.useFakeTimers();+ try {+ const FailedPage = lazy(async () => {+ throw new Error("Unable to preload CSS for https://paperclip.example/assets/issue-detail-CIbQo9zW.css");+ });+ const root = createRoot(container);+ await act(async () => { root.render(<RouteErrorBoundary><FailedPage /></RouteErrorBoundary>); });+ expect(reloadMock).toHaveBeenCalledTimes(1);+ expect(container.querySelector('[role="status"]')?.textContent).toContain("Loading");++ act(() => { vi.advanceTimersByTime(RELOAD_ABANDONED_MS); });+ expect(container.textContent).toContain("This page hit an error");+ expect(container.textContent).toContain("Unable to preload CSS");+ expect(captureBrowserExceptionMock).toHaveBeenCalledTimes(1);+ expect(captureBrowserExceptionMock).toHaveBeenCalledWith(expect.any(Error), {+ boundary: "route", componentStack: expect.any(String),+ });++ const AnotherFailedPage = lazy(async () => { throw new Error("Failed to fetch dynamically imported module"); });+ routerLocation.current = { pathname: "/co/issues/CO-1", search: "" };+ await act(async () => { root.render(<RouteErrorBoundary><AnotherFailedPage /></RouteErrorBoundary>); });+ expect(reloadMock).toHaveBeenCalledTimes(1);+ expect(captureBrowserExceptionMock).toHaveBeenCalledTimes(2);+ expect(container.textContent).toContain("Failed to fetch dynamically imported module");+ act(() => root.unmount());+ } finally {+ vi.useRealTimers();+ }+ });++ it("contains a repeated chunk load failure and recovers when navigating back to a task", async () => {+ window.sessionStorage.setItem("paperclip:chunk-load-reload-at", String(Date.now()));const FailedPage = lazy(async () => { throw new Error("Failed to fetch dynamically imported module"); });const root = createRoot(container);await act(async () => { root.render(<RouteErrorBoundary><FailedPage /></RouteErrorBoundary>); });+ expect(reloadMock).not.toHaveBeenCalled();+ expect(captureBrowserExceptionMock).toHaveBeenCalledTimes(1);expect(container.textContent).toContain("This page hit an error");routerLocation.current = { pathname: "/co/issues/CO-1", search: "" };await act(async () => { root.render(<RouteErrorBoundary><div>Saved conversation</div></RouteErrorBoundary>); });diff --git a/ui/src/components/RouteErrorBoundary.tsx b/ui/src/components/RouteErrorBoundary.tsxindex aba128c130..be006f1961 100644--- a/ui/src/components/RouteErrorBoundary.tsx+++ b/ui/src/components/RouteErrorBoundary.tsx@@ -1,6 +1,7 @@import { Component, Suspense, type ErrorInfo, type ReactNode } from "react";import { useLocation, useNavigate } from "@/lib/router";import { Button } from "@/components/ui/button";+import { onChunkLoadReloadAbandoned, reloadForChunkLoadError } from "@/lib/chunk-load-recovery";import { captureBrowserException } from "@/lib/sentry";import { PaperclipLoading } from "./AnimatedPaperclipIcon";@@ -12,16 +13,41 @@ type RouteErrorBoundaryInnerProps = {type RouteErrorBoundaryState = {error: Error | null;+ reloading: boolean;};class RouteErrorBoundaryInner extends Component<RouteErrorBoundaryInnerProps, RouteErrorBoundaryState> {- override state: RouteErrorBoundaryState = { error: null };+ override state: RouteErrorBoundaryState = { error: null, reloading: false };+ private stopWaitingForReload: (() => void) | null = null;- static getDerivedStateFromError(error: unknown): RouteErrorBoundaryState {+ static getDerivedStateFromError(error: unknown): Partial<RouteErrorBoundaryState> {return { error: error instanceof Error ? error : new Error(String(error)) };}override componentDidCatch(error: unknown, info: ErrorInfo): void {+ this.stopWaiting();+ if (reloadForChunkLoadError(error)) {+ this.setState({ reloading: true });+ this.stopWaitingForReload = onChunkLoadReloadAbandoned(() => {+ this.stopWaitingForReload = null;+ this.setState({ reloading: false });+ this.report(error, info);+ });+ return;+ }+ this.report(error, info);+ }++ override componentWillUnmount(): void {+ this.stopWaiting();+ }++ private stopWaiting(): void {+ this.stopWaitingForReload?.();+ this.stopWaitingForReload = null;+ }++ private report(error: unknown, info: ErrorInfo): void {console.error("Page render failed", { error, componentStack: info.componentStack });captureBrowserException(error, { boundary: "route", componentStack: info.componentStack });}@@ -31,13 +57,15 @@ class RouteErrorBoundaryInner extends Component<RouteErrorBoundaryInnerProps, Ro// away (back button included) can't recover without a hard refresh. We sit// above the routed <Outlet />, so reset whenever the route changes.if (this.state.error && prevProps.resetKey !== this.props.resetKey) {- this.setState({ error: null });+ this.stopWaiting();+ this.setState({ error: null, reloading: false });}}override render() {- const { error } = this.state;+ const { error, reloading } = this.state;if (!error) return this.props.children;+ if (reloading) return <PaperclipLoading className="min-h-full" />;return (<div className="mx-auto max-w-2xl space-y-4 px-4 py-10">diff --git a/ui/src/lib/chunk-load-recovery.test.ts b/ui/src/lib/chunk-load-recovery.test.tsnew file mode 100644index 0000000000..63e5460d8c--- /dev/null+++ b/ui/src/lib/chunk-load-recovery.test.ts@@ -0,0 +1,155 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { createChunkLoadRecovery, isChunkLoadError, RELOAD_ABANDONED_MS } from "./chunk-load-recovery";++function memoryStorage(initial: Record<string, string> = {}) {+ const values = new Map(Object.entries(initial));+ return {+ getItem: (key: string) => values.get(key) ?? null,+ setItem: (key: string, value: string) => { values.set(key, value); },+ };+}++const cssPreloadError = new Error(+ "Unable to preload CSS for https://paperclip.example/assets/issue-detail-CIbQo9zW.css",+);++function preloadErrorEvent(payload: unknown) {+ return Object.assign(new Event("vite:preloadError", { cancelable: true }), { payload });+}++describe("isChunkLoadError", () => {+ it("matches Vite CSS preload and browser dynamic import failures", () => {+ expect(isChunkLoadError(cssPreloadError)).toBe(true);+ expect(isChunkLoadError(new TypeError("Failed to fetch dynamically imported module: https://paperclip.example/assets/a.js"))).toBe(true);+ expect(isChunkLoadError(new TypeError("error loading dynamically imported module: https://paperclip.example/assets/a.js"))).toBe(true);+ expect(isChunkLoadError(new TypeError("Importing a module script failed."))).toBe(true);+ });++ it("ignores ordinary render errors and non-errors", () => {+ expect(isChunkLoadError(new Error("Maximum update depth exceeded"))).toBe(false);+ expect(isChunkLoadError(new Error("Request failed: Unable to preload CSS for x"))).toBe(false);+ expect(isChunkLoadError("Unable to preload CSS for x")).toBe(false);+ expect(isChunkLoadError(undefined)).toBe(false);+ });+});++describe("reloadForChunkLoadError", () => {+ afterEach(() => {+ vi.useRealTimers();+ });++ it("reloads once and treats later failures in the same document as that reload", () => {+ const reload = vi.fn();+ const { reloadForChunkLoadError } = createChunkLoadRecovery({ storage: () => memoryStorage(), reload });++ expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);+ expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);+ expect(reload).toHaveBeenCalledTimes(1);+ });++ it("defers to the error UI when the fresh page fails again", () => {+ const storage = memoryStorage();+ const reload = vi.fn();+ let now = 1_000_000;+ createChunkLoadRecovery({ storage: () => storage, reload, now: () => now }).reloadForChunkLoadError(cssPreloadError);++ now += 10_000;+ const freshPage = createChunkLoadRecovery({ storage: () => storage, reload, now: () => now });+ expect(freshPage.reloadForChunkLoadError(cssPreloadError)).toBe(false);+ expect(reload).toHaveBeenCalledTimes(1);+ });++ it("notifies waiting callers and stops claiming the failure when the reload is cancelled", () => {+ vi.useFakeTimers();+ const storage = memoryStorage();+ const reload = vi.fn();+ const { reloadForChunkLoadError, onChunkLoadReloadAbandoned } = createChunkLoadRecovery({+ storage: () => storage,+ reload,+ });+ expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);+ const abandoned = vi.fn();+ const stopped = vi.fn();+ onChunkLoadReloadAbandoned(abandoned);+ onChunkLoadReloadAbandoned(stopped)();++ vi.advanceTimersByTime(RELOAD_ABANDONED_MS - 1);+ expect(abandoned).not.toHaveBeenCalled();+ expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);++ vi.advanceTimersByTime(1);+ expect(abandoned).toHaveBeenCalledTimes(1);+ expect(stopped).not.toHaveBeenCalled();+ expect(reloadForChunkLoadError(cssPreloadError)).toBe(false);+ expect(reload).toHaveBeenCalledTimes(1);++ const late = vi.fn();+ onChunkLoadReloadAbandoned(late);+ expect(late).toHaveBeenCalledTimes(1);+ });++ it("recovers again after the guard window, such as after a later deploy", () => {+ const storage = memoryStorage();+ const reload = vi.fn();+ let now = 1_000_000;+ createChunkLoadRecovery({ storage: () => storage, reload, now: () => now }).reloadForChunkLoadError(cssPreloadError);++ now += 5 * 60 * 1000;+ const laterPage = createChunkLoadRecovery({ storage: () => storage, reload, now: () => now });+ expect(laterPage.reloadForChunkLoadError(cssPreloadError)).toBe(true);+ expect(reload).toHaveBeenCalledTimes(2);+ });++ it("ignores an unreadable stored marker", () => {+ const reload = vi.fn();+ const storage = memoryStorage({ "paperclip:chunk-load-reload-at": "not-a-time" });+ const { reloadForChunkLoadError } = createChunkLoadRecovery({ storage: () => storage, reload, now: () => 1_000 });+ expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);+ });++ it("never reloads for other errors", () => {+ const reload = vi.fn();+ const { reloadForChunkLoadError } = createChunkLoadRecovery({ storage: () => memoryStorage(), reload });+ expect(reloadForChunkLoadError(new Error("boom"))).toBe(false);+ expect(reload).not.toHaveBeenCalled();+ });++ it("never reloads without a working loop guard", () => {+ const reload = vi.fn();+ expect(createChunkLoadRecovery({ storage: () => null, reload }).reloadForChunkLoadError(cssPreloadError)).toBe(false);+ const throwing = {+ getItem: () => { throw new Error("SecurityError"); },+ setItem: () => { throw new Error("SecurityError"); },+ };+ expect(createChunkLoadRecovery({ storage: () => throwing, reload }).reloadForChunkLoadError(cssPreloadError)).toBe(false);+ expect(reload).not.toHaveBeenCalled();+ });+});++describe("startChunkLoadRecovery", () => {+ it("reloads for a Vite preload failure without cancelling the rejection", () => {+ const target = new EventTarget();+ const reload = vi.fn();+ const { startChunkLoadRecovery } = createChunkLoadRecovery({ storage: () => memoryStorage(), reload });+ const stop = startChunkLoadRecovery(target as unknown as Window);++ const event = preloadErrorEvent(cssPreloadError);+ target.dispatchEvent(event);+ expect(reload).toHaveBeenCalledTimes(1);+ expect(event.defaultPrevented).toBe(false);++ stop();+ target.dispatchEvent(preloadErrorEvent(cssPreloadError));+ expect(reload).toHaveBeenCalledTimes(1);+ });++ it("ignores preload events without a chunk load error", () => {+ const target = new EventTarget();+ const reload = vi.fn();+ const { startChunkLoadRecovery } = createChunkLoadRecovery({ storage: () => memoryStorage(), reload });+ startChunkLoadRecovery(target as unknown as Window);+ target.dispatchEvent(preloadErrorEvent(undefined));+ target.dispatchEvent(preloadErrorEvent(new Error("boom")));+ expect(reload).not.toHaveBeenCalled();+ });+});diff --git a/ui/src/lib/chunk-load-recovery.ts b/ui/src/lib/chunk-load-recovery.tsnew file mode 100644index 0000000000..a7f380817c--- /dev/null+++ b/ui/src/lib/chunk-load-recovery.ts@@ -0,0 +1,94 @@+const RELOAD_AT_KEY = "paperclip:chunk-load-reload-at";+const RELOAD_GUARD_MS = 5 * 60 * 1000;+export const RELOAD_ABANDONED_MS = 10_000;++const CHUNK_LOAD_ERROR_PATTERNS = [+ /^Unable to preload CSS for /,+ /^Failed to fetch dynamically imported module/,+ /^error loading dynamically imported module/,+ /^Importing a module script failed/,+];++export function isChunkLoadError(error: unknown): boolean {+ if (!(error instanceof Error)) return false;+ return CHUNK_LOAD_ERROR_PATTERNS.some((pattern) => pattern.test(error.message));+}++type ReloadStorage = Pick<Storage, "getItem" | "setItem">;++type ChunkLoadRecoveryOptions = {+ storage?: () => ReloadStorage | null;+ reload?: () => void;+ now?: () => number;+};++function browserSessionStorage(): ReloadStorage | null {+ try {+ return window.sessionStorage;+ } catch {+ return null;+ }+}++export function createChunkLoadRecovery(options: ChunkLoadRecoveryOptions = {}) {+ const readStorage = options.storage ?? browserSessionStorage;+ const reload = options.reload ?? (() => window.location.reload());+ const now = options.now ?? Date.now;+ let reloading = false;+ const abandonedListeners = new Set<() => void>();++ function abandonReload() {+ reloading = false;+ const listeners = [...abandonedListeners];+ abandonedListeners.clear();+ for (const listener of listeners) listener();+ }++ function reloadForChunkLoadError(error: unknown): boolean {+ if (!isChunkLoadError(error)) return false;+ if (reloading) return true;+ const storage = readStorage();+ if (!storage) return false;+ const at = now();+ try {+ const lastReloadAt = Number(storage.getItem(RELOAD_AT_KEY));+ if (Number.isFinite(lastReloadAt) && lastReloadAt > 0 && at - lastReloadAt < RELOAD_GUARD_MS) {+ return false;+ }+ storage.setItem(RELOAD_AT_KEY, String(at));+ } catch {+ return false;+ }+ reloading = true;+ reload();+ globalThis.setTimeout(abandonReload, RELOAD_ABANDONED_MS);+ return true;+ }++ function onChunkLoadReloadAbandoned(listener: () => void): () => void {+ if (!reloading) {+ listener();+ return () => {};+ }+ abandonedListeners.add(listener);+ return () => {+ abandonedListeners.delete(listener);+ };+ }++ function startChunkLoadRecovery(target: Pick<Window, "addEventListener" | "removeEventListener"> = window) {+ const onPreloadError = (event: Event) => {+ reloadForChunkLoadError((event as Event & { payload?: unknown }).payload);+ };+ target.addEventListener("vite:preloadError", onPreloadError);+ return () => target.removeEventListener("vite:preloadError", onPreloadError);+ }++ return { reloadForChunkLoadError, onChunkLoadReloadAbandoned, startChunkLoadRecovery };+}++const browserRecovery = createChunkLoadRecovery();++export const reloadForChunkLoadError = browserRecovery.reloadForChunkLoadError;+export const onChunkLoadReloadAbandoned = browserRecovery.onChunkLoadReloadAbandoned;+export const startChunkLoadRecovery = browserRecovery.startChunkLoadRecovery;diff --git a/ui/src/main.tsx b/ui/src/main.tsxindex 239bc82829..8bc5dba71c 100644--- a/ui/src/main.tsx+++ b/ui/src/main.tsx@@ -22,6 +22,7 @@ import { DesignSandboxProvider } from "./context/DesignSandboxContext";import { TooltipProvider } from "@/components/ui/tooltip";import { initPluginBridge } from "./plugins/bridge-init";import { PluginLauncherProvider } from "./plugins/launchers";+import { startChunkLoadRecovery } from "./lib/chunk-load-recovery";import { startPerfMeasureReaper } from "./lib/perf-measure-reaper";import { getOrCreatePaperclipReactRoot } from "./lib/react-root";import { startServiceWorkerUpdates } from "./lib/service-worker-updates";@@ -35,6 +36,8 @@ initPluginBridge(React, ReactDOM);// accumulate into millions of native objects (GBs). Reap them periodically.startPerfMeasureReaper();+startChunkLoadRecovery();+// Parked SPA tabs never navigate, so beyond registering the worker this also// re-checks /sw.js on tab focus and hourly, and applies a discovered update// with one reload while the tab is hidden — otherwise an old worker and its