Add Windows PDFium system-renderer fallback for render_pdf_page/region

[dancarloni]

Summary

render_pdf_page and render_pdf_region have never had a Windows fallback: pdfjsRendererPolicy(), systemRenderPage/Region, and runSystemCommand's spawn whitelist were all darwin-only, so any host whose native @napi-rs/canvas binding is blocked or unavailable on win32 gets "No PDF page renderer is available in this host" with no recourse — including Claude Desktop's embedded Electron UtilityProcess, which already has a proven, deliberate native-canvas block with its own crash latch and no fallback to catch it on Windows.

• Adds a Windows counterpart to the macOS qlmanage/sips fallback, using Google Chromium's official PDFium prebuilt library (via bblanchon/pdfium-binaries) called through koffi FFI, with PNG encoding done in pure JavaScript (server/png-encoder.js) since PDFium's C API renders to a raw bitmap and has no image encoder.
• Isolation is hybrid, because a single mechanism fails differently in each host that matters:
  • Ordinary Windows hosts (Cursor, a plain CLI run): the PDFium render runs in a disposable child process, spawned through the same runSystemCommand sandboxing already proven for qlmanage/sips on darwin (whitelisted command, shell:false, strict argument-shape validation, a hard timeout, one system-render child at a time).
  • Claude Desktop's embedded Electron UtilityProcess: relaunching process.execPath as a child process is not reliable there (its process.execPath is the Electron/Claude binary, not a plain node.exe). The render instead runs on a dedicated worker_threads.Worker, terminated on the same deadline, mirroring the pattern already proven in this codebase for the QPDF WebAssembly decryption worker and for pdf-lib mutations inside this exact host.
• pdfjsRendererPolicy() now returns native_with_system_fallback on win32 when the vendored pdfium.dll exists for the host's architecture; output-schemas.js's renderer enum gains "windows-pdfium".
• Vendors the official win-x64 and win-arm64 PDFium builds (bblanchon/pdfium-binaries tag chromium/8044, PDFium 155.0.8044.0, built without V8/XFA) under vendor/pdfium/, verified against pinned SHA-256 hashes in sources.lock.json and reproducible via scripts/vendor-pdfium-runtime.mjs. Every bundled component is permissively licensed (BSD/MIT/zlib/Apache-2.0/FTL/Unicode), no copyleft, all compatible with this project's MIT license — see vendor/pdfium/README.md and runtime.provenance.json.
• Adds koffi as a dependency (prebuilt per-platform bindings, no compilation) and test/pdfium-runtime-artifact.test.js, which binds the committed DLLs to their pinned hashes and (gated to win32) actually loads pdfium.dll and renders a page. .github/workflows/windows-render.yml and its probe script now also exercise this path on the existing windows-latest workflow_dispatch job, including the scenario this fallback was built for: the embedded native-canvas block in force with the system renderer available.
• Regenerates the npm license provenance record for koffi's locked packages and the layout-occurrence-oracle.v1.json fixture (both stale after this change touched package.json/package-lock.json and output-schemas.js); fixes test/mcp-contract.test.js's share-mirror file count/list and pinned tool-contract hash; adds renderer_label to two hand-built system_command test fixtures. Mirrors all server-side changes into pdf-toolkit-mcp-share/ per this project's existing convention.
• Does not touch the macOS qlmanage/sips renderer path, its error messages' default wording, or its tests: shared error-message helpers now take an optional rendererLabel (default "macOS", unused by every existing call site).
• Wires vendor/pdfium/ and koffi into scripts/build-mcpb.mjs's per-target staging (stagePdfiumDllsForTarget, installKoffiForTarget, win32 targets only), extends the staged-vendor-inventory assertion and its provenance check (verifyPdfiumRuntime), and updates the CycloneDX SBOM (scripts/pdfium-sbom.mjs) so a built .mcpb now actually ships the DLLs and platform-specific koffi bindings for win32-x64/arm64. The Cursor share ZIP intentionally excludes PDFium (Windows-only, MCPB-specific).

Test plan

• npm test — clean except for pre-existing, environment-specific failures unrelated to this change (confirmed against a clean baseline checkout of the same base commit): process-group/chmod-dependent and network-dependent tests that don't behave correctly in a sandboxed CI-like container running as root.
• npm run build:mcpb — reproducible, byte-identical build; staged MCPB verified to contain vendor/pdfium/runtime/win-{x64,arm64}/pdfium.dll and the platform-specific koffi packages.
• npm run smoke:mcpb — passes against the built artifact.
• npm run test:contract:share — passes; share package correctly excludes the Windows-only PDFium runtime.
• test/pdfium-runtime-artifact.test.js — 6/7 pass on Linux; the 7th (real pdfium.dll load + render) is gated to win32 and will run for real on windows-latest.
• Manual render_pdf_page/render_pdf_region run on a real Windows host — requested from the PR author; not yet performed.

