@u1f992/pdfdiff 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@u1f992/pdfdiff",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Visualize and quantify differences between two PDF files.",
   "main": "dist/index.js",
   "bin": {
@@ -10,7 +10,11 @@
     "test": "node --test",
     "test:cli": "node src/cli.js test/a.pdf test/b.pdf out --mask test/mask.pdf --dpi 300 && echo \"expected: Page 1, Addition: 7500, Deletion: 7500, Modification: 7500\"",
     "build:version": "node scripts/version.ts",
-    "build": "npm run build:version && rollup -c",
+    "build:wasm": "docker run --rm --volume .:/workdir --workdir /workdir --user root --entrypoint bash emscripten/emsdk:5.0.7 scripts/build-wasm.sh",
+    "format:wasm": "docker run --rm --volume .:/workdir --workdir /workdir --user root --entrypoint bash emscripten/emsdk:5.0.7 scripts/build-wasm.sh format",
+    "tidy:wasm": "docker run --rm --volume .:/workdir --workdir /workdir --user root --entrypoint bash emscripten/emsdk:5.0.7 scripts/build-wasm.sh tidy",
+    "clean:wasm": "docker run --rm --volume .:/workdir --workdir /workdir --user root --entrypoint bash emscripten/emsdk:5.0.7 scripts/build-wasm.sh clean",
+    "build": "npm run build:wasm && npm run build:version && rollup -c",
     "serve": "npm run build && http-server dist"
   },
   "repository": {
@@ -19,7 +23,7 @@
   },
   "keywords": [],
   "author": "Koutaro Mukai",
-  "license": "GPL-3.0",
+  "license": "AGPL-3.0-only",
   "bugs": {
     "url": "https://github.com/u1f992/pdfdiff/issues"
   },
@@ -32,8 +36,10 @@
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/node": "^22.18.7",
     "coi-serviceworker": "^0.1.7",
+    "fflate": "^0.8.2",
     "http-server": "^14.1.1",
     "nodehog": "^0.1.2",
+    "path-browserify": "^1.0.1",
     "prettier": "^3.5.3",
     "rollup": "^4.42.0",
     "rollup-plugin-copy": "^3.5.0",
@@ -41,9 +47,10 @@
     "typescript": "^5.9.2"
   },
   "dependencies": {
+    "@jsquash/png": "^3.1.1",
+    "@u1f992/gs-wasm": "0.3.0",
     "ix": "^7.0.0",
     "jimp": "^1.6.0",
-    "mupdf": "^1.26.2",
     "web-worker": "^1.5.0"
   }
 }

package/rollup.config.js

