@u1f992/pdfdiff 0.2.2 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@u1f992/pdfdiff",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Visualize and quantify differences between two PDF files.",
   "main": "dist/index.js",
   "bin": {
@@ -8,9 +8,13 @@
   },
   "scripts": {
     "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\"",
+    "test:cli": "node dist/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"
   },
@@ -35,6 +39,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",
@@ -43,9 +48,9 @@
   },
   "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/prettier.config.js

@@ -1,3 +1,3 @@
 const prettierConfig = {};
 
-export default prettierConfig;
+export default prettierConfig;

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,7 +113,7 @@ const rollupConfig = defineConfig([
       file: "dist/cli.js",
       sourcemap: true,
     },
-    external: ["web-worker"],
+    external: ["web-worker", GS_WASM],
     plugins: [
       typescript({ tsconfig: "./tsconfig.json" }),
       nodeResolve(),
@@ -112,9 +142,11 @@ const rollupConfig = defineConfig([
   },
   {
     input: "src/browser.ts",
+    external: [GS_WASM],
     output: {
       file: "dist/browser.js",
       sourcemap: true,
+      paths: gsWasmPaths,
     },
     plugins: [
       jimpAlias,
@@ -123,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

@@ -9,10 +9,12 @@ import { VERSION } from "./version.ts";
 async function encodeBitmapToPng(img: {
   width: number;
   height: number;
-  bitmap: { data: Uint8Array | Uint8ClampedArray };
+  bitmap: {
+    data: Uint8Array<ArrayBuffer> | Uint8ClampedArray<ArrayBuffer>;
+  };
 }): Promise<Uint8Array> {
   const data = img.bitmap.data;
-  const view =
+  const view: Uint8ClampedArray<ArrayBuffer> =
     data instanceof Uint8ClampedArray
       ? data
       : new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength);
@@ -147,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)

package/src/cli-png-worker.ts

@@ -1,20 +1,3 @@
-/*
- * 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 { fileURLToPath } from "node:url";
 import { parentPort } from "node:worker_threads";

package/src/cli.ts

@@ -1,22 +1,5 @@
 #!/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";
@@ -87,6 +70,17 @@ class PngWriterPool {
   }
 }
 
+// Errors always exit 2, following diff(1)'s 0/1/2 convention, so that with
+// --exit-code a caller can tell "differences found" (1) from a failed run.
+process.on("uncaughtException", (err) => {
+  console.error(err);
+  process.exit(2);
+});
+process.on("unhandledRejection", (err) => {
+  console.error(err);
+  process.exit(2);
+});
+
 const _wallSpan = perf.span("cli.wallTotal_ms");
 
 const {
@@ -100,6 +94,7 @@ const {
     "deletion-color": deletionColorHex,
     "modification-color": modificationColorHex,
     workers: workers_,
+    "exit-code": exitCode_,
     version,
     help,
   },
@@ -114,6 +109,7 @@ const {
     "deletion-color": { type: "string" },
     "modification-color": { type: "string" },
     workers: { type: "string" },
+    "exit-code": { type: "boolean" },
     version: { type: "boolean", short: "v" },
     help: { type: "boolean", short: "h" },
   },
@@ -134,16 +130,25 @@ OPTIONS:
     --deletion-color <#HEX>        default: ${formatHex(defaultOptions.pallet.deletion)}
     --modification-color <#HEX>    default: ${formatHex(defaultOptions.pallet.modification)}
     --workers <N>                  default: ${defaultOptions.workers}
+    --exit-code                    exit 1 if differences are found
     -v, --version
     -h, --help
 
+EXIT STATUS:
+    0    success (with --exit-code: no differences found)
+    1    differences found (only with --exit-code)
+    2    error
+
 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);
 }
@@ -206,12 +211,15 @@ if (Number.isNaN(workers) || workers < 1) {
   throw new Error("Invalid workers value");
 }
 
+const exitCodeOnDiff = exitCode_ ?? false;
+
 fs.mkdirSync(outDir, { recursive: true });
 const writerPool = new PngWriterPool(
   workers,
   new URL("./cli-png-worker.js", import.meta.url),
 );
 const pendingWrites: Promise<void>[] = [];
+let hasDiff = false;
 
 const _loopSpan = perf.span("cli.loopWall_ms");
 for await (const [
@@ -235,6 +243,9 @@ for await (const [
   console.log(
     `Page ${i}, Addition: ${addition.length}, Deletion: ${deletion.length}, Modification: ${modification.length}`,
   );
+  if (addition.length > 0 || deletion.length > 0 || modification.length > 0) {
+    hasDiff = true;
+  }
   const dir = path.join(outDir, i.toString(10));
   fs.mkdirSync(dir, { recursive: true });
   const sSubmit = perf.span("cli.poolSubmit_ms");
@@ -270,6 +281,10 @@ await writerPool.terminate();
 _loopSpan.stop();
 _wallSpan.stop();
 
+if (exitCodeOnDiff && hasDiff) {
+  process.exitCode = 1;
+}
+
 if (perf.enabled) {
   const counters = perf.dump();
   process.stderr.write("\n=== PERF ===\n");

package/src/decode.ts

@@ -0,0 +1,13 @@
+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;
+}

package/src/diff.ts

@@ -1,20 +1,3 @@
-/*
- * 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 { type JimpInstance } from "./jimp.ts";
 import { alignSize, createEmptyImage, type AlignStrategy } from "./image.ts";
 import { perf } from "./perf.ts";

package/src/image.ts

@@ -1,20 +1,3 @@
-/*
- * 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 * as jimp from "jimp";
 import { type JimpInstance } from "./jimp.ts";
 import { perf } from "./perf.ts";
@@ -69,7 +52,7 @@ function alignImage(
   targetWidth: number,
   targetHeight: number,
   align: AlignStrategy,
-) {
+): JimpInstance {
   if (align === "resize") {
     return img.resize({ w: targetWidth, h: targetHeight });
   } else {

package/src/index.html

@@ -49,7 +49,7 @@
         </div>
         <div>
           <label for="workers">Workers:</label>
-          <input type="number" id="workers" value="1" min="1" />
+          <input type="number" id="workers" placeholder="auto" min="1" />
         </div>
         <div>
           <label for="addition-color">Addition:</label>

package/src/index.test.ts

@@ -1,26 +1,10 @@
-/*
- * 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 assert from "node:assert/strict";
 import fs from "node:fs";
 import test from "node:test";
 
 import {
   defaultOptions,
+  defaultWorkers,
   formatHex,
   isValidAlignStrategy,
   parseHex,
@@ -50,10 +34,18 @@ test("defaultOptions", () => {
       deletion: [0xff, 0x57, 0x24, 0xff],
       modification: [0xff, 0xc1, 0x05, 0xff],
     },
-    workers: 1,
+    workers: defaultWorkers,
   });
 });
 
+test("defaultWorkers scales with cores, capped at 4", () => {
+  assert.equal(
+    defaultWorkers,
+    Math.max(1, Math.min(globalThis.navigator?.hardwareConcurrency ?? 1, 4)),
+  );
+  assert.ok(defaultWorkers >= 1 && defaultWorkers <= 4);
+});
+
 test("isValidAlignStrategy", async (ctx) => {
   for (const s of [
     "resize",