feat(export): pre-download validation pass for glyph loss and bullet-page splits (#621) (#872)

Adds a pre-download validation pass that surfaces two known render defects
instead of failing silently: characters the export font has no glyph for,
and bullets a page break falls inside. Glyph-loss findings name the
character as authored (not the cased probe the renderer's heading
uppercase transform produces), so the user can search their résumé for
the character actually reported.

Closes #621

Author: s-annam

src/components/features/ExportDialog.test.tsx

@@ -25,6 +25,7 @@ import { createRoot, type Root } from "react-dom/client";
 import type { CascadeResult } from "../../lib/heuristics/types.ts";
 import type { AnonymousAtsScore } from "../../lib/score/score.ts";
 import type { ContactOverrides } from "../../hooks/useEditableParse.ts";
+import type { RenderFinding } from "../../lib/pdf/render-findings.ts";
 
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
   true;
@@ -33,6 +34,9 @@ const pdfDownload = vi.fn();
 const markdownDownload = vi.fn();
 const reportDownload = vi.fn(() => Promise.resolve(true));
 let pdfError: string | null = null;
+/** #621 export findings the PDF row surfaces — empty for a clean export, which
+ *  is what every case here renders unless it says otherwise. */
+let pdfFindings: RenderFinding[] = [];
 
 /** What each hook was handed as its journey Download-stage mark site (#826).
  *  The success point lives inside the hooks, so what this component owns — and
@@ -46,7 +50,12 @@ vi.mock("../../hooks/useDownloadPdf.ts", () => ({
     onDownloaded?: () => void,
   ) => {
     captured.pdf = onDownloaded;
-    return { download: pdfDownload, isGenerating: false, error: pdfError };
+    return {
+      download: pdfDownload,
+      isGenerating: false,
+      error: pdfError,
+      findings: pdfFindings,
+    };
   },
 }));
 vi.mock("../../hooks/useDownloadMarkdown.ts", () => ({
@@ -154,6 +163,7 @@ beforeEach(() => {
   markdownDownload.mockClear();
   reportDownload.mockClear();
   pdfError = null;
+  pdfFindings = [];
   // jsdom does not implement modal dialogs in every version, and the primitive
   // calls `showModal()` from an effect. Stubbed to a plain open so the tests
   // exercise the dialog's CONTENT rather than the UA's modality.
@@ -421,4 +431,46 @@ describe("ExportDialog", () => {
     }
     expect(onExported).toHaveBeenCalledTimes(3);
   });
+
+  // #621 — the export reports what it could not render cleanly, on the row that
+  // produced the file. Advisory: the user already has the PDF.
+  describe("export findings", () => {
+    it("renders NO warning chrome when the export was clean", () => {
+      // The common case. A permanent "0 issues" strip on the download row would
+      // train every user to stop reading it.
+      const el = render(exportable());
+      expect(text(el)).not.toContain("Check the export");
+      expect(el.querySelector("[aria-live]:not([aria-live=\"off\"]) ul")).toBeNull();
+    });
+
+    it("names the field and states what happened, never colour alone", () => {
+      pdfFindings = [
+        {
+          kind: "glyph-degraded",
+          severity: "warning",
+          sourceField: "Experience \u2192 Staff Engineer \u00b7 Acme \u2192 bullet 3",
+          detail: 'The export font has no glyph for "\u2605", so it was drawn as "?".',
+        },
+      ];
+      const el = render(exportable());
+      // The badge carries a WORD, not just a tone.
+      expect(text(el)).toContain("Check the export");
+      expect(text(el)).toContain("Experience \u2192 Staff Engineer \u00b7 Acme \u2192 bullet 3");
+      expect(text(el)).toContain("\u2605");
+      // And it says the file arrived — a finding is not a refusal.
+      expect(text(el)).toContain("Your PDF downloaded");
+    });
+
+    it("counts the overflow instead of listing forty rows", () => {
+      pdfFindings = Array.from({ length: 8 }, (_, i) => ({
+        kind: "glyph-degraded" as const,
+        severity: "info" as const,
+        sourceField: `Experience \u2192 Role ${i + 1}`,
+        detail: 'The export font has no glyph for "\u2192", so it was drawn as "->".',
+      }));
+      const el = render(exportable());
+      expect(el.querySelectorAll("li")).toHaveLength(5);
+      expect(text(el)).toContain("and 3 more");
+    });
+  });
 });

src/components/features/ExportDialog.tsx

@@ -73,6 +73,7 @@ import {
 } from "../../lib/contact.ts";
 import { ExportGateBody, fixFirstGap } from "./ExportGateBody.tsx";
 import { ExportRow, ExportReportRow } from "./ExportRows.tsx";
+import { ExportFindings } from "./ExportFindings.tsx";
 import { useDownloadPdf } from "../../hooks/useDownloadPdf.ts";
 import { useDownloadMarkdown } from "../../hooks/useDownloadMarkdown.ts";
 import { useDownloadReport } from "../../hooks/useDownloadReport.ts";
@@ -198,6 +199,11 @@ export function ExportDialog({
             >
               {pdf.isGenerating ? "Generating…" : "Download PDF"}
             </Button>
+            {/* What the export could not draw cleanly (#621) — advisory, and
+                renders NOTHING for the clean résumé that is the common case.
+                It sits on the row that produced the file, beside the row's own
+                `ErrorState`, because that is the surface already mounted. */}
+            <ExportFindings findings={pdf.findings} />
           </ExportRow>
 
           <ExportRow

