@u1f992/pdfdiff 0.2.1 → 0.3.0

package/src/iterable.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/>.
- */
-
 export async function* withIndex<T>(iter: AsyncIterable<T>, start = 0) {
   let index = start;
   for await (const item of iter) {

package/src/jimp.ts

@@ -1,15 +1,33 @@
 import * as jimp from "jimp";
 
+/**
+ * Narrowed view of `jimp.JimpInstance` used throughout the project.
+ *
+ * Two constraints are tightened relative to the upstream type:
+ *
+ * 1. `bitmap.data` is asserted to be `Uint8Array<ArrayBuffer>` (never
+ *    SAB-backed). jimp allocates pixels via `Buffer`, which is always
+ *    backed by a real ArrayBuffer in practice. Pinning the generic
+ *    parameter here lets `sliceBackingBuffer` (and `postMessage` transfer
+ *    lists) infer ArrayBuffer instead of ArrayBufferLike.
+ *
+ * 2. `resize` and `composite` return `JimpInstance` (this narrowed type)
+ *    rather than upstream `jimp.JimpInstance`, so chaining preserves the
+ *    bitmap-backing constraint above.
+ */
 export type JimpInstance = Pick<
   jimp.JimpInstance,
-  | "width"
-  | "height"
-  | "bitmap"
-  | "getPixelColor"
-  | "setPixelColor"
-  | "resize"
-  | "composite"
+  "width" | "height" | "getPixelColor" | "setPixelColor"
 > & {
+  bitmap: {
+    data: Uint8Array<ArrayBuffer>;
+    width: number;
+    height: number;
+  };
+  resize: (options: Parameters<jimp.JimpInstance["resize"]>[0]) => JimpInstance;
+  composite: (
+    ...args: Parameters<jimp.JimpInstance["composite"]>
+  ) => JimpInstance;
   getBuffer: (mime: "image/png") => ReturnType<jimp.JimpInstance["getBuffer"]>;
   getBase64: (mime: "image/png") => ReturnType<jimp.JimpInstance["getBase64"]>;
 };

package/src/pdf.ts

@@ -1,74 +1,111 @@
+import { gs } from "@u1f992/gs-wasm";
+
+import { perf } from "./perf.ts";
+
 /*
- * 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.
+ * Pages are rendered with Ghostscript (gs-wasm). Each gs() invocation spins up
+ * its own worker and Ghostscript instance, so we render one page per call and
+ * let the caller drive concurrency (e.g. by rendering A/B/mask together and by
+ * running multiple page workers).
  *
- * 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/>.
+ * Ghostscript (via the `web-worker` package) must be invoked from a context
+ * that can itself spawn a worker. In Node's `web-worker` this is only the main
+ * thread, so rendering happens on the main thread and the resulting PNG bytes
+ * are handed off to the diff workers for decoding. The PDF is placed in
+ * Ghostscript's in-memory FS as `input.pdf` and the page is read back as a PNG.
  */
+const INPUT_VM_PATH = "input.pdf";
 
-import * as jimp from "jimp";
-import * as mupdf from "mupdf";
-
-import type { JimpInstance } from "./jimp.ts";
-
-export function* loadPages(pdf: mupdf.Document) {
-  for (let i = 0; i < pdf.countPages(); i++) {
-    yield pdf.loadPage(i);
+/**
+ * Count the pages of a PDF using Ghostscript's `pdfpagecount`. Runs with
+ * `-dNODISPLAY` (no rendering) so it is cheap relative to a page render.
+ */
+export async function countPages(pdf: Uint8Array): Promise<number> {
+  const span = perf.span("pdf.countPages_ms");
+  const out: number[] = [];
+  const { exitCode } = await gs({
+    args: [
+      "-q",
+      "-dNODISPLAY",
+      "-dNOSAFER",
+      "-c",
+      `(${INPUT_VM_PATH}) (r) file runpdfbegin pdfpagecount = quit`,
+    ],
+    inputFiles: { [INPUT_VM_PATH]: pdf },
+    onStdout: (charCode) => {
+      if (charCode !== null) out.push(charCode);
+    },
+  });
+  span.stop();
+  if (exitCode !== 0) {
+    throw new Error(`gs countPages failed (exit ${exitCode})`);
   }
+  const text = String.fromCharCode(...out).trim();
+  const n = Number.parseInt(text, 10);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new Error(`gs countPages: unexpected output ${JSON.stringify(text)}`);
+  }
+  return n;
 }
 
-function pixmapToRGBA(pixmap: mupdf.Pixmap): Uint8Array {
-  const width = pixmap.getWidth();
-  const height = pixmap.getHeight();
-  const stride = pixmap.getStride();
-  const hasAlpha = pixmap.getAlpha() !== 0;
-  const samples = pixmap.getPixels();
+/**
+ * Render an inclusive range of (0-based) pages of a PDF to PNG bytes in a single
+ * Ghostscript invocation, returning a map keyed by 0-based page index. Batching
+ * several pages per call amortizes Ghostscript's startup and PDF parsing, which
+ * dominate a single-page render. `alpha` selects the device: `pngalpha` keeps
+ * the page background transparent (so the diff can tell "no content" from
+ * "content" via the alpha channel), while `png16m` renders opaque. Decoding to
+ * RGBA is left to the caller (the diff workers) so it can run off this thread.
+ */
+export async function renderPageRangePng(
+  pdf: Uint8Array,
+  firstIndex: number,
+  lastIndex: number,
+  dpi: number,
+  alpha: boolean,
+): Promise<Map<number, Uint8Array<ArrayBuffer>>> {
+  const device = alpha ? "pngalpha" : "png16m";
+  const first = firstIndex + 1; // Ghostscript page numbers are 1-based.
+  const last = lastIndex + 1;
 
-  if (hasAlpha && stride === width * 4) {
-    return new Uint8Array(samples);
-  }
+  // `%d` in the output pattern is the 1-based index of the page *within this
+  // run* (it restarts at 1 regardless of -dFirstPage), so the k-th output maps
+  // back to absolute page (first + k - 1).
+  const pageCount = last - first + 1;
+  const names: string[] = [];
+  for (let k = 1; k <= pageCount; k++) names.push(`out-${k}.png`);
 
-  const out = new Uint8Array(width * height * 4);
-  const srcBpp = pixmap.getNumberOfComponents() + (hasAlpha ? 1 : 0);
-  for (let y = 0; y < height; y++) {
-    const srcRow = y * stride;
-    const dstRow = y * width * 4;
-    for (let x = 0; x < width; x++) {
-      const s = srcRow + x * srcBpp;
-      const d = dstRow + x * 4;
-      out[d] = samples[s]!;
-      out[d + 1] = samples[s + 1]!;
-      out[d + 2] = samples[s + 2]!;
-      out[d + 3] = hasAlpha ? samples[s + 3]! : 255;
+  const sRender = perf.span("pdf.gsRender_ms");
+  const { exitCode, outputFiles } = await gs({
+    args: [
+      "-dNOPAUSE",
+      "-dBATCH",
+      "-dQUIET",
+      `-dFirstPage=${first}`,
+      `-dLastPage=${last}`,
+      `-sDEVICE=${device}`,
+      `-r${dpi}`,
+      "-dTextAlphaBits=4",
+      "-dGraphicsAlphaBits=4",
+      "-sOutputFile=out-%d.png",
+      INPUT_VM_PATH,
+    ],
+    inputFiles: { [INPUT_VM_PATH]: pdf },
+    outputFilePaths: names,
+  });
+  sRender.stop();
+  if (exitCode !== 0) {
+    throw new Error(`gs render failed (pages ${first}-${last}, exit ${exitCode})`);
+  }
+  const result = new Map<number, Uint8Array<ArrayBuffer>>();
+  for (let k = 1; k <= pageCount; k++) {
+    const png = outputFiles[`out-${k}.png`];
+    if (!png) {
+      throw new Error(`gs render produced no output (page ${first + k - 1})`);
     }
+    result.set(firstIndex + (k - 1), png);
   }
-  return out;
-}
-
-export async function pageToImage(
-  page: mupdf.Page,
-  dpi: number,
-  alpha: boolean,
-) {
-  const zoom = dpi / 72;
-  const pixmap = page.toPixmap(
-    [zoom, 0, 0, zoom, 0, 0],
-    mupdf.ColorSpace.DeviceRGB,
-    alpha,
-  );
-  const width = pixmap.getWidth();
-  const height = pixmap.getHeight();
-  const data = pixmapToRGBA(pixmap);
-  pixmap.destroy();
-  page.destroy();
-  return jimp.Jimp.fromBitmap({ width, height, data }) as JimpInstance;
+  perf.incr("pdf.gsCalls");
+  perf.incr("pdf.pagesRendered", pageCount);
+  return result;
 }

package/src/perf.ts

@@ -0,0 +1,77 @@
+const _enabled = (() => {
+  try {
+    if (
+      typeof process !== "undefined" &&
+      process.env &&
+      process.env.PDFDIFF_PROFILE === "1"
+    ) {
+      return true;
+    }
+  } catch {
+    // process not available (e.g. in some browser worker environments)
+  }
+  const g = globalThis as { __PDFDIFF_PROFILE__?: boolean };
+  return g.__PDFDIFF_PROFILE__ === true;
+})();
+
+export type Counters = Readonly<Record<string, number>>;
+
+export type Span = { stop(): void };
+
+type Perf = {
+  readonly enabled: boolean;
+  span(key: string): Span;
+  incr(key: string, delta?: number): void;
+  setMax(key: string, value: number): void;
+  merge(other: Counters): void;
+  dump(): Counters;
+  reset(): void;
+};
+
+const _counters: Record<string, number> = Object.create(null);
+
+const _NOOP_SPAN: Span = Object.freeze({ stop() {} });
+const _noop = () => {};
+const _emptyDump = (): Counters => Object.freeze({});
+
+const _realPerf: Perf = {
+  enabled: true,
+  span(key) {
+    const t0 = performance.now();
+    return {
+      stop() {
+        _counters[key] = (_counters[key] ?? 0) + (performance.now() - t0);
+      },
+    };
+  },
+  incr(key, delta = 1) {
+    _counters[key] = (_counters[key] ?? 0) + delta;
+  },
+  setMax(key, value) {
+    const cur = _counters[key];
+    if (cur === undefined || value > cur) _counters[key] = value;
+  },
+  merge(other) {
+    for (const k of Object.keys(other)) {
+      _counters[k] = (_counters[k] ?? 0) + other[k]!;
+    }
+  },
+  dump() {
+    return { ..._counters };
+  },
+  reset() {
+    for (const k of Object.keys(_counters)) delete _counters[k];
+  },
+};
+
+const _noopPerf: Perf = {
+  enabled: false,
+  span: () => _NOOP_SPAN,
+  incr: _noop,
+  setMax: _noop,
+  merge: _noop,
+  dump: _emptyDump,
+  reset: _noop,
+};
+
+export const perf: Perf = _enabled ? _realPerf : _noopPerf;

package/src/rgba-color.test.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 assert from "assert";
 import test from "node:test";
 

package/src/rgba-color.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/>.
- */
-
 export type RGBAColor = [number, number, number, number];
 
 export const parseHex = (hex: string) => {

package/src/style.css

@@ -11,9 +11,21 @@
 .diff-table {
   border: 1px solid black;
   border-collapse: collapse;
+  width: 100%;
+  table-layout: fixed;
 }
 
 .diff-table th,
 .diff-table td {
   border: 1px solid black;
 }
+
+.diff-table img {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+body.hide-no-diff .diff-details.no-diff {
+  display: none;
+}

package/src/transferable.ts

@@ -0,0 +1,15 @@
+/**
+ * Slice an ArrayBufferView into a standalone backing buffer of the same kind
+ * (ArrayBuffer in, ArrayBuffer out; SharedArrayBuffer in, SharedArrayBuffer
+ * out). The buffer kind is preserved through the generic parameter.
+ */
+export function sliceBackingBuffer<TArrayBuffer extends ArrayBufferLike>(src: {
+  buffer: TArrayBuffer;
+  byteOffset: number;
+  byteLength: number;
+}): TArrayBuffer {
+  return src.buffer.slice(
+    src.byteOffset,
+    src.byteOffset + src.byteLength,
+  ) as TArrayBuffer;
+}

package/src/worker.ts

@@ -1,38 +1,14 @@
-/*
- * 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 mupdf from "mupdf";
-
-import { drawDifference, type Pallet } from "./diff.ts";
-import {
-  composeLayers,
-  createEmptyImage,
-  type AlignStrategy,
-} from "./image.ts";
+import { decodePng } from "./decode.ts";
+import { type Pallet } from "./diff.ts";
+import { alignSize, createEmptyImage, type AlignStrategy } from "./image.ts";
 import type { JimpInstance } from "./jimp.ts";
-import { pageToImage } from "./pdf.ts";
+import { perf, type Counters } from "./perf.ts";
+import { type RGBAColor } from "./rgba-color.ts";
+import { sliceBackingBuffer } from "./transferable.ts";
+import createWasmModule, { type MainModule } from "./wasm/core.js";
 
 export type InitMessage = {
   type: "init";
-  aBytes: Uint8Array;
-  bBytes: Uint8Array;
-  maskBytes: Uint8Array | null;
-  dpi: number;
-  alpha: boolean;
   pallet: Pallet;
   align: AlignStrategy;
 };
@@ -40,6 +16,11 @@ export type InitMessage = {
 export type PageMessage = {
   type: "page";
   index: number;
+  // PNG bytes rendered on the main thread, or null when the source PDF has no
+  // such page (the diff then treats it as an empty/transparent page).
+  a: ArrayBuffer | null;
+  b: ArrayBuffer | null;
+  mask: ArrayBuffer | null;
 };
 
 export type LoadedMessage = {
@@ -56,9 +37,10 @@ export type PageResultMessage = {
   a: { width: number; height: number; data: ArrayBuffer };
   b: { width: number; height: number; data: ArrayBuffer };
   diff: { width: number; height: number; data: ArrayBuffer };
-  addition: [number, number][];
-  deletion: [number, number][];
-  modification: [number, number][];
+  addition: ArrayBuffer;
+  deletion: ArrayBuffer;
+  modification: ArrayBuffer;
+  perf?: Counters | undefined;
 };
 
 export type ErrorMessage = {
@@ -66,74 +48,102 @@ export type ErrorMessage = {
   message: string;
 };
 
-let pdfA: mupdf.Document;
-let pdfB: mupdf.Document;
-let pdfMask: mupdf.Document;
+type WasmProcessResult = {
+  overlay: Uint8Array<ArrayBuffer>;
+  addition: Int32Array<ArrayBuffer>;
+  deletion: Int32Array<ArrayBuffer>;
+  modification: Int32Array<ArrayBuffer>;
+};
+
 let opts: {
-  dpi: number;
-  alpha: boolean;
   pallet: Pallet;
   align: AlignStrategy;
 };
 
-function toTransferable(
-  src: Buffer | Uint8Array | Uint8ClampedArray | number[],
-): ArrayBuffer {
-  const view =
-    src instanceof Uint8Array || src instanceof Uint8ClampedArray
-      ? src
-      : Uint8Array.from(src as ArrayLike<number>);
-  const out = new ArrayBuffer(view.byteLength);
-  new Uint8Array(out).set(view);
-  return out;
+let wasm: MainModule | null = null;
+async function getWasm(): Promise<MainModule> {
+  if (!wasm) wasm = await createWasmModule();
+  return wasm;
 }
 
-async function processPage(index: number): Promise<PageResultMessage> {
-  const [pageA, pageB, pageMask] = (await Promise.all([
-    index < pdfA.countPages()
-      ? pageToImage(pdfA.loadPage(index), opts.dpi, opts.alpha)
-      : createEmptyImage(1, 1),
-    index < pdfB.countPages()
-      ? pageToImage(pdfB.loadPage(index), opts.dpi, opts.alpha)
-      : createEmptyImage(1, 1),
-    index < pdfMask.countPages()
-      ? pageToImage(pdfMask.loadPage(index), opts.dpi, opts.alpha)
-      : createEmptyImage(1, 1),
-  ])) as [JimpInstance, JimpInstance, JimpInstance];
-
-  const {
-    diff: diffLayer,
-    addition,
-    deletion,
-    modification,
-  } = drawDifference(pageA, pageB, pageMask, opts.pallet, opts.align);
-  const diff = composeLayers(pageA.width, pageA.height, [
-    [pageA, 0.2],
-    [pageB, 0.2],
-    [diffLayer, 1],
-  ]);
+function packColor([r, g, b, a]: RGBAColor): number {
+  return ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
+}
+
+async function processPage(msg: PageMessage): Promise<PageResultMessage> {
+  const index = msg.index;
+  const sLoad = perf.span("worker.decodeAll_ms");
+  const [pageA, pageB, pageMaskOrNull] = (await Promise.all([
+    msg.a !== null ? decodePng(msg.a) : createEmptyImage(1, 1),
+    msg.b !== null ? decodePng(msg.b) : createEmptyImage(1, 1),
+    msg.mask !== null ? decodePng(msg.mask) : Promise.resolve(null),
+  ])) as [JimpInstance, JimpInstance, JimpInstance | null];
+  sLoad.stop();
+
+  const sAlign = perf.span("worker.alignSize_ms");
+  let aAligned: JimpInstance;
+  let bAligned: JimpInstance;
+  let maskAligned: JimpInstance | null;
+  if (pageMaskOrNull !== null) {
+    [aAligned, bAligned, maskAligned] = alignSize(
+      [pageA, pageB, pageMaskOrNull],
+      opts.align,
+    );
+  } else {
+    [aAligned, bAligned] = alignSize([pageA, pageB], opts.align);
+    maskAligned = null;
+  }
+  sAlign.stop();
+
+  const width = aAligned.width;
+  const height = aAligned.height;
+  const aData = aAligned.bitmap.data;
+  const bData = bAligned.bitmap.data;
+  const maskData = maskAligned !== null ? maskAligned.bitmap.data : null;
+
+  const sProcess = perf.span("worker.processPage_ms");
+  const wasmModule = await getWasm();
+  const result = wasmModule.processPage(
+    aData,
+    bData,
+    maskData,
+    width,
+    height,
+    packColor(opts.pallet.addition),
+    packColor(opts.pallet.deletion),
+    packColor(opts.pallet.modification),
+  ) as WasmProcessResult | number;
+  if (typeof result === "number") {
+    throw new Error(`wasm processPage failed: ${result}`);
+  }
+  sProcess.stop();
+
+  const sXfer = perf.span("worker.toTransferable_ms");
+  const aBuf = sliceBackingBuffer(aData);
+  const bBuf = sliceBackingBuffer(bData);
+  const dBuf = sliceBackingBuffer(result.overlay);
+  const addBuf = sliceBackingBuffer(result.addition);
+  const delBuf = sliceBackingBuffer(result.deletion);
+  const modBuf = sliceBackingBuffer(result.modification);
+  sXfer.stop();
+  perf.incr("worker.pages");
+
+  let pagePerf: Counters | undefined;
+  if (perf.enabled) {
+    pagePerf = perf.dump();
+    perf.reset();
+  }
 
   return {
     type: "pageResult",
     index,
-    a: {
-      width: pageA.width,
-      height: pageA.height,
-      data: toTransferable(pageA.bitmap.data),
-    },
-    b: {
-      width: pageB.width,
-      height: pageB.height,
-      data: toTransferable(pageB.bitmap.data),
-    },
-    diff: {
-      width: diff.width,
-      height: diff.height,
-      data: toTransferable(diff.bitmap.data),
-    },
-    addition,
-    deletion,
-    modification,
+    a: { width, height, data: aBuf },
+    b: { width, height, data: bBuf },
+    diff: { width, height, data: dBuf },
+    addition: addBuf,
+    deletion: delBuf,
+    modification: modBuf,
+    perf: pagePerf,
   };
 }
 
@@ -143,26 +153,22 @@ self.addEventListener(
     try {
       const msg = e.data;
       if (msg.type === "init") {
-        pdfA = mupdf.PDFDocument.openDocument(msg.aBytes, "application/pdf");
-        pdfB = mupdf.PDFDocument.openDocument(msg.bBytes, "application/pdf");
-        pdfMask = msg.maskBytes
-          ? mupdf.PDFDocument.openDocument(msg.maskBytes, "application/pdf")
-          : new mupdf.PDFDocument();
         opts = {
-          dpi: msg.dpi,
-          alpha: msg.alpha,
           pallet: msg.pallet,
           align: msg.align,
         };
-        if (pdfA.countPages() > 0) pdfA.loadPage(0).destroy();
+        await getWasm();
         const ready: ReadyMessage = { type: "ready" };
         self.postMessage(ready);
       } else if (msg.type === "page") {
-        const result = await processPage(msg.index);
+        const result = await processPage(msg);
         self.postMessage(result, [
           result.a.data,
           result.b.data,
           result.diff.data,
+          result.addition,
+          result.deletion,
+          result.modification,
         ]);
       }
     } catch (err) {