@tangle-network/ui 11.25.0 → 11.27.0

package/src/files/pdf-loader.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const PDFJS = "pdfjs-dist/legacy/build/pdf.mjs";
+const WORKER = "pdfjs-dist/legacy/build/pdf.worker.min.mjs";
+
+/** What the next import of pdf.js yields: a namespace, or a thrown error. */
+let pdfjsImport: () => Record<string, unknown>;
+let workerImports = 0;
+
+function installedPdfjs() {
+  return { getDocument: () => ({}), GlobalWorkerOptions: { workerSrc: "", workerPort: null } };
+}
+
+/**
+ * Loads the module under test with pdf.js replaced. The loader reads it through
+ * a dynamic import, so the substitution happens before the graph is built.
+ */
+async function loadModule() {
+  vi.resetModules();
+  vi.doMock(PDFJS, () => pdfjsImport());
+  vi.doMock(WORKER, () => {
+    workerImports += 1;
+    return {};
+  });
+  return await import("./pdf-loader");
+}
+
+let consoleWarn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  pdfjsImport = installedPdfjs;
+  workerImports = 0;
+  consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  consoleWarn.mockRestore();
+  vi.doUnmock(PDFJS);
+  vi.doUnmock(WORKER);
+  vi.resetModules();
+});
+
+describe("loadPdfjs", () => {
+  it("runs the worker on the main thread when no worker URL is configured", async () => {
+    const { loadPdfjs } = await loadModule();
+    const pdfjs = await loadPdfjs();
+    expect(typeof pdfjs.getDocument).toBe("function");
+    expect(workerImports).toBe(1);
+    expect(pdfjs.GlobalWorkerOptions.workerSrc).toBe("");
+  });
+
+  it("uses the configured worker URL instead of importing the worker", async () => {
+    const { configurePdfViewer, loadPdfjs } = await loadModule();
+    configurePdfViewer({ workerSrc: "/assets/pdf.worker.min.mjs", assetsUrl: "/pdfjs/" });
+    const pdfjs = await loadPdfjs();
+    expect(pdfjs.GlobalWorkerOptions.workerSrc).toBe("/assets/pdf.worker.min.mjs");
+    expect(workerImports).toBe(0);
+    expect(consoleWarn).not.toHaveBeenCalled();
+  });
+
+  it("warns once that scanned pages need assetsUrl", async () => {
+    const { loadPdfjs } = await loadModule();
+    await loadPdfjs();
+    await loadPdfjs();
+    expect(consoleWarn).toHaveBeenCalledTimes(1);
+    expect(consoleWarn.mock.calls[0][0]).toMatch(/no assetsUrl.*JBIG2, CCITT fax/);
+  });
+
+  it("treats a stub without the pdf.js API as missing, for the rest of the session", async () => {
+    // What a bundler told to ignore the uninstalled peer hands back.
+    pdfjsImport = () => ({ default: {}, getDocument: undefined });
+    const { loadPdfjs, isMissingPdfjsError } = await loadModule();
+    const first = await loadPdfjs().catch((error: unknown) => error);
+    expect(isMissingPdfjsError(first)).toBe(true);
+    expect((first as Error).message).toMatch(/Install pdfjs-dist/);
+
+    pdfjsImport = installedPdfjs;
+    expect(await loadPdfjs().catch((error: unknown) => error)).toBe(first);
+  });
+
+  it("tries again after a failure that is not a missing package", async () => {
+    let attempts = 0;
+    pdfjsImport = () => {
+      attempts += 1;
+      if (attempts === 1) throw new Error("Failed to fetch dynamically imported module");
+      return installedPdfjs();
+    };
+    const { loadPdfjs, isMissingPdfjsError } = await loadModule();
+    const failure = await loadPdfjs().catch((error: unknown) => error);
+    expect(isMissingPdfjsError(failure)).toBe(false);
+    await expect(loadPdfjs()).resolves.toHaveProperty("getDocument");
+  });
+});
+
+describe("asMissingPdfjsError", () => {
+  it("names pdfjs-dist only for a resolution failure about it", async () => {
+    const { asMissingPdfjsError, isMissingPdfjsError } = await loadModule();
+    for (const message of [
+      `Failed to resolve import "${PDFJS}". Does the file exist?`,
+      `Could not resolve "pdfjs-dist/legacy/build/pdf.mjs"`,
+      "Cannot find module 'pdfjs-dist/legacy/build/pdf.mjs'",
+    ]) {
+      expect(isMissingPdfjsError(asMissingPdfjsError(new Error(message))), message).toBe(true);
+    }
+    const chunk = new Error("Failed to fetch dynamically imported module");
+    expect(asMissingPdfjsError(chunk)).toBe(chunk);
+    const other = new Error('Could not resolve "./chunk-abc.js"');
+    expect(asMissingPdfjsError(other)).toBe(other);
+  });
+});
+
+describe("pdfAssetParams", () => {
+  it("asks for nothing until assetsUrl is configured", async () => {
+    const { pdfAssetParams } = await loadModule();
+    expect(pdfAssetParams()).toEqual({});
+  });
+
+  it("points every asset directory under an absolute assetsUrl", async () => {
+    const { configurePdfViewer, pdfAssetParams } = await loadModule();
+    configurePdfViewer({ assetsUrl: "/static/pdfjs" });
+    const base = new URL("/static/pdfjs/", document.baseURI).href;
+    expect(pdfAssetParams()).toEqual({
+      wasmUrl: `${base}wasm/`,
+      cMapUrl: `${base}cmaps/`,
+      cMapPacked: true,
+      standardFontDataUrl: `${base}standard_fonts/`,
+      iccUrl: `${base}iccs/`,
+    });
+  });
+});

