@@ -0,0 +1,71 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { expect, it, vi } from "vitest";
+import { ViewerStatus, type ViewerStatusState } from "./ViewerStatus";
+
+function setup(state: ViewerStatusState) {
+  const onRetry = vi.fn();
+  const onSubmitPassword = vi.fn();
+  render(
+    <ViewerStatus
+      state={state}
+      onRetry={onRetry}
+      onSubmitPassword={onSubmitPassword}
+    />,
+  );
+  return { onRetry, onSubmitPassword };
+}
+
+it("announces loading politely", () => {
+  setup({ status: "loading" });
+  expect(screen.getByRole("status").textContent).toContain("Loading document");
+});
+
+it("shows the empty state", () => {
+  setup({ status: "empty" });
+  expect(screen.getByText("No document")).toBeTruthy();
+});
+
+it("explains an unsupported file without offering Retry", () => {
+  setup({ status: "unsupported" });
+  expect(screen.getByRole("alert").textContent).toContain("can't be previewed");
+  expect(screen.queryByRole("button")).toBeNull();
+});
+
+it("shows the failure message and retries on click", async () => {
+  const { onRetry } = setup({ status: "failed", message: "Network error" });
+  expect(screen.getByRole("alert").textContent).toContain("Network error");
+  await userEvent.click(screen.getByRole("button", { name: "Retry" }));
+  expect(onRetry).toHaveBeenCalledTimes(1);
+});
+
+it("submits a typed password, and not an empty one", async () => {
+  const { onSubmitPassword } = setup({ status: "password", incorrect: false });
+  await userEvent.click(screen.getByRole("button", { name: "Open" }));
+  expect(onSubmitPassword).not.toHaveBeenCalled();
+
+  await userEvent.type(screen.getByLabelText("Password"), "secret{Enter}");
+  expect(onSubmitPassword).toHaveBeenCalledWith("secret");
+});
+
+it("marks a wrong password on the field", () => {
+  setup({ status: "password", incorrect: true });
+  const field = screen.getByLabelText("Password");
+  expect(field.getAttribute("aria-invalid")).toBe("true");
+  const description = field.getAttribute("aria-describedby") ?? "";
+  expect(document.getElementById(description)?.textContent).toBe(
+    "That password is incorrect.",
+  );
+});
+
+it("puts the focus back in the field after a wrong password, not before", () => {
+  const show = (state: ViewerStatusState) => (
+    <ViewerStatus state={state} onRetry={vi.fn()} onSubmitPassword={vi.fn()} />
+  );
+  const { rerender } = render(show({ status: "password", incorrect: false }));
+  expect(document.activeElement).not.toBe(screen.getByLabelText("Password"));
+  // Submitting shows the loading state, then the prompt comes back.
+  rerender(show({ status: "loading" }));
+  rerender(show({ status: "password", incorrect: true }));
+  expect(document.activeElement).toBe(screen.getByLabelText("Password"));
+});
@@ -0,0 +1,117 @@
+import type { PdfDocumentState } from "@v1/hooks/usePdfDocument";
+import { type FormEvent, useEffect, useId, useRef, useState } from "react";
+
+/** Every state except `ready`, which the page list renders instead. */
+export type ViewerStatusState = Exclude<PdfDocumentState, { status: "ready" }>;
+
+export interface ViewerStatusProps {
+  state: ViewerStatusState;
+  onRetry: () => void;
+  onSubmitPassword: (password: string) => void;
+}
+
+const panel =
+  "ui:flex ui:h-full ui:min-h-48 ui:flex-col ui:items-center ui:justify-center ui:gap-3 ui:p-6 ui:text-center ui:text-body ui:text-muted-foreground";
+const title = "ui:text-section-title ui:text-foreground";
+const button =
+  "ui:inline-flex ui:items-center ui:justify-center ui:rounded-md ui:bg-primary ui:px-4 ui:py-2 ui:text-body ui:text-primary-foreground ui:focus-visible:focus-ring";
+
+/** What the viewer shows while a document loads, fails, or needs a password. */
+export function ViewerStatus({
+  state,
+  onRetry,
+  onSubmitPassword,
+}: ViewerStatusProps) {
+  switch (state.status) {
+    case "loading":
+      return (
+        <output className={panel} aria-live="polite">
+          Loading document…
+        </output>
+      );
+    case "empty":
+      return (
+        <div className={panel}>
+          <p className={title}>No document</p>
+          <p>There is nothing to show yet.</p>
+        </div>
+      );
+    case "unsupported":
+      return (
+        <div className={panel} role="alert">
+          <p className={title}>This file can't be previewed</p>
+          <p>It isn't a PDF, or the PDF is damaged.</p>
+        </div>
+      );
+    case "failed":
+      return (
+        <div className={panel} role="alert">
+          <p className={title}>The document didn't load</p>
+          <p>{state.message}</p>
+          <button type="button" className={button} onClick={onRetry}>
+            Retry
+          </button>
+        </div>
+      );
+    case "password":
+      return (
+        <PasswordPrompt
+          incorrect={state.incorrect}
+          onSubmit={onSubmitPassword}
+        />
+      );
+  }
+}
+
+function PasswordPrompt({
+  incorrect,
+  onSubmit,
+}: {
+  incorrect: boolean;
+  onSubmit: (password: string) => void;
+}) {
+  const [password, setPassword] = useState("");
+  const inputId = useId();
+  const errorId = useId();
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  // Submitting swaps this form for the loading state, so the field's focus is
+  // lost. When the prompt comes back after a wrong password, give it back, so
+  // a keyboard user can retype straight away. Not on first showing: the
+  // viewer does not take focus from the page around it unasked.
+  useEffect(() => {
+    if (incorrect) {
+      inputRef.current?.focus();
+    }
+  }, [incorrect]);
+  const submit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (password !== "") {
+      onSubmit(password);
+    }
+  };
+  return (
+    <form className={panel} onSubmit={submit}>
+      <p className={title}>This document is password-protected</p>
+      <label htmlFor={inputId}>Password</label>
+      <input
+        ref={inputRef}
+        id={inputId}
+        type="password"
+        autoComplete="off"
+        value={password}
+        onChange={(event) => setPassword(event.target.value)}
+        aria-invalid={incorrect}
+        aria-describedby={incorrect ? errorId : undefined}
+        className="ui:rounded-md ui:border ui:border-input ui:bg-background ui:px-3 ui:py-2 ui:text-body ui:text-foreground ui:focus-visible:focus-ring"
+      />
+      {incorrect && (
+        <p id={errorId} role="alert" className="ui:text-destructive">
+          That password is incorrect.
+        </p>
+      )}
+      <button type="submit" className={button}>
+        Open
+      </button>
+    </form>
+  );
+}
@@ -0,0 +1,195 @@
+import { act, renderHook } from "@testing-library/react";
+import type { PdfOpening, PdfOpenOptions } from "@v1/lib/pdf/pdfjs";
+import type { OpenedPdf, PdfSource } from "@v1/lib/pdf/types";
+import type { PDFDocumentProxy } from "pdfjs-dist";
+import { beforeEach, expect, it, vi } from "vitest";
+import { usePdfDocument } from "./usePdfDocument";
+
+interface FakeOpening extends PdfOpening {
+  source: PdfSource;
+  /** Asks for a password the way pdf.js does, mid-load. */
+  askPassword: (incorrect: boolean) => void;
+  submitted: string[];
+  resolve: (value: OpenedPdf) => void;
+  reject: (error: unknown) => void;
+  destroy: ReturnType<typeof vi.fn>;
+}
+
+const openings: FakeOpening[] = [];
+
+vi.mock("@v1/lib/pdf/pdfjs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@v1/lib/pdf/pdfjs")>();
+  return {
+    ...actual,
+    openPdfDocument: (
+      source: PdfSource,
+      options: PdfOpenOptions = {},
+    ): PdfOpening => {
+      let resolve!: (value: OpenedPdf) => void;
+      let reject!: (error: unknown) => void;
+      const promise = new Promise<OpenedPdf>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      const submitted: string[] = [];
+      const opening: FakeOpening = {
+        source,
+        submitted,
+        askPassword: (incorrect) =>
+          options.onPassword?.({
+            incorrect,
+            submit: (password) => submitted.push(password),
+          }),
+        promise,
+        resolve,
+        reject,
+        destroy: vi.fn(),
+      };
+      openings.push(opening);
+      return opening;
+    },
+  };
+});
+
+const document = { numPages: 2 } as unknown as PDFDocumentProxy;
+const pageSizes = [
+  { width: 612, height: 792 },
+  { width: 792, height: 612 },
+];
+const url = (path: string): PdfSource => ({ kind: "url", url: path });
+
+function latest(): FakeOpening {
+  const opening = openings.at(-1);
+  if (!opening) {
+    throw new Error("nothing was opened");
+  }
+  return opening;
+}
+
+beforeEach(() => {
+  openings.length = 0;
+});
+
+it("is empty without a source and opens nothing", () => {
+  const { result } = renderHook(() => usePdfDocument(null));
+  expect(result.current.state).toEqual({ status: "empty" });
+  expect(openings).toHaveLength(0);
+});
+
+it("goes from loading to ready with the page sizes", async () => {
+  const { result } = renderHook(() => usePdfDocument(url("/a.pdf")));
+  expect(result.current.state).toEqual({ status: "loading" });
+  await act(async () => latest().resolve({ document, pageSizes }));
+  expect(result.current.state).toEqual({
+    status: "ready",
+    document,
+    pageSizes,
+  });
+});
+
+it("does not reopen when re-rendered with an equal, new source object", () => {
+  const { rerender } = renderHook(() => usePdfDocument(url("/a.pdf")));
+  rerender();
+  rerender();
+  expect(openings).toHaveLength(1);
+});
+
+it("treats a document with no pages as empty", async () => {
+  const { result } = renderHook(() => usePdfDocument(url("/a.pdf")));
+  await act(async () => latest().resolve({ document, pageSizes: [] }));
+  expect(result.current.state).toEqual({ status: "empty" });
+});
+
+it("fails with the message, and Retry opens the same source again", async () => {
+  const { result } = renderHook(() => usePdfDocument(url("/a.pdf")));
+  await act(async () =>
+    latest().reject(
+      Object.assign(new Error("Missing PDF"), { name: "MissingPDFException" }),
+    ),
+  );
+  expect(result.current.state).toEqual({
+    status: "failed",
+    message: "The document wasn't found.",
+  });
+
+  act(() => result.current.retry());
+  expect(result.current.state).toEqual({ status: "loading" });
+  expect(openings).toHaveLength(2);
+  expect(openings[0]?.destroy).toHaveBeenCalled();
+  expect(latest().source).toEqual(url("/a.pdf"));
+});
+
+it("reports a non-PDF as unsupported", async () => {
+  const { result } = renderHook(() => usePdfDocument(url("/a.txt")));
+  await act(async () =>
+    latest().reject(
+      Object.assign(new Error("Invalid PDF"), { name: "InvalidPDFException" }),
+    ),
+  );
+  expect(result.current.state).toEqual({ status: "unsupported" });
+});
+
+it("asks for a password and carries on with the same load, without reopening", async () => {
+  const { result } = renderHook(() => usePdfDocument(url("/locked.pdf")));
+  act(() => latest().askPassword(false));
+  expect(result.current.state).toEqual({
+    status: "password",
+    incorrect: false,
+  });
+
+  act(() => result.current.submitPassword("wrong"));
+  expect(latest().submitted).toEqual(["wrong"]);
+  expect(result.current.state).toEqual({ status: "loading" });
+  act(() => latest().askPassword(true));
+  expect(result.current.state).toEqual({ status: "password", incorrect: true });
+
+  act(() => result.current.submitPassword("right"));
+  await act(async () => latest().resolve({ document, pageSizes }));
+  expect(result.current.state.status).toBe("ready");
+  expect(openings).toHaveLength(1);
+  expect(latest().submitted).toEqual(["wrong", "right"]);
+});
+
+it("answers a password prompt once, and ignores a password nobody asked for", () => {
+  const { result } = renderHook(() => usePdfDocument(url("/locked.pdf")));
+  act(() => result.current.submitPassword("early"));
+  act(() => latest().askPassword(false));
+  act(() => result.current.submitPassword("first"));
+  act(() => result.current.submitPassword("second"));
+  expect(latest().submitted).toEqual(["first"]);
+});
+
+it("destroys the old load when the source changes, and ignores its result", async () => {
+  const { result, rerender } = renderHook(
+    ({ path }) => usePdfDocument(url(path)),
+    { initialProps: { path: "/a.pdf" } },
+  );
+  const first = latest();
+  rerender({ path: "/b.pdf" });
+  expect(first.destroy).toHaveBeenCalledTimes(1);
+  expect(result.current.state).toEqual({ status: "loading" });
+
+  await act(async () => first.resolve({ document, pageSizes }));
+  expect(result.current.state).toEqual({ status: "loading" });
+  expect(latest().source).toEqual(url("/b.pdf"));
+});
+
+it("drops a password prompt when the source changes", () => {
+  const { result, rerender } = renderHook(
+    ({ path }) => usePdfDocument(url(path)),
+    { initialProps: { path: "/a.pdf" } },
+  );
+  const first = latest();
+  act(() => first.askPassword(false));
+  rerender({ path: "/b.pdf" });
+  act(() => result.current.submitPassword("secret"));
+  expect(first.submitted).toEqual([]);
+  expect(latest().submitted).toEqual([]);
+  expect(result.current.state).toEqual({ status: "loading" });
+});
+
+it("destroys the load on unmount", () => {
+  const { unmount } = renderHook(() => usePdfDocument(url("/a.pdf")));
+  unmount();
+  expect(latest().destroy).toHaveBeenCalledTimes(1);
+});