This PR has already been developed, tested, and verified on a fork (dancarloni#1), where it is green on CI and mergeable. This request proposes it as an upstream contribution, as a draft pending review from the Open Document Alliance maintainers.

[Copilot]

🟡 Changes recommended

Unresolved critical and moderate findings remain in Windows compatibility, rendering isolation, correctness, and MCPB/SBOM packaging.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a Windows PDFium fallback for PDF page and region rendering when native canvas is unavailable.

Changes:

• Adds PDFium/koffi rendering, hybrid isolation, and pure-JavaScript PNG encoding.
• Vendors Windows runtimes and updates packaging, SBOM, provenance, licensing, and dependencies.
• Adds mirrored share-package updates, contract changes, artifact tests, and Windows CI coverage.

File summaries

File	Reviewed changes / final comments
vendor/pdfium/sources.lock.json	Pins PDFium sources and hashes.
vendor/pdfium/runtime.provenance.json	Runtime provenance; nit (3 votes): stale integration status and incorrect share ZIP claim.
vendor/pdfium/README.md	Runtime documentation; nit (2 votes): documented generation does not match the promotion script.
vendor/pdfium/licenses/zlib.txt	Bundled license notice.
vendor/pdfium/licenses/simdutf.txt	Bundled license notice.
vendor/pdfium/licenses/pdfium.txt	Bundled license notice.
vendor/pdfium/licenses/pdfium-binaries-build-scripts.txt	Bundled license notice.
vendor/pdfium/licenses/manifest.json	License manifest.
vendor/pdfium/licenses/llvm-libc.txt	Bundled license notice.
vendor/pdfium/licenses/libpng.txt	Bundled license notice.
vendor/pdfium/licenses/libopenjpeg.txt	Bundled license notice.
vendor/pdfium/licenses/libjpeg_turbo.md	Bundled license notice.
vendor/pdfium/licenses/libjpeg_turbo.ijg	Bundled license notice.
vendor/pdfium/licenses/lcms.txt	Bundled license notice.
vendor/pdfium/licenses/freetype.txt	Bundled license notice.
vendor/pdfium/licenses/fast_float.txt	Bundled license notice.
vendor/pdfium/licenses/agg23.txt	Bundled license notice.
vendor/pdfium/licenses/abseil.txt	Bundled license notice.
vendor/npm-licenses/npm-license-provenance.json	Regenerated npm license provenance.
test/pdfjs-subprocess-boundary.test.js	Updates system-command fixtures.
test/pdfium-runtime-artifact.test.js	Verifies runtime hashes and Windows loading/rendering.
test/mcp-contract.test.js	Updates share-package contract data.
test/fixtures/eval/extraction/phase1/layout-occurrence-oracle.v1.json	Regenerated evaluation fixture.
server/png-encoder.js	Pure-JavaScript PNG encoding; nit (1 vote): add decoded pixel validation.
server/pdfjs-worker.js	Windows rendering and isolation; critical (1 vote): worker termination cannot contain native crashes; nits (2 and 3 votes): subprocess and region paths lack CI coverage.
server/pdfjs-subprocess.js	Windows command validation and subprocess support.
server/pdfium-render-host.mjs	PDFium FFI rendering; moderate (1 vote): pass page rotation to PDFium.
server/output-schemas.js	Adds the Windows renderer enum; critical (1 vote): update trajectory-grader renderer allowlists.
server/index.js	Enables Windows fallback selection; critical (2 votes): update the Windows renderer-policy test assertion.
scripts/vendor-pdfium-runtime.mjs	Promotes pinned runtime assets; moderate (1 vote): rebuild runtime and license directories from scratch.
scripts/test-share-contract.mjs	Share-package contract support.
scripts/plugin-shipped-paths.mjs	Shipped-path inventory support.
scripts/pdfium-sbom.mjs	PDFium SBOM generation; moderate findings (1, 2, 1, and 1 votes): fix notice URLs and hashes, add DLL references, and use valid SPDX identifiers.
scripts/pdfium-runtime.mjs	Defines and verifies PDFium runtime assets.
scripts/build-mcpb.mjs	Stages Windows runtime assets; moderate (3 votes): include PDFium license notices and synchronize inventory/hash checks.
pdf-toolkit-mcp-share/server/png-encoder.js	Mirrored PNG encoder.
pdf-toolkit-mcp-share/server/pdfjs-worker.js	Mirrored Windows rendering worker.
pdf-toolkit-mcp-share/server/pdfjs-subprocess.js	Mirrored subprocess support.
pdf-toolkit-mcp-share/server/pdfium-render-host.mjs	Mirrored PDFium rendering host.
pdf-toolkit-mcp-share/server/output-schemas.js	Mirrored output schema updates.
pdf-toolkit-mcp-share/server/index.js	Mirrored renderer policy updates.
pdf-toolkit-mcp-share/package.json	Mirrored package metadata.
package.json	Adds koffi dependency.
package-lock.json	Locks dependency updates.
package-for-friend.js	Packaging and SBOM integration; moderate (3 votes): add PDFium records to the generated MCPB SBOM.
.github/workflows/windows-render.yml	Adds Windows rendering workflow coverage.
.github/workflows/windows-render-probe.mjs	Adds embedded-host rendering probe.
.gitattributes	Tracks vendored runtime assets appropriately.

Review details

Files not reviewed (1)

• pdf-toolkit-mcp-share/package-lock.json: Generated file

Suppressed comments (6)

scripts/pdfium-sbom.mjs:113

• Even after the notices are staged, this reference drops the licenses/ directory: the files live at vendor/pdfium/licenses/<name>, so every CycloneDX license URL currently points to a nonexistent path. Include licenses/ in the URL so SBOM consumers can resolve the notices.

  const assetPath = `vendor/pdfium/${notice.file}`;

scripts/pdfium-sbom.mjs:162

• The PDFium runtime component has no hash or distribution reference for either architecture's pdfium.dll, even though the provenance record carries both digests. The generated SBOM therefore cannot bind the shipped native payload to the reviewed bytes, unlike the existing QPDF runtime component; add architecture-specific DLL references and hashes.

  return {
    type: "library",
    "bom-ref": RUNTIME_BOM_REF,
    group: "pdf-tools",
    name: "pdfium-runtime",
    version,
    scope: "required",
    description:
      `Official Google Chromium PDFium prebuilt binaries from bblanchon/pdfium-binaries, `
      + `shipping Windows platform binaries (win-x64 and win-arm64) at ${RUNTIME_DIRECTORY}/ `
      + `in the MCPB for Windows targets only.`,
    purl: `pkg:generic/pdf-tools/pdfium-runtime@${version}`

scripts/pdfium-sbom.mjs:200

• PDFIUM_SBOM_COMPONENTS copies each provenance spdx value directly into a CycloneDX license expression, but the new provenance uses AGG for agg23 and the repository's pinned SPDX identifier record contains no AGG identifier. Once this graph is included, the component and composite runtime license emit an invalid SPDX expression; use a valid SPDX identifier or an explicit LicenseRef-* representation and validate it.

  return bundledAndRecipe.map(notice => ({
    type: "library",
    "bom-ref": `urn:pdf-tools:pdfium-bundled:${notice.component}`,
    name: notice.component,
    version: notice.component.includes(" ") ? notice.component.split(" ").pop() : "embedded",
    scope: "required",
    description: `${notice.component}; statically linked into ${RUNTIME_DIRECTORY}/pdfium.dll (Windows platforms only).`,
    licenses: [{ expression: notice.spdx }],
    externalReferences: [
      noticeReference(provenance, notice),
    ],

scripts/vendor-pdfium-runtime.mjs:81

• The promotion script writes into existing runtime and license directories without clearing them first. If a future pinned release removes a DLL or notice, rerunning this generator leaves the old file behind and writeLicenseManifest() records it as shipped, so the promoted tree is no longer an exact representation of the pinned archives. Rebuild the promoted directories from scratch before copying the new assets, as the QPDF promotion script does.

  const runtimeDir = path.join(VENDOR_DIR, "runtime", asset.arch);
  await mkdir(runtimeDir, { recursive: true });
  await writeFile(path.join(runtimeDir, "pdfium.dll"), await readFile(dllPath));

server/pdfium-render-host.mjs:105

• The PDFium render call hard-codes its rotate argument to 0, while systemRenderPageWindows() sizes and crops the bitmap from PDF.js's already-rotated page view. PDFium's render API takes page rotation explicitly, so a page with /Rotate is rendered in unrotated page space and region crops can be misplaced or distorted. Pass the page rotation (or an equivalent transform) to PDFium and cover a rotated page in the Windows system-renderer path.

    fn.FPDFBitmap_FillRect(bitmap, 0, 0, widthPx, heightPx, 0xffffffff);
    fn.FPDF_RenderPageBitmap(bitmap, page, 0, 0, widthPx, heightPx, 0, FPDF_ANNOT);

server/png-encoder.js:81

• The new encoder's current runtime check only verifies the PNG signature; the Windows artifact test does not decode the image or verify pixel values. A BGRA channel, row-order, or stride regression could therefore pass the Windows gate while returning a corrupted render. Add a focused test with known RGBA bytes and assert decoded dimensions and pixels.

  const raw = Buffer.alloc((stride + 1) * height);
  const rgbaBuffer = Buffer.isBuffer(rgba) ? rgba : Buffer.from(rgba);
  for (let row = 0; row < height; row += 1) {
    const rawOffset = row * (stride + 1);
    raw[rawOffset] = 0; // filter type: None

• Files reviewed: 28/52 changed files
• Comments generated: 8
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.