@@ -11,10 +11,6 @@ const plugins = [
   commonjs(),
   copy({
     targets: [
-      {
-        src: "node_modules/mupdf/dist/mupdf-wasm.wasm",
-        dest: "dist",
-      },
       {
         src: "node_modules/coi-serviceworker/coi-serviceworker.min.js",
         dest: "dist",
@@ -27,10 +23,30 @@ const plugins = [
         src: "src/style.css",
         dest: "dist",
       },
+      {
+        src: "src/wasm/core.wasm",
+        dest: "dist",
+      },
+      // Ghostscript (gs-wasm) Emscripten glue + binary. The `index.js`/
+      // `worker.js` ESM wrappers are re-bundled (below) into dist/gs-wasm/ so
+      // their bare imports (`web-worker`, `upath`) resolve in the browser; the
+      // large glue is shipped as-is and imported as a sibling by worker.js.
+      {
+        src: [
+          "node_modules/@u1f992/gs-wasm/dist/gs.js",
+          "node_modules/@u1f992/gs-wasm/dist/gs.wasm",
+        ],
+        dest: "dist/gs-wasm",
+      },
     ],
   }),
 ];
 
+// gs-wasm is kept external (not bundled): the CLI resolves it from node_modules,
+// while the browser bundles load it from the copied dist/gs-wasm/ folder.
+const GS_WASM = "@u1f992/gs-wasm";
+const gsWasmPaths = { [GS_WASM]: "./gs-wasm/index.js" };
+
 const jimpAlias = alias({
   entries: [
     {
@@ -51,12 +67,26 @@ const webWorkerAlias = alias({
   ],
 });
 
+// gs-wasm's worker depends on `upath`, which imports node's `path`. Shim it for
+// the browser. Scoped to the gs-wasm worker bundle only so the Node CLI bundles
+// keep the real `path`.
+const pathAlias = alias({
+  entries: [
+    {
+      find: "path",
+      replacement: path.resolve("node_modules/path-browserify/index.js"),
+    },
+  ],
+});
+
 const rollupConfig = defineConfig([
   {
     input: "src/index.ts",
+    external: [GS_WASM],
     output: {
       file: "dist/index.js",
       sourcemap: true,
+      paths: gsWasmPaths,
     },
     plugins: [
       jimpAlias,
@@ -83,18 +113,40 @@ const rollupConfig = defineConfig([
       file: "dist/cli.js",
       sourcemap: true,
     },
-    external: ["web-worker"],
+    external: ["web-worker", GS_WASM],
     plugins: [
       typescript({ tsconfig: "./tsconfig.json" }),
       nodeResolve(),
       commonjs(),
     ],
   },
+  {
+    input: "src/cli-png-worker.ts",
+    output: {
+      file: "dist/cli-png-worker.js",
+      sourcemap: true,
+    },
+    plugins: [
+      typescript({ tsconfig: "./tsconfig.json" }),
+      nodeResolve(),
+      commonjs(),
+      copy({
+        targets: [
+          {
+            src: "node_modules/@jsquash/png/codec/pkg/squoosh_png_bg.wasm",
+            dest: "dist",
+          },
+        ],
+      }),
+    ],
+  },
   {
     input: "src/browser.ts",
+    external: [GS_WASM],
     output: {
       file: "dist/browser.js",
       sourcemap: true,
+      paths: gsWasmPaths,
     },
     plugins: [
       jimpAlias,
@@ -103,6 +155,32 @@ const rollupConfig = defineConfig([
       ...plugins,
     ],
   },
+  // Re-bundle gs-wasm's ESM wrappers into dist/gs-wasm/ with their bare
+  // dependencies resolved, so the browser can load them as plain static files.
+  // The main-thread wrapper spawns ./worker.js (sibling) via new URL(...).
+  {
+    input: "node_modules/@u1f992/gs-wasm/dist/index.js",
+    output: {
+      file: "dist/gs-wasm/index.js",
+      format: "es",
+      sourcemap: true,
+    },
+    plugins: [webWorkerAlias, nodeResolve(), commonjs()],
+  },
+  // The worker wrapper imports the (large) emscripten glue as a sibling
+  // ./gs.js, which is copied verbatim; everything else (upath, status) is
+  // bundled in.
+  {
+    input: "node_modules/@u1f992/gs-wasm/dist/worker.js",
+    external: (id) => id === "./gs.js" || id.endsWith("/gs.js"),
+    output: {
+      file: "dist/gs-wasm/worker.js",
+      format: "es",
+      sourcemap: true,
+      paths: { "./gs.js": "./gs.js" },
+    },
+    plugins: [pathAlias, nodeResolve(), commonjs()],
+  },
 ]);
 
 export default rollupConfig;

package/scripts/build-wasm.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+set -eEuo pipefail
+shopt -s inherit_errexit
+trap 'echo "Error on line $LINENO: $BASH_COMMAND (exit $?)" >&2' ERR
+
+# Align the ubuntu user in the emscripten/emsdk image with the mounted
+# workdir's owner so files we create are owned by the host user, and so we
+# can write back into /workdir regardless of the host user's UID. Without
+# this the script fails on hosts whose user is not UID 1000 (e.g. GitHub
+# Actions' runner is UID 1001).
+HOST_UID=$(stat --format='%u' /workdir)
+HOST_GID=$(stat --format='%g' /workdir)
+if [ "$HOST_UID" -ne 0 ] && [ "$HOST_UID" -ne "$(id -u ubuntu)" ]; then
+  groupmod --non-unique --gid "$HOST_GID" ubuntu
+  usermod --non-unique --uid "$HOST_UID" --gid "$HOST_GID" ubuntu
+  chown --recursive "$HOST_UID:$HOST_GID" /home/ubuntu
+fi
+
+TARGET=${1:-all}
+
+# clang-format / clang-tidy are only needed for the format and tidy targets
+# and are not part of the emscripten/emsdk base image; install on demand.
+case "$TARGET" in
+format | tidy)
+  DEBIAN_FRONTEND=noninteractive apt-get update -qq >/dev/null
+  DEBIAN_FRONTEND=noninteractive apt-get install -qq --yes --no-install-recommends \
+    clang-format clang-tidy >/dev/null
+  ;;
+esac
+
+exec runuser -u ubuntu -- bash -c "cd /workdir && make -C wasm $TARGET"

package/src/browser.ts

@@ -1,11 +1,81 @@
 /// <reference lib="dom" />
 
+import encode from "@jsquash/png/encode";
+import { zipSync } from "fflate";
+
 import * as pdfdiff from "./index.ts";
 import { VERSION } from "./version.ts";
 
+async function encodeBitmapToPng(img: {
+  width: number;
+  height: number;
+  bitmap: {
+    data: Uint8Array<ArrayBuffer> | Uint8ClampedArray<ArrayBuffer>;
+  };
+}): Promise<Uint8Array> {
+  const data = img.bitmap.data;
+  const view: Uint8ClampedArray<ArrayBuffer> =
+    data instanceof Uint8ClampedArray
+      ? data
+      : new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength);
+  const png = await encode(new ImageData(view, img.width, img.height));
+  return new Uint8Array(png);
+}
+
 const versionEl = document.getElementById("version");
 if (versionEl) versionEl.textContent = "v" + VERSION;
 
+const hideNoDiffEl = document.getElementById(
+  "hide-no-diff",
+) as HTMLInputElement | null;
+const applyHideNoDiff = () => {
+  document.body.classList.toggle("hide-no-diff", !!hideNoDiffEl?.checked);
+};
+hideNoDiffEl?.addEventListener("change", applyHideNoDiff);
+applyHideNoDiff();
+
+const downloadButton = document.getElementById(
+  "download-zip",
+) as HTMLButtonElement | null;
+type ResultPage = {
+  a: Uint8Array;
+  b: Uint8Array;
+  diff: Uint8Array;
+  hasDiff: boolean;
+};
+let lastResultPages: Map<number, ResultPage> | null = null;
+const updateDownloadLabel = () => {
+  if (!downloadButton) return;
+  downloadButton.textContent = hideNoDiffEl?.checked
+    ? "Download zip (diff only)"
+    : "Download zip";
+};
+hideNoDiffEl?.addEventListener("change", updateDownloadLabel);
+updateDownloadLabel();
+
+downloadButton?.addEventListener("click", () => {
+  if (!lastResultPages) return;
+  const diffOnly = !!hideNoDiffEl?.checked;
+  const files: Record<string, Uint8Array> = {};
+  for (const [i, page] of lastResultPages) {
+    if (diffOnly && !page.hasDiff) continue;
+    files[`${i}/a.png`] = page.a;
+    files[`${i}/b.png`] = page.b;
+    files[`${i}/diff.png`] = page.diff;
+  }
+  if (Object.keys(files).length === 0) return;
+  const zipped = zipSync(files, { level: 0 });
+  const blob = new Blob([new Uint8Array(zipped)], { type: "application/zip" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = diffOnly ? "pdfdiff-result-diff-only.zip" : "pdfdiff-result.zip";
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+});
+
 async function readFileAsUint8Array(file: File): Promise<Uint8Array> {
   return new Promise((resolve, reject) => {
     const reader = new FileReader();
@@ -28,6 +98,19 @@ document
     const errorElement = document.getElementById("error-message");
     if (errorElement) errorElement.textContent = "";
 
+    const submitButton = (event.currentTarget as HTMLFormElement).querySelector(
+      'button[type="submit"]',
+    ) as HTMLButtonElement | null;
+    const originalSubmitText = submitButton?.textContent ?? "";
+    if (submitButton) {
+      submitButton.disabled = true;
+      submitButton.textContent = "Preparing...";
+    }
+    if (downloadButton) downloadButton.disabled = true;
+    lastResultPages = null;
+    const resultPages = new Map<number, ResultPage>();
+    let completed = false;
+
     try {
       const pdfAFile = (
         document.getElementById("pdf-a") as HTMLInputElement | null
@@ -66,10 +149,11 @@ document
         throw new Error();
       }
 
-      const workers = ((
-        val = (document.getElementById("workers") as HTMLInputElement | null)
-          ?.value,
-      ) => (typeof val !== "undefined" ? parseInt(val, 10) : undefined))();
+      const workersRaw = (
+        document.getElementById("workers") as HTMLInputElement | null
+      )?.value;
+      // Empty input means "use the default" (which scales with CPU cores).
+      const workers = workersRaw ? parseInt(workersRaw, 10) : undefined;
       if (
         typeof workers !== "undefined" &&
         (Number.isNaN(workers) || workers < 1)
@@ -123,10 +207,13 @@ document
         pdfdiff.visualizeDifferences(pdfA, pdfB, options),
         1,
       )) {
+        if (submitButton) submitButton.textContent = `Page ${i}...`;
         const pageResult = document.createElement("details");
         pageResult.className = "diff-details";
-        pageResult.open =
-          addition.length + deletion.length + modification.length > 0;
+        const totalDiff =
+          addition.length + deletion.length + modification.length;
+        if (totalDiff === 0) pageResult.classList.add("no-diff");
+        pageResult.open = totalDiff > 0;
 
         const summary = document.createElement("summary");
 
@@ -165,23 +252,39 @@ document
 
         const imagesRow = document.createElement("tr");
 
+        const aPng = await encodeBitmapToPng(a);
+        const bPng = await encodeBitmapToPng(b);
+        const diffPng = await encodeBitmapToPng(diff);
+        resultPages.set(i, {
+          a: aPng,
+          b: bPng,
+          diff: diffPng,
+          hasDiff: totalDiff > 0,
+        });
+
         const cellA = document.createElement("td");
         const imageA = document.createElement("img");
-        imageA.src = await a.getBase64("image/png");
+        imageA.src = URL.createObjectURL(
+          new Blob([new Uint8Array(aPng)], { type: "image/png" }),
+        );
         imageA.className = "checkerboard-bg";
         cellA.appendChild(imageA);
         imagesRow.appendChild(cellA);
 
         const cellB = document.createElement("td");
         const imageB = document.createElement("img");
-        imageB.src = await b.getBase64("image/png");
+        imageB.src = URL.createObjectURL(
+          new Blob([new Uint8Array(bPng)], { type: "image/png" }),
+        );
         imageB.className = "checkerboard-bg";
         cellB.appendChild(imageB);
         imagesRow.appendChild(cellB);
 
         const cellDiff = document.createElement("td");
         const imageDiff = document.createElement("img");
-        imageDiff.src = await diff.getBase64("image/png");
+        imageDiff.src = URL.createObjectURL(
+          new Blob([new Uint8Array(diffPng)], { type: "image/png" }),
+        );
         imageDiff.className = "checkerboard-bg";
         cellDiff.appendChild(imageDiff);
         imagesRow.appendChild(cellDiff);
@@ -191,10 +294,20 @@ document
         pageResult.appendChild(imagesTable);
         resultsContainer?.appendChild(pageResult);
       }
+      completed = true;
     } catch (e) {
       console.error(e);
       if (errorElement) {
         errorElement.textContent = `Error: ${(e as Error).message}`;
       }
+    } finally {
+      if (submitButton) {
+        submitButton.disabled = false;
+        submitButton.textContent = originalSubmitText;
+      }
+      if (completed && resultPages.size > 0) {
+        lastResultPages = resultPages;
+        if (downloadButton) downloadButton.disabled = false;
+      }
     }
   });

package/src/cli-png-worker.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parentPort } from "node:worker_threads";
+
+import encode, { init } from "@jsquash/png/encode";
+
+export type EncodeJob = {
+  width: number;
+  height: number;
+  data: ArrayBuffer;
+  path: string;
+};
+
+export type EncodeReply = { ok: true } | { ok: false; error: string };
+
+const wasmPath = fileURLToPath(
+  new URL("./squoosh_png_bg.wasm", import.meta.url),
+);
+await init(fs.readFileSync(wasmPath));
+
+if (!parentPort) {
+  throw new Error("cli-png-worker must be run as a worker_threads worker");
+}
+
+const port = parentPort;
+
+port.on("message", async (job: EncodeJob) => {
+  try {
+    const png = await encode(
+      new ImageData(new Uint8ClampedArray(job.data), job.width, job.height),
+    );
+    fs.writeFileSync(job.path, new Uint8Array(png));
+    const reply: EncodeReply = { ok: true };
+    port.postMessage(reply);
+  } catch (e) {
+    const reply: EncodeReply = {
+      ok: false,
+      error: e instanceof Error ? `${e.message}\n${e.stack}` : String(e),
+    };
+    port.postMessage(reply);
+  }
+});

package/src/cli.ts

@@ -1,26 +1,11 @@
 #!/usr/bin/env node
 
-/*
- * Copyright (C) 2025  Koutaro Mukai
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
 import fs from "node:fs";
 import path from "node:path";
 import util from "node:util";
+import { Worker as ThreadWorker } from "node:worker_threads";
 
+import type { EncodeJob, EncodeReply } from "./cli-png-worker.ts";
 import {
   isValidAlignStrategy,
   defaultOptions,
@@ -28,9 +13,65 @@ import {
   parseHex,
   formatHex,
   visualizeDifferences,
+  perf,
 } from "./index.ts";
+import { sliceBackingBuffer } from "./transferable.ts";
 import { VERSION } from "./version.ts";
 
+class PngWriterPool {
+  private readonly workers: ThreadWorker[] = [];
+  private readonly idle: ThreadWorker[] = [];
+  private readonly waiting: Array<(w: ThreadWorker) => void> = [];
+
+  constructor(size: number, scriptUrl: URL) {
+    for (let i = 0; i < size; i++) {
+      const w = new ThreadWorker(scriptUrl);
+      this.workers.push(w);
+      this.idle.push(w);
+    }
+  }
+
+  private acquire(): Promise<ThreadWorker> {
+    const w = this.idle.pop();
+    if (w) return Promise.resolve(w);
+    return new Promise<ThreadWorker>((resolve) => this.waiting.push(resolve));
+  }
+
+  private release(w: ThreadWorker) {
+    const next = this.waiting.shift();
+    if (next) next(w);
+    else this.idle.push(w);
+  }
+
+  async submit(job: EncodeJob): Promise<void> {
+    const w = await this.acquire();
+    return new Promise<void>((resolve, reject) => {
+      const onMessage = (msg: EncodeReply) => {
+        w.off("message", onMessage);
+        w.off("error", onError);
+        this.release(w);
+        if (msg.ok) resolve();
+        else reject(new Error(msg.error));
+      };
+      const onError = (err: Error) => {
+        w.off("message", onMessage);
+        w.off("error", onError);
+        this.release(w);
+        reject(err);
+      };
+      w.on("message", onMessage);
+      w.once("error", onError);
+      w.postMessage(job, [job.data]);
+    });
+  }
+
+  async terminate(): Promise<void> {
+    await Promise.all(this.workers.map((w) => w.terminate()));
+  }
+}
+
+const _wallSpan = perf.span("cli.wallTotal_ms");
+
 const {
   positionals,
   values: {
@@ -80,12 +121,15 @@ OPTIONS:
     -h, --help
 
 NOTES:
-    Approximate per-worker memory:
-        a_size_MB + b_size_MB [+ mask_size_MB]    (PDF buffers in wasm)
-        + 300 MB                                  (mupdf + V8 base)
-        + (dpi / 150)^2 * 50 MB                   (pixmap working set)
-    The main process adds ~500 MB - 1 GB (varies with --workers).
-    Choose --workers so the total stays under ~80% of available memory.
+    Pages are rendered with Ghostscript (gs-wasm). Each page render spins up a
+    transient Ghostscript instance (~26 MB WASM binary plus a rasterization
+    working set that grows with --dpi). A and B (and the mask) render
+    concurrently, and --workers controls how many pages are rendered and diffed
+    in parallel, so peak memory scales with both --workers and --dpi. Each
+    in-flight page additionally holds decoded RGBA bitmaps of ~width*height*4
+    bytes. --workers defaults to the CPU core count (capped at 4); lower it to
+    reduce memory, or raise it for large jobs on big machines. Keep the total
+    under ~80% of available memory.
 `);
   process.exit(0);
 }
@@ -149,6 +193,13 @@ if (Number.isNaN(workers) || workers < 1) {
 }
 
 fs.mkdirSync(outDir, { recursive: true });
+const writerPool = new PngWriterPool(
+  workers,
+  new URL("./cli-png-worker.js", import.meta.url),
+);
+const pendingWrites: Promise<void>[] = [];
+
+const _loopSpan = perf.span("cli.loopWall_ms");
 for await (const [
   i,
   { a, b, diff, addition, deletion, modification },
@@ -172,16 +223,44 @@ for await (const [
   );
   const dir = path.join(outDir, i.toString(10));
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(
-    path.join(dir, "a.png"),
-    new Uint8Array(await a.getBuffer("image/png")),
-  );
-  fs.writeFileSync(
-    path.join(dir, "b.png"),
-    new Uint8Array(await b.getBuffer("image/png")),
-  );
-  fs.writeFileSync(
-    path.join(dir, "diff.png"),
-    new Uint8Array(await diff.getBuffer("image/png")),
+  const sSubmit = perf.span("cli.poolSubmit_ms");
+  const aBuf = sliceBackingBuffer(a.bitmap.data);
+  const bBuf = sliceBackingBuffer(b.bitmap.data);
+  const dBuf = sliceBackingBuffer(diff.bitmap.data);
+  pendingWrites.push(
+    writerPool.submit({
+      width: a.width,
+      height: a.height,
+      data: aBuf,
+      path: path.join(dir, "a.png"),
+    }),
+    writerPool.submit({
+      width: b.width,
+      height: b.height,
+      data: bBuf,
+      path: path.join(dir, "b.png"),
+    }),
+    writerPool.submit({
+      width: diff.width,
+      height: diff.height,
+      data: dBuf,
+      path: path.join(dir, "diff.png"),
+    }),
   );
+  sSubmit.stop();
+}
+const sDrain = perf.span("cli.poolDrain_ms");
+await Promise.all(pendingWrites);
+sDrain.stop();
+await writerPool.terminate();
+_loopSpan.stop();
+_wallSpan.stop();
+
+if (perf.enabled) {
+  const counters = perf.dump();
+  process.stderr.write("\n=== PERF ===\n");
+  const keys = Object.keys(counters).sort();
+  const out: Record<string, number> = {};
+  for (const k of keys) out[k] = Math.round(counters[k]! * 1000) / 1000;
+  process.stderr.write(JSON.stringify(out, null, 2) + "\n");
 }

package/src/decode.ts

@@ -0,0 +1,15 @@
+import * as jimp from "jimp";
+
+import type { JimpInstance } from "./jimp.ts";
+
+/**
+ * Decode PNG bytes (as produced by {@link renderPageRangePng}) into an RGBA
+ * image.
+ * `jimp.fromBuffer` accepts an ArrayBuffer directly, which keeps this usable in
+ * the browser without relying on Node's `Buffer`.
+ */
+export async function decodePng(
+  png: ArrayBuffer,
+): Promise<JimpInstance> {
+  return (await jimp.Jimp.fromBuffer(png)) as JimpInstance;
+}