package/src/files/pdf-loader.ts

@@ -0,0 +1,169 @@
+/**
+ * Loads pdf.js for `PdfViewer`, which renders PDF pages to canvas in every
+ * browser, including Android Chrome and iOS Safari, where `<object>` shows a
+ * blank frame or only the first page.
+ *
+ * `pdfjs-dist` is an optional peer, reached only through the dynamic imports
+ * below, for the reasons `editor/editor-peers.ts` gives: a static import fails
+ * the build of every consumer that does not install it, and esbuild defers an
+ * unresolved `import()` to run time only when the call carries a `.catch()`.
+ * `scripts/validate-dist.mjs` enforces both.
+ *
+ * The legacy build is deliberate. The modern build calls APIs such as
+ * `Map.prototype.getOrInsertComputed` without a fallback, so it throws on
+ * phone browsers a year or two old; the legacy build carries polyfills for
+ * them at about 60 KB more minified code. The worker comes from the same
+ * build, because pdf.js refuses a worker whose version differs from its own.
+ *
+ * Worker. pdf.js parses documents in a worker named by `workerSrc`. No
+ * bundler-neutral expression yields that URL from inside a library, and the
+ * pdf.js default fetches from a CDN, so by default this module imports the
+ * worker module itself. pdf.js then runs its worker code on the main thread,
+ * which works in Vite, esbuild, webpack and Cloudflare Workers builds with no
+ * configuration and no third-party fetch. Parsing a large document then
+ * competes with scrolling, so production apps should serve the worker file and
+ * pass its URL to `configurePdfViewer` before the first viewer renders. With
+ * Vite:
+ *
+ *   import workerSrc from "pdfjs-dist/legacy/build/pdf.worker.min.mjs?url";
+ *   configurePdfViewer({ workerSrc });
+ *
+ * The setting is page-wide because pdf.js's own worker setting is: once the
+ * main-thread worker is loaded, every document on the page uses it.
+ *
+ * Assets. pdf.js 6 decodes JBIG2, CCITT fax and JPEG 2000 images with
+ * WebAssembly modules it fetches at run time; black-and-white scans use the
+ * first two. Without `assetsUrl` those images do not render, and pdf.js warns
+ * only in the console, so this module warns once when it loads without one.
+ */
+
+import type * as Pdfjs from "pdfjs-dist";
+import { isMissingPeerError, rethrow } from "../lib/optional-peer";
+
+export type PdfjsLib = typeof Pdfjs;
+
+export interface PdfViewerConfig {
+  /**
+   * URL of `pdfjs-dist/legacy/build/pdf.worker.min.mjs` from the installed
+   * pdfjs-dist, served by the app. Moves PDF parsing off the main thread.
+   */
+  workerSrc?: string;
+  /**
+   * Base URL, ending in `/`, under which the app serves the `wasm/`, `cmaps/`,
+   * `standard_fonts/` and `iccs/` directories of the installed pdfjs-dist.
+   * Needed for scanned pages, CJK text and non-embedded fonts.
+   */
+  assetsUrl?: string;
+}
+
+let config: PdfViewerConfig = {};
+
+/**
+ * Sets the page-wide pdf.js worker and asset locations. Call it once, before
+ * the first `PdfViewer` renders; a worker set afterwards applies only when no
+ * document has loaded the main-thread worker yet.
+ */
+export function configurePdfViewer(next: PdfViewerConfig): void {
+  config = { ...next };
+}
+
+/**
+ * The optional peer behind `PdfViewer`. `scripts/validate-dist.mjs` reads this
+ * list and requires every import of it to be dynamic and caught.
+ */
+const DEFERRED_PEERS = ["pdfjs-dist"];
+
+/** pdfjs-dist is absent, or resolved to a stub with none of its API. */
+export class MissingPdfjsError extends Error {
+  constructor(options?: { cause?: unknown }) {
+    super(
+      "PdfViewer needs the optional peer pdfjs-dist. Install pdfjs-dist to render PDF pages.",
+      options,
+    );
+    this.name = "MissingPdfjsError";
+  }
+}
+
+export function isMissingPdfjsError(error: unknown): boolean {
+  return error instanceof Error && error.name === "MissingPdfjsError";
+}
+
+/**
+ * Turns a resolution failure that names pdfjs-dist into `MissingPdfjsError`.
+ * Any other rejection, such as a chunk that did not download, passes through.
+ */
+export function asMissingPdfjsError(error: unknown): unknown {
+  if (!isMissingPeerError(error)) return error;
+  const message = (error as Error).message;
+  return DEFERRED_PEERS.some((name) => message.includes(name))
+    ? new MissingPdfjsError({ cause: error })
+    : error;
+}
+
+async function importPdfjs(): Promise<PdfjsLib> {
+  let pdfjs: PdfjsLib;
+  try {
+    pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs").catch(rethrow);
+  } catch (error) {
+    throw asMissingPdfjsError(error);
+  }
+  // A bundler told to ignore the missing peer can hand back an empty module.
+  if (typeof pdfjs.getDocument !== "function") throw new MissingPdfjsError();
+  return pdfjs;
+}
+
+let pending: Promise<PdfjsLib> | null = null;
+let warnedAboutAssets = false;
+
+/**
+ * Resolves pdf.js with its worker configured. A missing peer stays missing for
+ * the session, so its rejection is kept; any other failure, such as a chunk
+ * that did not download, is dropped so the next viewer tries again.
+ */
+export function loadPdfjs(): Promise<PdfjsLib> {
+  pending ??= importPdfjs().catch((error: unknown) => {
+    if (!isMissingPdfjsError(error)) pending = null;
+    throw error;
+  });
+  return pending.then(async (pdfjs) => {
+    const { GlobalWorkerOptions } = pdfjs;
+    if (config.workerSrc) {
+      GlobalWorkerOptions.workerSrc = config.workerSrc;
+    } else if (!GlobalWorkerOptions.workerSrc && !GlobalWorkerOptions.workerPort) {
+      // Defines `globalThis.pdfjsWorker`, which pdf.js runs on this thread.
+      await import("pdfjs-dist/legacy/build/pdf.worker.min.mjs").catch(rethrow);
+    }
+    if (!config.assetsUrl && !warnedAboutAssets) {
+      warnedAboutAssets = true;
+      console.warn(
+        "PdfViewer: no assetsUrl is configured, so JBIG2, CCITT fax and JPEG 2000 images " +
+          "(most black-and-white scans) will not render. See configurePdfViewer.",
+      );
+    }
+    return pdfjs;
+  });
+}
+
+/** The `getDocument` options that locate pdf.js's run-time assets. */
+export interface PdfAssetParams {
+  wasmUrl?: string;
+  cMapUrl?: string;
+  cMapPacked?: boolean;
+  standardFontDataUrl?: string;
+  iccUrl?: string;
+}
+
+/** `getDocument` asset options for the configured `assetsUrl`, or none. */
+export function pdfAssetParams(): PdfAssetParams {
+  if (!config.assetsUrl) return {};
+  // pdf.js joins file names onto these with plain concatenation, and a
+  // worker resolves a relative URL against its own script, so make it absolute.
+  const base = new URL(config.assetsUrl, document.baseURI).href.replace(/\/?$/, "/");
+  return {
+    wasmUrl: `${base}wasm/`,
+    cMapUrl: `${base}cmaps/`,
+    cMapPacked: true,
+    standardFontDataUrl: `${base}standard_fonts/`,
+    iccUrl: `${base}iccs/`,
+  };
+}

