PaperClipAI/ui/src/lib/chunk-load-recovery.test.ts

import { afterEach, describe, expect, it, vi } from "vitest";
import { createChunkLoadRecovery, isChunkLoadError, RELOAD_ABANDONED_MS, RELOAD_DELAYS_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("retries a fresh page that fails again, waiting longer each time for the deploy to settle", () => {
    vi.useFakeTimers();
    const storage = memoryStorage();
    const reload = vi.fn();
    let now = 1_000_000;
    createChunkLoadRecovery({ storage: () => storage, reload, now: () => now }).reloadForChunkLoadError(cssPreloadError);
    expect(reload).toHaveBeenCalledTimes(1);

    for (const delayMs of RELOAD_DELAYS_MS.slice(1)) {
      now += 10_000;
      const freshPage = createChunkLoadRecovery({ storage: () => storage, reload, now: () => now });
      const reloadsBefore = reload.mock.calls.length;
      expect(freshPage.reloadForChunkLoadError(cssPreloadError)).toBe(true);
      vi.advanceTimersByTime(delayMs - 1);
      expect(reload).toHaveBeenCalledTimes(reloadsBefore);
      vi.advanceTimersByTime(1);
      expect(reload).toHaveBeenCalledTimes(reloadsBefore + 1);
    }
  });

  it("defers to the error UI once the retries in the guard window are used up", () => {
    const storage = memoryStorage();
    const reload = vi.fn();
    let now = 1_000_000;
    for (let attempt = 0; attempt < RELOAD_DELAYS_MS.length; attempt += 1) {
      expect(createChunkLoadRecovery({ storage: () => storage, reload, now: () => now }).reloadForChunkLoadError(cssPreloadError)).toBe(true);
      now += 10_000;
    }

    const exhaustedPage = createChunkLoadRecovery({ storage: () => storage, reload, now: () => now });
    expect(exhaustedPage.reloadForChunkLoadError(cssPreloadError)).toBe(false);
  });

  it("counts a reload recorded by an older build as the first retry", () => {
    vi.useFakeTimers();
    const reload = vi.fn();
    const storage = memoryStorage({ "paperclip:chunk-load-reload-at": "1000000" });
    const { reloadForChunkLoadError } = createChunkLoadRecovery({ storage: () => storage, reload, now: () => 1_010_000 });

    expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);
    expect(reload).not.toHaveBeenCalled();
    vi.advanceTimersByTime(RELOAD_DELAYS_MS[1]!);
    expect(reload).toHaveBeenCalledTimes(1);
  });

  it("keeps the stored reload time readable by builds without retries", () => {
    const storage = memoryStorage();
    const reload = vi.fn();
    let now = 1_000_000;
    createChunkLoadRecovery({ storage: () => storage, reload, now: () => now }).reloadForChunkLoadError(cssPreloadError);
    now += 10_000;
    createChunkLoadRecovery({ storage: () => storage, reload, now: () => now }).reloadForChunkLoadError(cssPreloadError);

    // An older build reads this key with Number() and keeps its one-reload guard.
    expect(Number(storage.getItem("paperclip:chunk-load-reload-at"))).toBe(1_000_000);
  });

  it("ignores a retry count left from another guard window", () => {
    vi.useFakeTimers();
    const reload = vi.fn();
    const storage = memoryStorage({
      "paperclip:chunk-load-reload-at": "2000000",
      "paperclip:chunk-load-reload-attempts": `1000000:${RELOAD_DELAYS_MS.length}`,
    });
    const { reloadForChunkLoadError } = createChunkLoadRecovery({ storage: () => storage, reload, now: () => 2_010_000 });

    expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);
    vi.advanceTimersByTime(RELOAD_DELAYS_MS[1]!);
    expect(reload).toHaveBeenCalledTimes(1);
  });

  it("cancels a delayed retry that has not started", () => {
    vi.useFakeTimers();
    const reload = vi.fn();
    const storage = memoryStorage({ "paperclip:chunk-load-reload-at": "1000000" });
    const recovery = createChunkLoadRecovery({ storage: () => storage, reload, now: () => 1_010_000 });
    expect(recovery.reloadForChunkLoadError(cssPreloadError)).toBe(true);
    const abandoned = vi.fn();
    recovery.onChunkLoadReloadAbandoned(abandoned);

    expect(recovery.cancelPendingChunkLoadReload()).toBe(true);
    vi.advanceTimersByTime(RELOAD_DELAYS_MS[1]! + RELOAD_ABANDONED_MS);
    expect(reload).not.toHaveBeenCalled();
    expect(abandoned).not.toHaveBeenCalled();
    expect(recovery.cancelPendingChunkLoadReload()).toBe(false);
  });

  it("cannot cancel a reload that already started", () => {
    const reload = vi.fn();
    const recovery = createChunkLoadRecovery({ storage: () => memoryStorage(), reload });
    expect(recovery.reloadForChunkLoadError(cssPreloadError)).toBe(true);
    expect(recovery.cancelPendingChunkLoadReload()).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", () => {
    for (const marker of ["not-a-time", "{\"windowStartedAt\":\"soon\"}", "null"]) {
      const reload = vi.fn();
      const storage = memoryStorage({ "paperclip:chunk-load-reload-at": marker });
      const { reloadForChunkLoadError } = createChunkLoadRecovery({ storage: () => storage, reload, now: () => 1_000 });
      expect(reloadForChunkLoadError(cssPreloadError)).toBe(true);
      expect(reload).toHaveBeenCalledTimes(1);
    }
  });

  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();
  });
});