deps: replace abandoned pdf-lib with the maintained @cantoo/pdf-lib fork (#5672)

[atomantic]

Summary

PortOS generates PDFs on four user-facing export paths — comic issue, trade volume, prose print interior, and the legacy archive bundle. All four sat on pdf-lib@1.17.1, which has had no npm publish since 2022-05-12: the pinned version and the latest published version are the same release. It is not deprecated and npm audit has always been clean, but it parses and serializes a hostile binary format, so the day a PDF advisory lands there is no upstream release to take. Doing the migration now makes it a planned change instead of an emergency one.

@cantoo/pdf-lib is a same-license (MIT) fork of the same project, actively published, and it preserves the PDFDocument / rgb / StandardFonts public API this codebase uses. The swap is four import lines, one manifest line, and the lockfile — no export changes its layout, fonts, page geometry, or output.

What changed

• server/package.json — pdf-lib@^1.17.1 → @cantoo/pdf-lib@2.9.1 (exact pin, matching the manifest's dominant convention).
• Four import sites updated: server/services/pipeline/volumePdf.js, comicPdf.js, proseExport.js, and server/services/legacyExport.js. Prose comments naming the package were updated alongside them so a future dependency sweep greps clean.
• server/package-lock.json regenerated. Lockfile goes 380 → 385 packages (+5 net); npm audit reports 0 vulnerabilities.
• docs/DEPS.md — the pdf-lib row becomes an @cantoo/pdf-lib Tier 2 KEEP row plus a pdf-lib | — | REPLACED row, with a Detailed Findings subsection recording the API surface, the transitive delta, and a re-audit trigger (revisit if the fork itself goes >12 months without a publish, or on any CVE).

Two things worth flagging

The issue scoped three import sites; there are four. server/services/legacyExport.js contains a byte sequence that makes file(1) classify it as data, so plain grep -r silently skips it. It surfaced only as an ERR_MODULE_NOT_FOUND in the suite. That caveat is now recorded in docs/DEPS.md — a repo-wide dependency sweep must use grep -ra.

Two boundary tests, not import-level ones. A same-API fork can only regress below the helper layer, so both new tests assert real output bytes:

• proseExport.test.js — buildProsePdf returns a Uint8Array starting %PDF- and ending %%EOF, above an empty-document floor. Catches a fork whose save() returns a different container type, which would break every streaming caller while passing every existing helper test.
• comicPdf.test.js — embedded image XObjects scale with the rendered page count (ratio, not a hard-coded count, since an RGBA PNG carries its alpha as a separate SMask object). Catches a silently dropped drawImage payload, which would otherwise emit a structurally valid PDF of blank pages.

No unit tests were added for the layout helpers — they are deterministic and already exercised through these callers (AGENTS.md Test Strategy).

Test plan

• cd server && npm test — 1834 files / 37283 tests pass.
• cd server && npm audit — 0 vulnerabilities.
• grep -ra "pdf-lib" server scripts docs --include='*.js' --include='*.md' returns only @cantoo/pdf-lib matches and the DEPS.md history prose.
• grep -c '"node_modules/pdf-lib"' server/package-lock.json → 0.
• Local codex review round — one finding (an inaccurate transitive-dependency count in the DEPS.md prose), verified against the regenerated lockfile and fixed in a follow-up commit.

Closes #5672

https://claude.ai/code/session_01GMxEz43s3YCLaVZV9KmVwE