src/components/features/ExportFindings.tsx

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The offlinecv Authors
+
+/**
+ * ExportFindings — what the exporter could not render cleanly, shown on the row
+ * that produced the file (#621).
+ *
+ * Reuse analysis (CLAUDE.md Golden Rule). This is NOT a new banner primitive.
+ * The design-system barrel deliberately ships no Toast/Snackbar, and its house
+ * pattern for "an action finished and has something to say" is to confirm IN the
+ * surface already mounted rather than open a new one — so this swaps content
+ * into `ExportRow`, beside the `ErrorState` that already reports a failed
+ * export, and carries its status on the shared `StatusBadge`. Nothing new is
+ * added to the design system.
+ *
+ * Three rules it exists to keep:
+ *
+ *  1. **Zero findings renders NOTHING.** Not an empty "0 issues" panel, not a
+ *     green all-clear. Most résumés are clean, and a permanent status strip on
+ *     the download row would teach every user to stop reading it.
+ *  2. **Never colour alone.** The badge carries the WORD, the sentence states
+ *     the count, and every finding names its own field — the tone is
+ *     reinforcement.
+ *  3. **Advisory, never a blocker.** The user already has their PDF by the time
+ *     this renders; the copy says so. Refusing a download is `useDownloadPdf`'s
+ *     #664 font gate and stays there.
+ *
+ * `aria-live="polite"` announces the swap. The parent format list is itself a
+ * polite live region, so the announcement would happen regardless; declaring it
+ * here keeps the guarantee attached to the component that needs it rather than
+ * to a container that could be restructured.
+ */
+
+import { StatusBadge } from "@design-system";
+import type { RenderFinding } from "../../lib/pdf/render-findings.ts";
+
+/**
+ * How many findings are listed before the rest are counted. A résumé pasted from
+ * a source full of arrows can produce one finding per bullet; forty rows in a
+ * dialog is a wall, and the first few already say what kind of thing is wrong
+ * and where to start.
+ */
+const MAX_LISTED = 5;
+
+export function ExportFindings({
+  findings,
+}: {
+  findings: readonly RenderFinding[];
+}) {
+  if (findings.length === 0) return null;
+  const listed = findings.slice(0, MAX_LISTED);
+  const rest = findings.length - listed.length;
+  // `warning` when anything was actually destroyed; `info` when every finding is
+  // a substitution that still reads correctly (an arrow drawn as "->").
+  const tone = findings.some((f) => f.severity === "warning") ? "warning" : "info";
+
+  return (
+    <div aria-live="polite" className="flex flex-col gap-2">
+      <div className="flex flex-wrap items-center gap-2">
+        <StatusBadge tone={tone}>Check the export</StatusBadge>
+        <p className="text-sm text-content-secondary">
+          Your PDF downloaded, but{" "}
+          {findings.length === 1
+            ? "one thing"
+            : `${findings.length} things`}{" "}
+          did not come out as written.
+        </p>
+      </div>
+      <ul className="flex flex-col gap-1">
+        {listed.map((finding, idx) => (
+          <li
+            key={`${finding.kind}:${finding.sourceField}:${finding.detail}:${idx}`}
+            className="text-sm text-content-tertiary"
+          >
+            <span className="font-medium text-content-secondary">
+              {finding.sourceField}
+            </span>{" "}
+            — {finding.detail}
+          </li>
+        ))}
+      </ul>
+      {rest > 0 && (
+        <p className="text-sm text-content-tertiary">
+          …and {rest} more like {rest === 1 ? "this" : "these"}.
+        </p>
+      )}
+    </div>
+  );
+}

src/hooks/useDownloadPdf.ts

@@ -17,6 +17,11 @@
  * résumé bytes leave the browser, which is the actual guarantee. Say custody,
  * not runtime.
  *