package/src/files/pdf-viewer.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { configurePdfViewer, type PdfViewerConfig } from "./pdf-loader";
+import { PdfViewer } from "./pdf-viewer";
+
+// Served by .storybook/main.ts from .storybook/fixtures.
+// US Courts form AO 440, Summons in a Civil Action: two pages, a work of the
+// United States government (https://www.uscourts.gov/sites/default/files/ao440.pdf).
+const SUMMONS = "/fixtures/summons-ao440.pdf";
+// A fictional three-page letter stored as CCITT Group 4 images at 200 dpi, the
+// way an office scanner writes black-and-white pages.
+const SCANNED_LETTER = "/fixtures/scanned-letter.pdf";
+
+/** The worker and decoder assets, served the way an app serves them. */
+const SERVED_ASSETS: PdfViewerConfig = {
+  workerSrc: "/pdfjs/legacy/build/pdf.worker.min.mjs",
+  assetsUrl: "/pdfjs/",
+};
+
+// Storybook deep-merges parameters, so an empty story-level object would keep
+// the served assets; a named mode cannot be merged into.
+type PdfAssets = "served" | "none";
+
+const meta: Meta<typeof PdfViewer> = {
+  title: "Files/PdfViewer",
+  component: PdfViewer,
+  parameters: { layout: "fullscreen", pdfAssets: "served" satisfies PdfAssets },
+  decorators: [
+    (Story, context) => {
+      // pdf.js fixes its worker with the first document on the page, so a
+      // story's configuration holds when the story is opened on its own.
+      configurePdfViewer(context.parameters.pdfAssets === "none" ? {} : SERVED_ASSETS);
+      return (
+        <div className="h-[100dvh] w-full bg-background p-3 text-foreground sm:h-[680px] sm:max-w-[820px]">
+          <Story />
+        </div>
+      );
+    },
+  ],
+  args: {
+    src: SUMMONS,
+    filename: "Summons in a Civil Action.pdf",
+    size: 25_380,
+    onDownload: () => {},
+    className: "h-full",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PdfViewer>;
+
+export const CourtForm: Story = {
+  name: "Court form",
+};
+
+export const CourtFormLight: Story = {
+  name: "Court form (light)",
+  globals: { theme: "light" },
+};
+
+export const ScannedLetter: Story = {
+  name: "Scanned letter (CCITT pages)",
+  args: {
+    src: SCANNED_LETTER,
+    filename: "Notice of lease termination.pdf",
+    size: 75_955,
+  },
+};
+
+export const ZeroConfiguration: Story = {
+  name: "Zero configuration (main-thread worker)",
+  parameters: { pdfAssets: "none" satisfies PdfAssets },
+};
+
+export const NotAPdf: Story = {
+  name: "Not a PDF (falls back)",
+  args: {
+    src: "data:application/pdf;base64,VGhpcyBpcyBub3QgYSBQREYu",
+    filename: "Exhibit C.pdf",
+    size: 15,
+  },
+};

package/src/files/pdf-viewer.test.tsx

@@ -0,0 +1,245 @@
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MissingPdfjsError, loadPdfjs, type PdfjsLib } from "./pdf-loader";
+import { PdfViewer } from "./pdf-viewer";
+
+vi.mock("./pdf-loader", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./pdf-loader")>()),
+  loadPdfjs: vi.fn(),
+}));
+
+const BLOB_URL = "blob:https://app.tangle.tools/9a8b7c";
+/** US Letter in points. */
+const LETTER = { width: 612, height: 792 };
+const CSS_PER_POINT = 96 / 72;
+
+/** A pdf.js stand-in: pages of US Letter that render at once. */
+function fakePdfjs({ numPages = 3, fail }: { numPages?: number; fail?: Error } = {}) {
+  const render = vi.fn(() => ({ promise: Promise.resolve(), cancel: vi.fn() }));
+  const page = {
+    getViewport: ({ scale }: { scale: number }) => ({
+      width: LETTER.width * scale,
+      height: LETTER.height * scale,
+    }),
+    render,
+    cleanup: vi.fn(),
+  };
+  const doc = { numPages, getPage: vi.fn(async () => page) };
+  const destroy = vi.fn(async () => {});
+  const getDocument = vi.fn(() => ({
+    promise: fail ? Promise.reject(fail) : Promise.resolve(doc),
+    destroy,
+    onProgress: undefined,
+  }));
+  const pdfjs = { getDocument } as unknown as PdfjsLib;
+  return { pdfjs, getDocument, destroy, render };
+}
+
+function namedError(name: string, extra: Record<string, unknown> = {}): Error {
+  return Object.assign(new Error(name), { name }, extra);
+}
+
+const pageInput = () => screen.getByRole("textbox", { name: /^Page/ });
+
+let consoleError: ReturnType<typeof vi.spyOn>;
+let consoleWarn: ReturnType<typeof vi.spyOn>;
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+  consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  // Node cannot read a browser's object URLs; serve the test's as a PDF header.
+  vi.stubGlobal("fetch", (input: RequestInfo | URL, init?: RequestInit) =>
+    String(input).startsWith("blob:")
+      ? Promise.resolve(new Response("%PDF-"))
+      : realFetch(input, init),
+  );
+});
+
+afterEach(() => {
+  consoleError.mockRestore();
+  consoleWarn.mockRestore();
+  vi.unstubAllGlobals();
+  vi.mocked(loadPdfjs).mockReset();
+});
+
+describe("PdfViewer", () => {
+  it("renders every page of the document to a canvas", async () => {
+    const fake = fakePdfjs({ numPages: 3 });
+    vi.mocked(loadPdfjs).mockResolvedValue(fake.pdfjs);
+
+    const { container } = render(<PdfViewer src={BLOB_URL} filename="lease.pdf" />);
+
+    expect(screen.getByRole("status")).toHaveTextContent("Loading lease.pdf");
+    expect(await screen.findByRole("img", { name: "Page 3 of 3" })).toBeInTheDocument();
+    expect(screen.getByRole("region", { name: "lease.pdf" })).toBeInTheDocument();
+    expect(pageInput()).toHaveValue("1");
+    expect(screen.getByText("/ 3")).toBeInTheDocument();
+    await waitFor(() => expect(container.querySelectorAll("canvas")).toHaveLength(3));
+    expect(fake.render).toHaveBeenCalledWith(
+      expect.objectContaining({ canvas: expect.any(HTMLCanvasElement) }),
+    );
+  });
+
+  it("streams an http(s) URL and reads other URLs as bytes", async () => {
+    const fake = fakePdfjs();
+    vi.mocked(loadPdfjs).mockResolvedValue(fake.pdfjs);
+
+    const remote = render(<PdfViewer src="https://files.example/brief.pdf" />);
+    await screen.findByRole("img", { name: "Page 1 of 3" });
+    expect(fake.getDocument).toHaveBeenLastCalledWith({ url: "https://files.example/brief.pdf" });
+    remote.unmount();
+
+    render(<PdfViewer src="data:application/pdf;base64,JVBERi0=" />);
+    await screen.findByRole("img", { name: "Page 1 of 3" });
+    const [params] = fake.getDocument.mock.lastCall as unknown as [{ data: Uint8Array }];
+    expect(new TextDecoder().decode(params.data)).toBe("%PDF-");
+  });
+
+  it("moves between pages with the buttons and the page field", async () => {
+    vi.mocked(loadPdfjs).mockResolvedValue(fakePdfjs({ numPages: 3 }).pdfjs);
+    render(<PdfViewer src={BLOB_URL} filename="lease.pdf" />);
+    await screen.findByRole("img", { name: "Page 3 of 3" });
+
+    const previous = screen.getByRole("button", { name: "Previous page" });
+    const next = screen.getByRole("button", { name: "Next page" });
+    expect(previous).toBeDisabled();
+
+    fireEvent.click(next);
+    expect(pageInput()).toHaveValue("2");
+    expect(previous).toBeEnabled();
+
+    fireEvent.change(pageInput(), { target: { value: "9" } });
+    fireEvent.keyDown(pageInput(), { key: "Enter" });
+    expect(pageInput()).toHaveValue("3");
+    expect(next).toBeDisabled();
+
+    fireEvent.change(pageInput(), { target: { value: "1x" } });
+    expect(pageInput()).toHaveValue("1");
+    fireEvent.keyDown(pageInput(), { key: "Escape" });
+    expect(pageInput()).toHaveValue("3");
+  });
+
+  it("zooms in steps and returns to fit-to-width", async () => {
+    vi.mocked(loadPdfjs).mockResolvedValue(fakePdfjs({ numPages: 1 }).pdfjs);
+    render(<PdfViewer src={BLOB_URL} filename="lease.pdf" />);
+    const page = await screen.findByRole("img", { name: "Page 1 of 1" });
+
+    // jsdom lays nothing out, so the fitted width falls back to 100%.
+    const fit = screen.getByRole("button", { name: "100%, fit to width" });
+    expect(fit).toHaveAttribute("aria-pressed", "true");
+
+    fireEvent.click(screen.getByRole("button", { name: "Zoom in" }));
+    const zoomed = screen.getByRole("button", { name: "125%, fit to width" });
+    expect(zoomed).toHaveAttribute("aria-pressed", "false");
+    await waitFor(() =>
+      expect(page.style.width).toBe(`${Math.round(LETTER.width * CSS_PER_POINT * 1.25)}px`),
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Zoom out" }));
+    fireEvent.click(screen.getByRole("button", { name: "Zoom out" }));
+    expect(screen.getByRole("button", { name: "75%, fit to width" })).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "75%, fit to width" }));
+    expect(screen.getByRole("button", { name: "100%, fit to width" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  });
+
+  it("fits the first page to the width of the pane", async () => {
+    const width = vi
+      .spyOn(HTMLElement.prototype, "clientWidth", "get")
+      .mockReturnValue(600);
+    try {
+      vi.mocked(loadPdfjs).mockResolvedValue(fakePdfjs({ numPages: 1 }).pdfjs);
+      render(<PdfViewer src={BLOB_URL} />);
+      const page = await screen.findByRole("img", { name: "Page 1 of 1" });
+      // 600px less the column's 12px padding on each side.
+      await waitFor(() => expect(page.style.width).toBe("576px"));
+      const percent = Math.round((576 / (LETTER.width * CSS_PER_POINT)) * 100);
+      expect(screen.getByRole("button", { name: `${percent}%, fit to width` })).toHaveAttribute(
+        "aria-pressed",
+        "true",
+      );
+    } finally {
+      width.mockRestore();
+    }
+  });
+
+  it("offers Download in the toolbar only when the host handles it", async () => {
+    vi.mocked(loadPdfjs).mockResolvedValue(fakePdfjs().pdfjs);
+    const onDownload = vi.fn();
+    const { rerender } = render(<PdfViewer src={BLOB_URL} filename="lease.pdf" />);
+    await screen.findByRole("img", { name: "Page 1 of 3" });
+    expect(screen.queryByRole("button", { name: "Download lease.pdf" })).toBeNull();
+
+    rerender(<PdfViewer src={BLOB_URL} filename="lease.pdf" onDownload={onDownload} />);
+    fireEvent.click(screen.getByRole("button", { name: "Download lease.pdf" }));
+    expect(onDownload).toHaveBeenCalledTimes(1);
+  });
+
+  it("says so and falls back to the browser's viewer when pdfjs-dist is missing", async () => {
+    vi.mocked(loadPdfjs).mockRejectedValue(new MissingPdfjsError());
+    const onDownload = vi.fn();
+    const { container } = render(
+      <PdfViewer src={BLOB_URL} filename="lease.pdf" size={2048} onDownload={onDownload} />,
+    );
+
+    expect(
+      await screen.findByText(/does not include the page viewer/),
+    ).toBeInTheDocument();
+    const object = container.querySelector("object");
+    expect(object).toHaveAttribute("data", BLOB_URL);
+    expect(object).toHaveAttribute("type", "application/pdf");
+    expect(screen.getByText("This browser does not show PDFs inline.")).toBeInTheDocument();
+    expect(screen.getByText("2.0 KB")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Download" }));
+    expect(onDownload).toHaveBeenCalledTimes(1);
+    // A missing package will not appear on a retry.
+    expect(screen.queryByRole("button", { name: "Try again" })).toBeNull();
+    expect(consoleError).toHaveBeenCalledWith(
+      expect.stringContaining("falling back"),
+      expect.any(MissingPdfjsError),
+    );
+  });
+
+  it.each([
+    ["PasswordException", {}, /password-protected/, false],
+    ["InvalidPDFException", {}, /could not be read as a PDF/, false],
+    ["ResponseException", { status: 404 }, /could not be downloaded \(HTTP 404\)/, true],
+    ["UnknownErrorException", {}, /could not open this PDF/, true],
+  ])("explains a %s and offers a retry only when one can help", async (name, extra, notice, retry) => {
+    vi.mocked(loadPdfjs).mockResolvedValue(fakePdfjs({ fail: namedError(name, extra) }).pdfjs);
+    render(<PdfViewer src={BLOB_URL} />);
+    expect(await screen.findByText(notice)).toBeInTheDocument();
+    expect(Boolean(screen.queryByRole("button", { name: "Try again" }))).toBe(retry);
+  });
+
+  it("loads the document again on Try again", async () => {
+    const failing = fakePdfjs({ fail: namedError("UnknownErrorException") });
+    const working = fakePdfjs({ numPages: 2 });
+    vi.mocked(loadPdfjs)
+      .mockResolvedValueOnce(failing.pdfjs)
+      .mockResolvedValueOnce(working.pdfjs);
+    render(<PdfViewer src={BLOB_URL} />);
+
+    fireEvent.click(await screen.findByRole("button", { name: "Try again" }));
+    expect(await screen.findByRole("img", { name: "Page 2 of 2" })).toBeInTheDocument();
+  });
+
+  it("destroys the loading task when it unmounts or the source changes", async () => {
+    const fake = fakePdfjs();
+    vi.mocked(loadPdfjs).mockResolvedValue(fake.pdfjs);
+    const { rerender, unmount } = render(<PdfViewer src={BLOB_URL} />);
+    await screen.findByRole("img", { name: "Page 1 of 3" });
+
+    rerender(<PdfViewer src="blob:https://app.tangle.tools/other" />);
+    expect(fake.destroy).toHaveBeenCalledTimes(1);
+    await screen.findByRole("img", { name: "Page 1 of 3" });
+
+    unmount();
+    await act(async () => {});
+    expect(fake.destroy).toHaveBeenCalledTimes(2);
+  });
+});