mixdog 0.9.172 → 0.9.174

package/src/runtime/office/pdf/pdf-draw.mjs

@@ -2,18 +2,11 @@ import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { rgb } from 'pdf-lib';
 import sharp from 'sharp';
+import { pageSizePoints } from '../shared/page-sizes.mjs';
+import { withoutRunt, wrapUnits } from '../shared/line-breaks.mjs';
 
 export const SAVE_OPTIONS = Object.freeze({ useObjectStreams: true, addDefaultPage: false });
 
-const PAGE_SIZES = Object.freeze({
-  a3: [841.89, 1190.55],
-  a4: [595.28, 841.89],
-  a5: [419.53, 595.28],
-  letter: [612, 792],
-  legal: [612, 1008],
-  tabloid: [792, 1224],
-});
-
 export function round2(value) {
   return Number(Number(value).toFixed(2));
 }
@@ -29,20 +22,7 @@ export function color(value = '') {
 }
 
 export function pageSize(properties = {}) {
-  let size;
-  if (Array.isArray(properties.pageSize) && properties.pageSize.length === 2) {
-    size = properties.pageSize.map(Number);
-  } else {
-    const named = String(properties.pageSize || 'a4').toLowerCase();
-    if (!PAGE_SIZES[named]) {
-      throw new Error(
-        `Unknown PDF page size: ${properties.pageSize}; use ${Object.keys(PAGE_SIZES).join(', ')} or [width, height] in points`
-      );
-    }
-    size = [...PAGE_SIZES[named]];
-  }
-  if (!size.every((value) => Number.isFinite(value) && value > 0))
-    throw new Error('PDF pageSize must be two positive numbers in points');
+  const size = pageSizePoints(properties.pageSize || 'a4', 'PDF page size');
   const landscape = String(properties.orientation || '').toLowerCase() === 'landscape';
   return landscape && size[0] < size[1] ? [size[1], size[0]] : size;
 }