+ * It also carries the export's own findings (#621) — what the renderer could
+ * not draw cleanly — back to the surface. Those are ADVISORY and arrive only
+ * after the bytes have reached the user: the refusal below is the one thing that
+ * stops a download, and reporting must never grow into a second one.
+ *
  * This hook owns the refusal for #664. When the Poppins fetch fails, the
  * renderer falls back to Helvetica, whose WinAnsi codec replaces anything
  * outside it with `?` — including a candidate's own name. Rather than hand back
@@ -37,6 +42,7 @@ import {
   renderAtsResumePdf,
   type ExportGlyphLoss,
 } from "../lib/pdf/render-ats-pdf.ts";
+import type { RenderFinding } from "../lib/pdf/render-findings.ts";
 import { slugifyName, triggerBlobDownload } from "../lib/download/blob-download.ts";
 import { trackDownloadCompleted, type DownloadSource } from "../lib/analytics.ts";
 import { clearBlankDraft } from "./useResumeAnalysis.ts";
@@ -45,6 +51,13 @@ export interface UseDownloadPdf {
   download: () => Promise<void>;
   isGenerating: boolean;
   error: string | null;
+  /**
+   * What the LAST completed render could not draw cleanly (#621) — empty until a
+   * download has run, and empty again the moment the next one starts, so the
+   * surface can never show findings that belong to a résumé the user has since
+   * edited. Advisory only: the download already happened.
+   */
+  findings: RenderFinding[];
 }
 
 /** Turn a candidate name into a safe, lower-kebab PDF filename. */