@@ -116,22 +96,27 @@ function breakWord(word, font, size, width) {
 
 // Line breaks are honoured, words wrap at spaces, and a run wider than the
 // line (CJK prose, URLs) breaks by character instead of leaving the page.
+// Words that read as one ("10월 14일", "24억 원") wrap together (wrapUnits), and
+// a paragraph never ends on one word alone under a full line (withoutRunt).
 export function wrapText(text, font, size, width) {
   const lines = [];
+  const measure = (value) => font.widthOfTextAtSize(value, size);
   for (const raw of String(text ?? '').split(/\r?\n/)) {
+    const paragraph = [];
     let line = '';
-    for (const word of raw.split(/[ \t]+/).filter(Boolean)) {
+    for (const word of wrapUnits(raw.split(/[ \t]+/).filter(Boolean))) {
       const candidate = line ? `${line} ${word}` : word;
-      if (font.widthOfTextAtSize(candidate, size) <= width) {
+      if (measure(candidate) <= width) {
         line = candidate;
         continue;
       }
-      if (line) lines.push(line);
-      const pieces = font.widthOfTextAtSize(word, size) <= width ? [word] : breakWord(word, font, size, width);
+      if (line) paragraph.push(line);
+      const pieces = measure(word) <= width ? [word] : breakWord(word, font, size, width);
       line = pieces.pop() || '';
-      lines.push(...pieces);
+      paragraph.push(...pieces);
     }
-    lines.push(line);
+    paragraph.push(line);
+    lines.push(...withoutRunt(paragraph, measure, width));
   }
   return lines.length ? lines : [''];
 }

package/src/runtime/office/pdf/pdf-fonts.mjs

@@ -45,24 +45,11 @@ export async function unicodeFontPath(explicit = '') {
 
 /** The characters of `text` the font has no glyph for, in first-seen order. */
 function uncoveredCharacters(font, text, limit = 6) {
-  const face = font?.embedder?.font;
   const missing = [];
   const seen = new Set();
   for (const char of String(text || '')) {
-    const codePoint = char.codePointAt(0);
-    if (codePoint <= 32 || seen.has(char)) continue;
-    const covered =
-      typeof face?.hasGlyphForCodePoint === 'function'
-        ? face.hasGlyphForCodePoint(codePoint)
-        : (() => {
-            try {
-              font.encodeText(char);
-              return true;
-            } catch {
-              return false;
-            }
-          })();
-    if (covered) continue;
+    if (char.codePointAt(0) <= 32 || seen.has(char)) continue;
+    if (hasGlyph(font, char) || standIn(font, char) !== null) continue;
     seen.add(char);
     missing.push(char);
     if (missing.length >= limit) break;
@@ -77,25 +64,104 @@ function describeUncovered(characters = []) {
     .join(', ');
 }
 
-/** True when every character of text has a glyph in the font (standard fonts throw on encode; embedded faces map misses to .notdef, so ask the face). */
-export function fontCovers(font, text) {
-  if (!text) return true;
+// Typographic characters a face often lacks, each with the glyphs that set it
+// the way a typesetter would: the writing guide asks for the minus sign on a
+// negative figure (−6p), and Malgun Gothic and the standard PDF fonts have
+// none, so a Korean report carrying one refused to write at all.
+const TYPOGRAPHIC_STAND_INS = Object.freeze({
+  '\u2212': ['\u2013', '-'],
+  '\u2010': ['-'],
+  '\u2011': ['-'],
+  '\u2007': [' '],
+  '\u2009': [' '],
+  '\u200A': [' '],
+  '\u202F': [' '],
+});
+
+function hasGlyph(font, char) {
   const face = font?.embedder?.font;
-  if (typeof face?.hasGlyphForCodePoint === 'function') {
-    for (const char of String(text)) {
-      const codePoint = char.codePointAt(0);
-      if (codePoint > 32 && !face.hasGlyphForCodePoint(codePoint)) return false;
-    }
-    return true;
-  }
+  if (typeof face?.hasGlyphForCodePoint === 'function') return face.hasGlyphForCodePoint(char.codePointAt(0));
   try {
-    font.encodeText(String(text));
+    font.encodeText(char);
     return true;
   } catch {
     return false;
   }
 }
 
+function standIn(font, char) {
+  return (TYPOGRAPHIC_STAND_INS[char] || []).find((candidate) => hasGlyph(font, candidate)) ?? null;
+}
+
+/**
+ * The font with its typographic stand-ins applied wherever it encodes or measures text, so every page, stamp,
+ * and field drawn with it sets a minus sign it lacks as an en dash instead of a missing glyph. A face that
+ * carries every one of those characters is returned unchanged.
+ */
+function withStandIns(font) {
+  const substitutes = new Map();
+  for (const char of Object.keys(TYPOGRAPHIC_STAND_INS)) {
+    if (hasGlyph(font, char)) continue;
+    const replacement = standIn(font, char);
+    if (replacement !== null) substitutes.set(char, replacement);
+  }
+  if (!substitutes.size) return font;
+  const pattern = new RegExp(`[${[...substitutes.keys()].join('')}]`, 'gu');
+  const set = (text) => String(text ?? '').replace(pattern, (char) => substitutes.get(char));
+  return Object.create(font, {
+    encodeText: { value: (text) => font.encodeText(set(text)) },
+    widthOfTextAtSize: { value: (text, size) => font.widthOfTextAtSize(set(text), size) },
+  });
+}
+
+/** True when every character of text has a glyph in the font, or a typographic stand-in it has (standard fonts throw on encode; embedded faces map misses to .notdef, so ask the face). */
+export function fontCovers(font, text) {
+  if (!text) return true;
+  const seen = new Set();
+  for (const char of String(text)) {
+    if (char.codePointAt(0) <= 32 || seen.has(char)) continue;
+    seen.add(char);
+    if (!hasGlyph(font, char) && standIn(font, char) === null) return false;
+  }
+  return true;
+}
+
+// The bold face that ships beside a regular one: malgun.ttf / malgunbd.ttf, segoeui.ttf / segoeuib.ttf,
+// NanumGothic.ttf / NanumGothicBold.ttf, DejaVuSans.ttf / DejaVuSans-Bold.ttf, a -Regular file and its -Bold.
+function boldCompanions(path) {
+  const file = String(path || '');
+  if (!/\.(ttf|otf)$/i.test(file)) return [];
+  return [
+    ...new Set(
+      [
+        file.replace(/-Regular(\.\w+)$/i, '-Bold$1'),
+        file.replace(/Regular(\.\w+)$/i, 'Bold$1'),
+        file.replace(/(\.\w+)$/, 'bd$1'),
+        file.replace(/(\.\w+)$/, 'b$1'),
+        file.replace(/(\.\w+)$/, '-Bold$1'),
+        file.replace(/(\.\w+)$/, 'Bold$1'),
+      ].filter((candidate) => candidate !== file)
+    ),
+  ];
+}
+
+/**
+ * The bold face for headings, table headers, labels, and figures: Helvetica-Bold beside Helvetica, else the
+ * installed bold companion of the embedded face when it covers the same text. Without one the regular face
+ * stands in, so a document without a bold file still writes — only without the weight.
+ */
+export async function embedBoldFont(document, { font, fontPath = '', text = '' } = {}) {
+  if (!fontPath) return withStandIns(await document.embedFont(StandardFonts.HelveticaBold));
+  for (const candidate of boldCompanions(fontPath)) {
+    try {
+      await access(candidate);
+      const bold = await document.embedFont(await readFile(candidate), { subset: true });
+      if (fontCovers(bold, text)) return withStandIns(bold);
+    } catch {}
+  }
+  return font;
+}
+
 /**
  * Embed the font a document needs for `text`: an explicit fontPath always wins;
  * otherwise Helvetica when it can encode the text, else the first installed
@@ -108,7 +174,7 @@ export async function embedDocumentFont(
 ) {
   if (!fontPath) {
     const builtin = await document.embedFont(standard);
-    if (fontCovers(builtin, text)) return { font: builtin, fontPath: '', embedded: false };
+    if (fontCovers(builtin, text)) return { font: withStandIns(builtin), fontPath: '', embedded: false };
   }
   const candidates = await unicodeFontCandidates(fontPath);
   if (fontPath && !candidates.length) throw new Error(`PDF font file was not found: ${fontPath}`);
@@ -125,7 +191,7 @@ export async function embedDocumentFont(
       if (fontPath) throw new Error(`PDF font ${candidate} could not be embedded: ${error?.message || error}`);
       continue;
     }
-    if (fontCovers(font, text)) return { font, fontPath: candidate, embedded: true };
+    if (fontCovers(font, text)) return { font: withStandIns(font), fontPath: candidate, embedded: true };
     if (fontPath) {
       const missing = describeUncovered(uncoveredCharacters(font, text));
       throw new Error(`Font ${candidate} has no glyph for ${missing || 'part of the text'}; ${PDF_FONT_HINT}`);

package/src/runtime/office/pdf/pdf-forms.mjs

@@ -1,4 +1,4 @@
-import { PDFRawStream, decodePDFRawStream } from 'pdf-lib';
+import { PDFHexString, PDFName, PDFRawStream, decodePDFRawStream } from 'pdf-lib';
 import { color } from './pdf-draw.mjs';
 
 export function fieldWidgets(field, document) {
@@ -20,6 +20,26 @@ export function fieldWidgets(field, document) {
   }
 }
 
+// A box a person cannot hit or read: 8 pt squares for marks, 24 x 12 pt for anything typed. The comparison carries a
+// hundredth of a point: a form's rectangle stored as 11.999 pt is the 12 pt box its author drew, and the W-9's
+// 284-point line was reported as too small to type in.
+export function minimumFieldSize(type) {
+  return ['checkbox', 'radio'].includes(type) ? [8 - 0.01, 8 - 0.01] : [24 - 0.01, 12 - 0.01];
+}
+
+// The words a form gives a field for the person filling it: the tooltip (/TU) a reader shows on hover — "Line 1
+// Name of entity/individual" behind the IRS W-9's "topmostSubform[0].Page1[0].f1_01[0]". Without it a filler had only
+// the internal name to go on and had to guess which box took the name.
+function fieldLabel(field) {
+  try {
+    const tooltip = field.acroField.dict.lookup(PDFName.of('TU'));
+    const text = tooltip?.decodeText?.().replace(/\s+/g, ' ').trim();
+    return text || '';
+  } catch {
+    return '';
+  }
+}
+
 export function rectanglesOverlap(left, right) {
   return (
     left.x < right.x + right.width &&
@@ -102,15 +122,13 @@ export function lintPdfFormFields(fields = [], pages = []) {
         message: `Form field is outside page ${field.page}.`,
       });
     } else {
-      // A box a person cannot hit or read: 8 pt squares for marks, 24 x 12 pt for anything typed.
-      const mark = ['checkbox', 'radio'].includes(field.type);
-      const [minWidth, minHeight] = mark ? [8, 8] : [24, 12];
+      const [minWidth, minHeight] = minimumFieldSize(field.type);
       if (field.width < minWidth || field.height < minHeight) {
         issues.push({
           severity: 'warning',
           code: 'field_too_small',
           path: `/field[${field.index}]`,
-          message: `Form field ${field.name || field.index} is ${field.width} x ${field.height} pt; a ${field.type} field needs at least ${minWidth} x ${minHeight}.`,
+          message: `Form field ${field.name || field.index} is ${field.width} x ${field.height} pt; a ${field.type} field needs at least ${Math.round(minWidth)} x ${Math.round(minHeight)}.`,
         });
       }
     }
@@ -135,13 +153,21 @@ export function lintPdfFormFields(fields = [], pages = []) {
   };
 }
 
+// Two lines of 11 pt body text with the box's insets: the height from which a text box holds a paragraph.
+const MULTILINE_MIN_HEIGHT = 40;
+
 /**
  * Add one field. `font` is the face its appearance is drawn with: pdf-lib
  * paints a widget the moment it is added, so a dropdown or list whose
  * options are Korean needs the embedded face here, not only at save time.
  */
 export async function addFormField(document, field, font = null) {
-  const page = document.getPage(Math.max(1, Number(field.page) || 1) - 1);
+  // Named as every page operation names it, rather than pdf-lib's "`index` must be at most …".
+  const number = Math.max(1, Number(field.page) || 1);
+  if (!Number.isInteger(number) || number > document.getPageCount()) {
+    throw new Error(`PDF page out of range: ${field.page}`);
+  }
+  const page = document.getPage(number - 1);
   const form = document.getForm();
   const name = String(field.name);
   const options = {
@@ -187,16 +213,25 @@ export async function addFormField(document, field, font = null) {
   } else {
     control = form.createTextField(name);
     control.addToPage(page, options);
-    if (field.multiline) control.enableMultiline();
+    // A box tall enough for two lines of body text is a box for a paragraph (a reason, a comment). Left single-line,
+    // pdf-lib's auto size set the answer at the box's height — 35 pt in a 60 pt box — and cut it at the right edge.
+    // An explicit multiline: false keeps one line.
+    const multiline = field.multiline ?? options.height >= MULTILINE_MIN_HEIGHT;
+    if (multiline) control.enableMultiline();
     if (Number(field.maxLength) > 0) control.setMaxLength(Math.floor(Number(field.maxLength)));
     // pdf-lib's auto size fits a multiline value to the box height and drops
     // the lines that do not fit; a fixed body size keeps every line.
     if (Number(field.fontSize) > 0) control.setFontSize(Number(field.fontSize));
-    else if (field.multiline) control.setFontSize(11);
+    else if (multiline) control.setFontSize(11);
     if (field.value != null) control.setText(String(field.value));
   }
   if (field.required) control.enableRequired();
   if (field.readOnly) control.enableReadOnly();
+  // The caption is also the field's tooltip (/TU): what a screen reader announces and what a later filler reads as
+  // the field's label, instead of its internal name.
+  if (String(field.label ?? '').trim()) {
+    control.acroField.dict.set(PDFName.of('TU'), PDFHexString.fromText(String(field.label).trim()));
+  }
 }
 
 /** Every string a field carries, so the writer can pick a font that covers it. */
@@ -268,10 +303,12 @@ export function describeFormField(field, document, index) {
       if (maxLength != null) flags.maxLength = maxLength;
     } catch {}
   }
+  const label = fieldLabel(field);
   return {
     path: `/field[${index + 1}]`,
     index: index + 1,
     name: field.getName(),
+    ...(label ? { label } : {}),
     type: kind,
     value: fieldValue(field, kind),
     ...(options ? { options } : {}),

package/src/runtime/office/pdf/pdf-ocr.mjs

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module';
 import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { PDFDocument, rgb } from 'pdf-lib';
+import { SAVE_OPTIONS } from './pdf-draw.mjs';
 import { embedDocumentFont, fontCovers } from './pdf-fonts.mjs';
 import { renderPdfPages } from './pdf-render.mjs';
 import { selectedPages } from './pdf-document.mjs';
@@ -63,15 +64,6 @@ export function parseOcrTsv(value) {
     .filter((word) => word.text.trim() && word.width > 0 && word.height > 0);
 }
 
-// One text line per recognized row, with the words that belong to it.
-//
-// A word box is where ink sits, not where a word begins and ends: Korean and
-// CJK come back split at syllable boundaries ("출" "고" "율" for 출고율) while a
-// real word break can measure a single pixel. Geometry therefore cannot rebuild
-// the line, but the engine's own line text can — it is the reading the OCR
-// result already reports. The rows and the text come back in the same order, so
-// a line takes that text when it carries exactly the same characters, and falls
-// back to its word boxes when it does not.
 // The word boxes of each OCR line, keyed by the engine's page/block/paragraph/line ids.
 function ocrLineGroups(rows, at) {
   const groups = new Map();
@@ -137,6 +129,15 @@ function ocrLine(group, spokenReading) {
   };
 }
 
+// One text line per recognized row, with the words that belong to it.
+//
+// A word box is where ink sits, not where a word begins and ends: Korean and
+// CJK come back split at syllable boundaries ("출" "고" "율" for 출고율) while a
+// real word break can measure a single pixel. Geometry therefore cannot rebuild
+// the line, but the engine's own line text can — it is the reading the OCR
+// result already reports. The rows and the text come back in the same order, so
+// a line takes that text when it carries exactly the same characters, and falls
+// back to its word boxes when it does not.
 export function ocrTextLines(value, plainText = '') {
   const { at, rows } = ocrTsvRows(value);
   if (['line_num', 'left', 'text'].some((name) => at[name] === undefined)) return [];
@@ -172,12 +173,17 @@ export function parseOcrBlocks(blocks) {
   return words;
 }
 
+// Where each language's recognition data is downloaded to and kept.
+function ocrCachePath(dataDir) {
+  return join(dataDir, 'office', 'ocr', 'languages');
+}
+
 // Whether a scanned page can be read here and now. The engine ships with the
 // runtime, but each language's data is downloaded on first use and kept in the
 // cache: promising OCR of a Korean scan on a machine with no network and no
 // cached kor data fails in the middle of the task instead of before it.
 export async function pdfOcrReadiness(dataDir) {
-  const cachePath = join(dataDir, 'office', 'ocr', 'languages');
+  const cachePath = ocrCachePath(dataDir);
   let available = true;
   try {
     require.resolve('tesseract.js');
@@ -283,7 +289,7 @@ async function createOcrWorker(operation, dataDir) {
   const languages = Array.isArray(operation.languages)
     ? operation.languages.map(String).join('+')
     : String(operation.languages || 'eng+kor');
-  const cachePath = join(dataDir, 'office', 'ocr', 'languages');
+  const cachePath = ocrCachePath(dataDir);
   await mkdir(cachePath, { recursive: true });
   const tesseract = require('tesseract.js');
   const worker = await tesseract.createWorker(languages, tesseract.OEM.LSTM_ONLY, {
@@ -337,7 +343,7 @@ export async function ocrPdf(path, operation, { dataDir, signal = null } = {}) {
     const minConfidence = Number(operation.minConfidence ?? 40);
     for (const entry of recognizedPages) placeRecognizedText(document, entry, font, minConfidence, tally);
     if (tally.wordCount > 0) {
-      await writeFile(path, await document.save({ useObjectStreams: true, addDefaultPage: false }));
+      await writeFile(path, await document.save(SAVE_OPTIONS));
     }
     return ocrResult(operation, { pages, languages, text, tally, fontPath, embedded });
   } finally {

package/src/runtime/office/pdf/pdf-render.mjs

@@ -1,14 +1,9 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { isMainThread, parentPort, Worker, workerData } from 'node:worker_threads';
-import { DOMMatrix, ImageData, Path2D, createCanvas, loadImage } from '@napi-rs/canvas';
+import { createCanvas, loadImage } from '@napi-rs/canvas';
 import { pdfjsStandardFontDataUrl, resolvedPdfJs } from '../../attachments/pdfjs-runtime.mjs';
-
-function installPdfJsCanvasGlobals() {
-  globalThis.DOMMatrix ??= DOMMatrix;
-  globalThis.ImageData ??= ImageData;
-  globalThis.Path2D ??= Path2D;
-}
+import { installPdfGlobals } from './pdf-document.mjs';
 
 const PAGE_NUMBER_PATTERN = /^\s*(?:(?:page\s*)?\d+\s*(?:of|\/)\s*\d+|페이지\s*\d+|\d+\s*페이지)\s*$/i;
 
@@ -68,22 +63,29 @@ function requestedPages(pageCount, pages) {
 const PDF_RENDER_WORKER_KIND = 'mixdog-office-pdf-render';
 const PDF_RENDER_PAGE_WORKER_KIND = 'mixdog-office-pdf-render-page';
 
-async function renderPdfPageDirect(path, pageNumber, targetWidth, minimumScale = 0.25) {
-  installPdfJsCanvasGlobals();
-  const { getDocument, Util, VerbosityLevel } = await resolvedPdfJs();
-  const loadingTask = getDocument({
-    data: new Uint8Array(await readFile(path)),
+// One loading contract for every rasterizing read: the bundled standard fonts,
+// no worker thread of its own, and errors only.
+function pdfLoadingTask(getDocument, VerbosityLevel, data) {
+  return getDocument({
+    data,
     disableWorker: true,
     useSystemFonts: false,
     standardFontDataUrl: pdfjsStandardFontDataUrl(),
     isEvalSupported: false,
     verbosity: VerbosityLevel.ERRORS,
   });
+}
+
+// maximumScale: a preview stops at two pixels a point; a picture placed in a document (a Word chart) asks for three.
+async function renderPdfPageDirect(path, pageNumber, targetWidth, minimumScale = 0.25, maximumScale = 2) {
+  installPdfGlobals();
+  const { getDocument, Util, VerbosityLevel } = await resolvedPdfJs();
+  const loadingTask = pdfLoadingTask(getDocument, VerbosityLevel, new Uint8Array(await readFile(path)));
   try {
     const document = await loadingTask.promise;
     const page = await document.getPage(pageNumber);
     const base = page.getViewport({ scale: 1 });
-    const scale = Math.min(2, Math.max(minimumScale, Number(targetWidth || 1400) / base.width));
+    const scale = Math.min(maximumScale, Math.max(minimumScale, Number(targetWidth || 1400) / base.width));
     const viewport = page.getViewport({ scale });
     const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
     const context = canvas.getContext('2d');
@@ -145,20 +147,74 @@ async function runPdfRenderWorker(data, signal = null) {
   });
 }
 
-async function renderPdfPagesDirect(path, { pages = null, maxWidth = 1400, signal = null } = {}) {
+// Many pages are reviewed as contact sheets: one labelled grid image per group
+// of pages, written next to the PDF.
+async function writeContactSheet(group, width, imagePath, renderPage) {
+  const columns = group.length <= 2 ? 1 : Math.max(2, Math.ceil(Math.sqrt(group.length * 0.75)));
+  const rows = Math.ceil(group.length / columns);
+  const gap = 12;
+  const labelHeight = 24;
+  const cellWidth = Math.max(64, Math.floor((width - (columns + 1) * gap) / columns));
+  const thumbnails = [];
+  for (const pageNumber of group) {
+    const rendered = await renderPage(pageNumber, cellWidth, 0.05);
+    thumbnails.push({
+      page: pageNumber,
+      image: await loadImage(rendered.data),
+      data: rendered.data,
+    });
+  }
+  const cellHeight = Math.max(...thumbnails.map(({ image }) => image.height));
+  const sheet = createCanvas(width, gap + rows * (labelHeight + cellHeight + gap));
+  const context = sheet.getContext('2d');
+  context.fillStyle = 'rgb(238,240,244)';
+  context.fillRect(0, 0, sheet.width, sheet.height);
+  context.font = '16px sans-serif';
+  context.textBaseline = 'middle';
+  for (let index = 0; index < thumbnails.length; index += 1) {
+    const { page: pageNumber, image } = thumbnails[index];
+    const column = index % columns;
+    const row = Math.floor(index / columns);
+    const x = gap + column * (cellWidth + gap);
+    const y = gap + row * (labelHeight + cellHeight + gap);
+    context.fillStyle = 'rgb(45,50,60)';
+    context.fillText(`Page ${pageNumber}`, x, y + labelHeight / 2);
+    context.fillStyle = 'rgb(255,255,255)';
+    context.fillRect(x, y + labelHeight, cellWidth, cellHeight);
+    context.drawImage(image, x, y + labelHeight);
+    context.strokeStyle = 'rgb(180,185,195)';
+    context.strokeRect(x, y + labelHeight, image.width, image.height);
+  }
+  const data = sheet.toBuffer('image/png');
+  await writeFile(imagePath, data);
+  return {
+    page: group[0],
+    pages: group,
+    path: imagePath,
+    width: sheet.width,
+    height: sheet.height,
+    mimeType: 'image/png',
+    data: data.toString('base64'),
+    // The pages the sheet was composed from: the render review reads these,
+    // never the sheet (its grey field, labels, and borders are not the deck).
+    // Stripped from the model-facing result by the render action.
+    pageImages: thumbnails.map(({ page: pageNumber, image, data: pageData }) => ({
+      page: pageNumber,
+      width: image.width,
+      height: image.height,
+      mimeType: 'image/png',
+      data: pageData.toString('base64'),
+    })),
+  };
+}
+
+async function renderPdfPagesDirect(path, { pages = null, maxWidth = 1400, maximumScale = 2, signal = null } = {}) {
   if (signal?.aborted) throw new Error('PDF rendering was cancelled');
-  installPdfJsCanvasGlobals();
+  installPdfGlobals();
   const { getDocument, VerbosityLevel } = await resolvedPdfJs();
   const pdfData = await readFile(path);
   const openDocument = async () => {
-    const loadingTask = getDocument({
-      data: Uint8Array.from(pdfData),
-      disableWorker: true,
-      useSystemFonts: false,
-      standardFontDataUrl: pdfjsStandardFontDataUrl(),
-      isEvalSupported: false,
-      verbosity: VerbosityLevel.ERRORS,
-    });
+    const loadingTask = pdfLoadingTask(getDocument, VerbosityLevel, Uint8Array.from(pdfData));
     try {
       return { loadingTask, document: await loadingTask.promise };
     } catch (error) {
@@ -182,6 +238,7 @@ async function renderPdfPagesDirect(path, { pages = null, maxWidth = 1400, signa
           pageNumber,
           targetWidth,
           minimumScale,
+          maximumScale,
         },
         signal
       );
@@ -210,65 +267,8 @@ async function renderPdfPagesDirect(path, { pages = null, maxWidth = 1400, signa
       const pagesPerSheet = Math.ceil(selected.length / 12);
       for (let offset = 0; offset < selected.length; offset += pagesPerSheet) {
         const group = selected.slice(offset, offset + pagesPerSheet);
-        const columns = group.length <= 2 ? 1 : Math.max(2, Math.ceil(Math.sqrt(group.length * 0.75)));
-        const rows = Math.ceil(group.length / columns);
-        const gap = 12;
-        const labelHeight = 24;
-        const cellWidth = Math.max(64, Math.floor((width - (columns + 1) * gap) / columns));
-        const thumbnails = [];
-        for (const pageNumber of group) {
-          const rendered = await renderPage(pageNumber, cellWidth, 0.05);
-          thumbnails.push({
-            page: pageNumber,
-            image: await loadImage(rendered.data),
-            data: rendered.data,
-          });
-        }
-        const cellHeight = Math.max(...thumbnails.map(({ image }) => image.height));
-        const sheet = createCanvas(width, gap + rows * (labelHeight + cellHeight + gap));
-        const context = sheet.getContext('2d');
-        context.fillStyle = 'rgb(238,240,244)';
-        context.fillRect(0, 0, sheet.width, sheet.height);
-        context.font = '16px sans-serif';
-        context.textBaseline = 'middle';
-        for (let index = 0; index < thumbnails.length; index += 1) {
-          const { page: pageNumber, image } = thumbnails[index];
-          const column = index % columns;
-          const row = Math.floor(index / columns);
-          const x = gap + column * (cellWidth + gap);
-          const y = gap + row * (labelHeight + cellHeight + gap);
-          context.fillStyle = 'rgb(45,50,60)';
-          context.fillText(`Page ${pageNumber}`, x, y + labelHeight / 2);
-          context.fillStyle = 'rgb(255,255,255)';
-          context.fillRect(x, y + labelHeight, cellWidth, cellHeight);
-          context.drawImage(image, x, y + labelHeight);
-          context.strokeStyle = 'rgb(180,185,195)';
-          context.strokeRect(x, y + labelHeight, image.width, image.height);
-        }
-        const data = sheet.toBuffer('image/png');
-        const first = group[0];
-        const last = group.at(-1);
-        const imagePath = join(dirname(path), `${stem}-pages-${first}-${last}.png`);
-        await writeFile(imagePath, data);
-        output.push({
-          page: first,
-          pages: group,
-          path: imagePath,
-          width: sheet.width,
-          height: sheet.height,
-          mimeType: 'image/png',
-          data: data.toString('base64'),
-          // The pages the sheet was composed from: the render review reads these,
-          // never the sheet (its grey field, labels, and borders are not the deck).
-          // Stripped from the model-facing result by the render action.
-          pageImages: thumbnails.map(({ page: pageNumber, image, data: pageData }) => ({
-            page: pageNumber,
-            width: image.width,
-            height: image.height,
-            mimeType: 'image/png',
-            data: pageData.toString('base64'),
-          })),
-        });
+        const imagePath = join(dirname(path), `${stem}-pages-${group[0]}-${group.at(-1)}.png`);
+        output.push(await writeContactSheet(group, width, imagePath, renderPage));
       }
     }
     const reviewedPages = output.flatMap((image) => image.pages || [image.page]);
@@ -304,6 +304,7 @@ export async function renderPdfPages(path, options = {}) {
       options: {
         pages: options.pages ?? null,
         maxWidth: options.maxWidth ?? 1400,
+        maximumScale: options.maximumScale ?? 2,
       },
     },
     signal
@@ -318,7 +319,8 @@ if (!isMainThread && [PDF_RENDER_WORKER_KIND, PDF_RENDER_PAGE_WORKER_KIND].inclu
             workerData.path,
             workerData.pageNumber,
             workerData.targetWidth,
-            workerData.minimumScale
+            workerData.minimumScale,
+            workerData.maximumScale
           )
         : await renderPdfPagesDirect(workerData.path, workerData.options);
     parentPort?.postMessage({ ok: true, value });