@@ -87,10 +100,14 @@ export function useDownloadPdf(
 ): UseDownloadPdf {
   const [isGenerating, setIsGenerating] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [findings, setFindings] = useState<RenderFinding[]>([]);
 
   const download = useCallback(async () => {
     setIsGenerating(true);
     setError(null);
+    // Cleared up front, alongside `error`, for the same reason: a stale report
+    // about the PREVIOUS export would read as a verdict on this one.
+    setFindings([]);
     try {
       const model = buildAtsResumeModel(result, score);
 
@@ -105,14 +122,17 @@ export function useDownloadPdf(
         return;
       }
 
-      const bytes = await renderAtsResumePdf(model);
+      const { bytes, findings: rendered } = await renderAtsResumePdf(model);
       // `bytes.slice()` copies into a fresh ArrayBuffer-backed view so Blob gets
       // a clean buffer.
       triggerBlobDownload(
         bytes.slice(),
         "application/pdf",
         filenameFromName(model.contact.name),
       );
+      // AFTER the download, never before: a finding is a report on the file the
+      // user now has, not a gate in front of it (#621).
+      setFindings(rendered);
 
       // Distinguish a from-scratch authored download from an uploaded one
       // (#313). `tiers` is empty ONLY for `buildBlankResult()`'s output —
@@ -137,5 +157,5 @@ export function useDownloadPdf(
     // is keyed to the résumé that was on screen then.
   }, [result, score, onDownloaded]);
 
-  return { download, isGenerating, error };
+  return { download, isGenerating, error, findings };
 }

src/lib/edit/description-override-roundtrip.repro.test.ts

@@ -114,7 +114,7 @@ describe("descriptionOverrides edit-leg round-trip (#489)", { timeout: 20000 },
       display,
       scoreEditedResume(applied, p1.triggers, []),
     );
-    const p3 = await runCascade(await renderAtsResumePdf(model));
+    const p3 = await runCascade((await renderAtsResumePdf(model)).bytes);
 
     const p3Text = JSON.stringify(p3.canonical.fields);
     expect(p3Text.includes(NEW_DESCRIPTION)).toBe(true);

src/lib/heuristics/corpus-edit-roundtrip.test.ts

@@ -543,7 +543,7 @@ async function editRoundtrip(
       display,
       scoreEditedResume(applied, p1.triggers, Object.keys(edits.bullets)),
     );
-    return { p3: await runCascade(await renderAtsResumePdf(model)) };
+    return { p3: await runCascade((await renderAtsResumePdf(model)).bytes) };
   } catch (err) {
     return { renderError: `export/re-parse threw: ${(err as Error).message}` };
   }

src/lib/heuristics/multi-experience-roundtrip.test.ts

@@ -97,7 +97,7 @@ describe("#311 multiple experience sections — parse + round-trip", { timeout:
     const bytes = await fsp.readFile(FIXTURE);
     const parse1 = await runCascade(new Uint8Array(bytes));
     const model = buildAtsResumeModel(parse1, scoreOf(parse1));
-    const exportedBytes = await renderAtsResumePdf(model);
+    const { bytes: exportedBytes } = await renderAtsResumePdf(model);
     const parse3 = await runCascade(new Uint8Array(exportedBytes));
 
     // Two distinct experience-category groups on the way IN. (The export

src/lib/heuristics/roundtrip-hop.ts

@@ -78,7 +78,7 @@ export async function runRoundtripHop(
     layer = HOP_LAYERS[1];
     const model = buildAtsResumeModel(before, score);
     layer = HOP_LAYERS[2];
-    const bytes = await renderAtsResumePdf(model);
+    const { bytes } = await renderAtsResumePdf(model);
     layer = HOP_LAYERS[3];
     return { after: await runCascade(bytes) };
   } catch (err) {

src/lib/pdf/export-layout-contract.test.ts

@@ -185,7 +185,7 @@ async function drawnLines(
   build: ModelBuilder,
   filler: number,
 ): Promise<PdfDrawnLine[]> {
-  return extractPdfDrawnLines(await renderAtsResumePdf(build(filler)));
+  return extractPdfDrawnLines((await renderAtsResumePdf(build(filler))).bytes);
 }
 
 /** Index of the single drawn line containing `token` (fails if 0 or 2+ match). */
@@ -766,7 +766,7 @@ describe("export layout contract — keep-with-next pagination (#629)", () => {
         },
       ],
     };
-    const lines = await extractPdfDrawnLines(await renderAtsResumePdf(model));
+    const lines = await extractPdfDrawnLines((await renderAtsResumePdf(model)).bytes);
     const pages = Math.max(...lines.map((l) => l.page));
     const densest = Math.max(
       ...Array.from({ length: pages }, (_, i) => linesOnPage(lines, i + 1)),
@@ -827,7 +827,7 @@ describe("export layout contract — the Summary body honours widow control", ()
    *  {@link bulletLinesPerPage} returns, so a `1` is the widow. */
   async function summaryLinesPerPage(words: number): Promise<number[]> {
     const lines = await extractPdfDrawnLines(
-      await renderAtsResumePdf(summaryModel(words)),
+      (await renderAtsResumePdf(summaryModel(words))).bytes,
     );
     const perPage = new Map<number, number>();
     for (const line of lines) {

src/lib/pdf/render-ats-pdf.flush-right-links.test.ts

@@ -90,7 +90,7 @@ const MODEL: AtsResumeModel = {
 
 describe("renderAtsResumePdf — flush-right dates + link annotations (#425)", () => {
   it("draws the entry date flush-right against the content margin", async () => {
-    const { items } = await inspect(await renderAtsResumePdf(MODEL));
+    const { items } = await inspect((await renderAtsResumePdf(MODEL)).bytes);
     // A year token from the date range, on the right side of the page.
     const dateItems = items.filter((i) => /20(20|23)/.test(i.str) && i.x > 300);
     expect(dateItems.length).toBeGreaterThan(0);
@@ -105,7 +105,7 @@ describe("renderAtsResumePdf — flush-right dates + link annotations (#425)", (
   });
 
   it("registers clickable URI link annotations for the contact links", async () => {
-    const { links } = await inspect(await renderAtsResumePdf(MODEL));
+    const { links } = await inspect((await renderAtsResumePdf(MODEL)).bytes);
     expect(links).toContain("https://linkedin.com/in/jane");
     expect(links).toContain("https://github.com/jane");
     expect(links).toContain("mailto:jane@example.com");
@@ -125,7 +125,7 @@ describe("renderAtsResumePdf — flush-right dates + link annotations (#425)", (
       },
       sections: [],
     };
-    const { annots } = await inspect(await renderAtsResumePdf(model));
+    const { annots } = await inspect((await renderAtsResumePdf(model)).bytes);
     const email = annots.find((a) => a.url === "mailto:jane@example.com");
     const site = annots.find((a) => a.url.startsWith("https://example.com"));
     expect(email).toBeDefined();
@@ -148,7 +148,7 @@ describe("renderAtsResumePdf — flush-right dates + link annotations (#425)", (
     };
     // pdfjs may normalize a bare-host URL with a trailing slash, so match on the
     // scheme+host rather than an exact string.
-    const { links } = await inspect(await renderAtsResumePdf(model));
+    const { links } = await inspect((await renderAtsResumePdf(model)).bytes);
     expect(links.some((u) => u.startsWith("https://www.jane.dev"))).toBe(true);
     expect(links.some((u) => u.startsWith("http://portfolio.example"))).toBe(true);
     // The naive display-rebuilt targets (www dropped, forced https) must NOT appear.