@doccloak/core 0.13.0 → 0.15.0

package/dist/pdf/read.js

@@ -9,6 +9,7 @@
 import { DEFAULT_MAX_BYTES, extractPdf } from "./extract.js";
 import { UnsupportedDocumentError } from "../dom/errors.js";
 import { openWithOracle } from "./oracle.js";
+import { findTextWithoutOcr, ocrGlyphBoxes } from "./coverage.js";
 export async function toPdfBytes(input) {
     if (input instanceof Uint8Array)
         return input;
@@ -24,6 +25,8 @@ export async function toPdfBytes(input) {
         reader.readAsArrayBuffer(input);
     });
 }
+/** Resolution of the missing-OCR check: letters stay several pixels tall, a page stays cheap. */
+const COVERAGE_DPI = 100;
 export async function readPdf(input, options = {}) {
     const bytes = await toPdfBytes(input);
     // Size cap before anything parses the file (pdf.js would otherwise read all of it first).
@@ -33,13 +36,88 @@ export async function readPdf(input, options = {}) {
     }
     const oracle = await openWithOracle(bytes, options.assets, options.password);
     try {
-        const res = await extractPdf(bytes, {
-            maxBytes: options.maxBytes,
-            maxPages: options.maxPages,
-            maxGlyphs: options.maxGlyphs,
-            password: options.password,
-            oracle,
-        });
+        const extractOptions = { maxBytes: options.maxBytes, maxPages: options.maxPages, maxGlyphs: options.maxGlyphs, password: options.password, oracle };
+        let res = await extractPdf(bytes, extractOptions);
+        const missing = new Map();
+        const extraOcr = [];
+        const ocrImagePages = options.ocrImagePages !== false && !!options.recognizeText;
+        const checkCoverage = options.checkOcrCoverage !== false;
+        // Each page by what it holds: a picture without any text layer is read whole; a scan with an OCR
+        // layer and a text page with images are checked for text their layer does not have, and that is
+        // read. Words a layer already has are never added twice.
+        const wholePages = res.pages.filter((p) => p.imageOnly && !p.ocrText && ocrImagePages).map((p) => p.index);
+        const checked = res.pages.filter((p) => checkCoverage && (p.ocrText || (p.hasImages && !p.imageOnly))).map((p) => p.index);
+        const total = wholePages.length + (options.recognizeText ? checked.length : 0);
+        let done = 0;
+        const progress = () => options.onOcrProgress?.(done, total);
+        if (total > 0)
+            progress();
+        const wholeRead = new Map();
+        for (const index of wholePages) {
+            try {
+                const read = await readText(oracle, res.runs, index, null, 0, options);
+                const words = read ? read.lines.reduce((n, l) => n + l.length, 0) : 0;
+                wholeRead.set(index, words);
+                if (read && words > 0)
+                    extraOcr.push({ ...read, whole: true });
+            }
+            catch {
+                // No canvas in this host, or the host OCR failed: the page stays a picture the card lists.
+            }
+            done++;
+            progress();
+        }
+        for (const index of checked) {
+            const page = res.pages[index];
+            try {
+                const rendered = await oracle.render(index, COVERAGE_DPI / 72, options.canvasFactory);
+                // On a scan the OCR layer is the text; on a text page every glyph of its layer is.
+                const allText = !page.ocrText;
+                const { boxes, emPx } = ocrGlyphBoxes(res.runs, index, rendered.transform, allText);
+                const lines = findTextWithoutOcr(rendered.canvas.getImageData(), rendered.widthPx, rendered.heightPx, boxes, emPx);
+                if (lines.length > 0) {
+                    missing.set(index, lines.length);
+                    if (options.recognizeText) {
+                        const read = await readText(oracle, res.runs, index, lines, emPx, options, allText);
+                        if (read && read.lines.length > 0)
+                            extraOcr.push(read);
+                    }
+                }
+            }
+            catch {
+                // No canvas in this host (Node without a factory), or the host OCR failed: the page keeps
+                // what its own layer has.
+            }
+            if (options.recognizeText) {
+                done++;
+                progress();
+            }
+        }
+        // Read text joins the pages' text: extract again with it, as the writer will.
+        if (extraOcr.length > 0)
+            res = await extractPdf(bytes, { ...extractOptions, extraOcr });
+        for (const [index, words] of wholeRead)
+            res.pages[index].ocrWholePage = words;
+        for (const [index, count] of missing) {
+            const page = res.pages[index];
+            page.ocrMissingLines = count;
+            const where = page.ocrText ? 'the picture shows text its OCR layer does not have' : 'an image on the page shows text its text layer does not have';
+            res.warnings.push(page.ocrReadWords
+                ? `page ${index + 1}: ${where} (${count} lines, for example a table); DocCloak read it with its own OCR (${page.ocrReadWords} words), check it before sharing`
+                : `page ${index + 1}: ${where} (${count} lines, for example a table or a stamp); it cannot be found or redacted, check it before sharing`);
+        }
+        for (const [index, words] of wholeRead) {
+            if (words > 0)
+                res.warnings.push(`page ${index + 1}: no text layer; DocCloak read the page with its own OCR (${words} words), check it before sharing`);
+        }
+        // With the host's OCR, the images of the text pages checked above were scanned for text.
+        if (options.recognizeText) {
+            const scanned = new Set(checked);
+            res.warnings = res.warnings.filter((w) => {
+                const m = w.match(/^page (\d+): contains images; text inside images is not scanned$/);
+                return !(m && scanned.has(Number(m[1]) - 1));
+            });
+        }
         return {
             plainText: res.plainText,
             pageCount: res.pages.length,
@@ -53,12 +131,136 @@ export async function readPdf(input, options = {}) {
             bytes,
             assets: options.assets,
             password: options.password,
+            ...(extraOcr.length > 0 ? { extraOcr } : {}),
         };
     }
     finally {
         await oracle.close();
     }
 }
+/** Resolution DocCloak's own OCR reads missing text at. */
+const READ_DPI = 300;
+/** Two readings of a word are the same word at this share of common letters (in order). */
+const SAME_WORD = 0.6;
+/** Letters and digits of `s`, lower-cased, without diacritics. */
+function letters(s) {
+    return s.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+}
+/** Longest common subsequence of `a` and `b` over the longer length (0..1). */
+function similarity(a, b) {
+    if (!a || !b)
+        return a === b ? 1 : 0;
+    const row = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = 0;
+        for (let j = 1; j <= b.length; j++) {
+            const keep = row[j];
+            row[j] = a[i - 1] === b[j - 1] ? prev + 1 : Math.max(row[j], row[j - 1]);
+            prev = keep;
+        }
+    }
+    return row[b.length] / Math.max(a.length, b.length);
+}
+/** Words the OCR is less sure of than this (0..100) do not count towards a page read whole being text: on a picture without text they are noise. */
+const MIN_WHOLE_PAGE_CONFIDENCE = 30;
+/** A page read whole counts as text when it gives at least this many such words of two or more letters or digits. */
+const MIN_WHOLE_PAGE_WORDS = 3;
+/**
+ * Read text a page's layer does not have with the host's OCR: render the page at READ_DPI, hand
+ * over the region around the missing `lines` (grown by an em) or, with `lines` null, the whole page
+ * (a picture without any text layer); keep the words that do not lie under the layer's own glyphs
+ * (its OCR glyphs, or with `allText` every glyph of a text page), and turn them into glyphs in user
+ * space (letters at the boxes the OCR gives, origins on the line's baseline).
+ */
+async function readText(oracle, runs, pageIndex, lines, emPx, options, allText = false) {
+    const k = READ_DPI / COVERAGE_DPI;
+    const page = await oracle.render(pageIndex, READ_DPI / 72, options.canvasFactory);
+    // The region holds the missing lines and, above and below, the rows next to them: a row whose
+    // only OCR text is junk looks covered, so it is never reported missing itself.
+    const growX = emPx * k;
+    const growY = 2.5 * emPx * k;
+    const region = lines === null ? { x0: 0, y0: 0, x1: page.widthPx, y1: page.heightPx } : {
+        x0: Math.max(0, Math.floor(Math.min(...lines.map((l) => l.x0)) * k - growX)),
+        y0: Math.max(0, Math.floor(Math.min(...lines.map((l) => l.y0)) * k - growY)),
+        x1: Math.min(page.widthPx, Math.ceil(Math.max(...lines.map((l) => l.x1)) * k + growX)),
+        y1: Math.min(page.heightPx, Math.ceil(Math.max(...lines.map((l) => l.y1)) * k + growY)),
+    };
+    const read = await options.recognizeText(page.canvas.canvas, region, READ_DPI);
+    if (lines === null) {
+        // Confidence decides whether the picture holds text; once it does, every word read is kept:
+        // Tesseract is least sure of elided words ("d'avril", "d'actions"), and a word left out can be
+        // neither found nor covered.
+        const sure = read.reduce((n, l) => n + l.words.filter((w) => (w.confidence ?? 100) >= MIN_WHOLE_PAGE_CONFIDENCE && letters(w.text).length >= 2).length, 0);
+        if (sure < MIN_WHOLE_PAGE_WORDS)
+            return null;
+    }
+    const { boxes, chars } = ocrGlyphBoxes(runs, pageIndex, page.transform, allText);
+    // A word the layer already has (its glyphs lie under the word and spell about the same) is not
+    // added twice; where the layer holds junk over the word ("[miesiąc | opowiezany ema"), the word
+    // DocCloak read is added.
+    const alreadyThere = (b, text) => {
+        const area = Math.max(1, (b.x1 - b.x0) * (b.y1 - b.y0));
+        let under = 0;
+        const spelled = [];
+        boxes.forEach((o, i) => {
+            const w = Math.min(b.x1, o.x1) - Math.max(b.x0, o.x0);
+            const h = Math.min(b.y1, o.y1) - Math.max(b.y0, o.y0);
+            if (w > 0 && h > 0) {
+                under += w * h;
+                const cx = (o.x0 + o.x1) / 2;
+                if (cx >= b.x0 && cx <= b.x1)
+                    spelled.push([o.x0, chars[i]]);
+            }
+        });
+        if (under / area <= 0.5)
+            return false;
+        const layer = spelled.sort((p, q) => p[0] - q[0]).map((x) => x[1]).join('');
+        return similarity(letters(text), letters(layer)) >= SAME_WORD;
+    };
+    // Pixels to user space: the inverse of the render transform [a b c d e f].
+    const [a, b, c, d, e, f] = page.transform;
+    const det = a * d - b * c;
+    const toUser = (px, py) => [(d * (px - e) - c * (py - f)) / det, (a * (py - f) - b * (px - e)) / det];
+    const unit = (v) => { const l = Math.hypot(v[0], v[1]) || 1; return [v[0] / l, v[1] / l]; };
+    const [ox, oy] = toUser(0, 0);
+    const [rx, ry] = toUser(1, 0);
+    const [ux, uy] = toUser(0, -1);
+    const dir = unit([rx - ox, ry - oy]);
+    const up = unit([ux - ox, uy - oy]);
+    const userPerPx = Math.hypot(rx - ox, ry - oy);
+    const out = [];
+    for (const line of read) {
+        const words = [];
+        const baselineAt = (px) => {
+            const { x0, y0, x1, y1 } = line.baseline;
+            return x1 === x0 ? y0 : y0 + ((px - x0) / (x1 - x0)) * (y1 - y0);
+        };
+        // The line's text size: its tallest letters (capitals and ascenders reach about 0.72 em) over the baseline.
+        const tops = line.words.map((w) => baselineAt(w.bbox.x0) - w.bbox.y0).filter((h) => h > 0).sort((p, q) => p - q);
+        const sizePx = tops.length > 0 ? tops[tops.length - 1] / 0.72 : 0;
+        if (!(sizePx > 0))
+            continue;
+        for (const w of line.words) {
+            const box = { x0: w.bbox.x0 + region.x0, y0: w.bbox.y0 + region.y0, x1: w.bbox.x1 + region.x0, y1: w.bbox.y1 + region.y0 };
+            if (alreadyThere(box, w.text))
+                continue;
+            const letters = (w.symbols && w.symbols.length > 0 ? w.symbols : [...w.text].map((ch, i, all) => ({
+                text: ch,
+                bbox: { x0: w.bbox.x0 + ((w.bbox.x1 - w.bbox.x0) * i) / all.length, y0: w.bbox.y0, x1: w.bbox.x0 + ((w.bbox.x1 - w.bbox.x0) * (i + 1)) / all.length, y1: w.bbox.y1 },
+            })));
+            const glyphs = letters.map((s, i) => {
+                const x0 = s.bbox.x0 + region.x0;
+                const nextX = i + 1 < letters.length ? letters[i + 1].bbox.x0 + region.x0 : s.bbox.x1 + region.x0;
+                const [x, y] = toUser(x0, baselineAt(s.bbox.x0) + region.y0);
+                return { unicode: s.text, x, y, advance: Math.max(0, nextX - x0) * userPerPx };
+            });
+            words.push({ glyphs, size: sizePx * userPerPx, dir, up });
+        }
+        if (words.length > 0)
+            out.push(words);
+    }
+    return { page: pageIndex, lines: out };
+}
 /** True for names ending in .pdf (case-insensitive). */
 export function isPdfFile(filename) {
     return /\.pdf$/i.test(filename.trim());

package/dist/pdf/standard-metrics.d.ts

@@ -25,3 +25,9 @@ export interface StandardMetrics {
     capHeight: number;
 }
 export declare function loadStandardMetrics(name: StandardFontName): StandardMetrics;
+/**
+ * Helvetica advance of one character in 1/1000 em: a stand-in for the proportions of a sans-serif
+ * print (Arial and Liberation Sans share them). Letters WinAnsi cannot encode take their base
+ * letter's width ("ł" as "l"), anything else the width of a digit.
+ */
+export declare function helveticaWidth(ch: string): number;

package/dist/pdf/standard-metrics.js

@@ -5,7 +5,7 @@
  * common aliases: Arial, Times New Roman, Courier New) get their advance
  * widths from the AFM metrics vendored by @cantoo/pdf-lib.
  */
-import { Font as AfmFont } from '@cantoo/pdf-lib/standard-fonts';
+import { Encodings, Font as AfmFont } from '@cantoo/pdf-lib/standard-fonts';
 const CACHE = new Map();
 function normalizeBaseFont(baseFont) {
     return baseFont.replace(/^[A-Z]{6}\+/, '').replace(/[\s_]/g, '').toLowerCase();
@@ -70,3 +70,26 @@ export function loadStandardMetrics(name) {
         capHeight: font.CapHeight ?? 718,
     };
 }
+/**
+ * Helvetica advance of one character in 1/1000 em: a stand-in for the proportions of a sans-serif
+ * print (Arial and Liberation Sans share them). Letters WinAnsi cannot encode take their base
+ * letter's width ("ł" as "l"), anything else the width of a digit.
+ */
+export function helveticaWidth(ch) {
+    const metrics = loadStandardMetrics('Helvetica');
+    for (const candidate of [ch, ch.normalize('NFD').charAt(0)]) {
+        const cp = candidate.codePointAt(0);
+        if (cp === undefined)
+            continue;
+        try {
+            const glyph = Encodings.WinAnsi.encodeUnicodeCodePoint(cp);
+            const w = metrics.widthOfGlyph(glyph.name);
+            if (w !== undefined)
+                return w;
+        }
+        catch {
+            // not in WinAnsi: try the base letter
+        }
+    }
+    return 556;
+}

package/dist/pdf/textstate.d.ts

@@ -3,7 +3,8 @@
  *
  * Tracks the subset of the graphics state that positions glyphs (ISO 32000-1
  * 8.4, 9.3, 9.4): CTM, text state parameters, text matrix and line matrix,
- * fill colour (to spot white-on-white text), and the q/Q stack. The same
+ * fill colour (to spot white-on-white text), constant alpha from ExtGState
+ * (to spot fully transparent text, a common OCR layer), and the q/Q stack. The same
  * class is used by the extractor (to compute glyph origins) and by the
  * surgery (to know the state at any operator).
  */
@@ -36,6 +37,15 @@ export interface GraphicsState {
     fillLuminance: number | null;
     /** Stroke luminance, for render modes that only stroke. */
     strokeLuminance: number | null;
+    /** Constant alpha (ExtGState /ca) for filling, 0..1. */
+    fillAlpha: number;
+    /** Constant alpha (ExtGState /CA) for stroking, 0..1. */
+    strokeAlpha: number;
+}
+/** The alpha entries of a named ExtGState (absent when the dictionary does not set them). */
+export interface ExtGStateAlpha {
+    fillAlpha?: number;
+    strokeAlpha?: number;
 }
 export declare function initialState(ctm?: Matrix): GraphicsState;
 /**
@@ -58,10 +68,11 @@ export declare class StateMachine {
     constructor(initial: GraphicsState);
     /**
      * Apply one operator's effect on the state. `resolveFont` maps a resource
-     * name to a LoadedFont (undefined when unknown). Returns false when the
-     * operator is a text-showing operator (caller handles it).
+     * name to a LoadedFont (undefined when unknown); `resolveGState` maps an
+     * ExtGState resource name to its alpha entries (without it `gs` is ignored).
+     * Text-showing operators are not handled here (caller handles them).
      */
-    update(op: ContentOp, resolveFont: (name: string) => LoadedFont | undefined): void;
+    update(op: ContentOp, resolveFont: (name: string) => LoadedFont | undefined, resolveGState?: (name: string) => ExtGStateAlpha | undefined): void;
     nextLine(): void;
     /** Move the text matrix by an unscaled text-space advance (already includes Tfs, Tc, Tw, Th). */
     advanceText(tx: number): void;

package/dist/pdf/textstate.js

@@ -3,7 +3,8 @@
  *
  * Tracks the subset of the graphics state that positions glyphs (ISO 32000-1
  * 8.4, 9.3, 9.4): CTM, text state parameters, text matrix and line matrix,
- * fill colour (to spot white-on-white text), and the q/Q stack. The same
+ * fill colour (to spot white-on-white text), constant alpha from ExtGState
+ * (to spot fully transparent text, a common OCR layer), and the q/Q stack. The same
  * class is used by the extractor (to compute glyph origins) and by the
  * surgery (to know the state at any operator).
  */
@@ -50,7 +51,7 @@ export function matrixFromOperands(ops) {
     return [n[0], n[1], n[2], n[3], n[4], n[5]];
 }
 function cloneState(s) {
-    return { ctm: s.ctm, text: { ...s.text }, fillLuminance: s.fillLuminance, strokeLuminance: s.strokeLuminance };
+    return { ctm: s.ctm, text: { ...s.text }, fillLuminance: s.fillLuminance, strokeLuminance: s.strokeLuminance, fillAlpha: s.fillAlpha, strokeAlpha: s.strokeAlpha };
 }
 export function initialState(ctm = IDENTITY) {
     return {
@@ -58,6 +59,8 @@ export function initialState(ctm = IDENTITY) {
         text: { font: null, fontName: '', fontSize: 0, charSpacing: 0, wordSpacing: 0, hscale: 1, leading: 0, rise: 0, renderMode: 0 },
         fillLuminance: 0,
         strokeLuminance: 0,
+        fillAlpha: 1,
+        strokeAlpha: 1,
     };
 }
 function num(o, fallback = 0) {
@@ -103,10 +106,11 @@ export class StateMachine {
     }
     /**
      * Apply one operator's effect on the state. `resolveFont` maps a resource
-     * name to a LoadedFont (undefined when unknown). Returns false when the
-     * operator is a text-showing operator (caller handles it).
+     * name to a LoadedFont (undefined when unknown); `resolveGState` maps an
+     * ExtGState resource name to its alpha entries (without it `gs` is ignored).
+     * Text-showing operators are not handled here (caller handles them).
      */
-    update(op, resolveFont) {
+    update(op, resolveFont, resolveGState) {
         const s = this.state;
         const o = op.operands;
         switch (op.op) {
@@ -234,6 +238,15 @@ export class StateMachine {
                 s.strokeLuminance = this.strokeSpace && nums.length === o.length ? luminanceOf(nums, this.strokeSpace) : null;
                 break;
             }
+            case 'gs': {
+                const nameOp = o[0];
+                const alpha = nameOp && nameOp.kind === 'name' ? resolveGState?.(nameOp.value) : undefined;
+                if (alpha?.fillAlpha !== undefined)
+                    s.fillAlpha = clamp01(alpha.fillAlpha);
+                if (alpha?.strokeAlpha !== undefined)
+                    s.strokeAlpha = clamp01(alpha.strokeAlpha);
+                break;
+            }
             default:
                 break;
         }

package/dist/pdf/types.d.ts

@@ -8,6 +8,7 @@
  * cannot be edited safely are rasterized and reported, never shipped with a
  * box drawn over live text.
  */
+import type { CanvasFactory } from './oracle.js';
 import type { UnredactablePart } from '../dom/errors.js';
 /**
  * Runtime assets the host serves. Everything is optional: in Node tests the
@@ -81,8 +82,13 @@ export interface GlyphRun {
     glyphs: Glyph[];
     /** Text render mode at the time of showing (3 and 7 paint nothing: invisible OCR layers). */
     renderMode: number;
-    /** True when the run is not visible (render mode 3/7, or fully outside the page). */
+    /** True when the run is not visible (render mode 3/7, white, fully transparent, tiny, or painted under an opaque image). */
     hidden: boolean;
+    /**
+     * Hidden text over an image: an OCR layer, the reading of what a scanned picture shows. A
+     * redaction that touches it is painted into the picture (the page is exported as an image).
+     */
+    ocr?: boolean;
     /** Flat-text offset of each glyph's first character (parallel to glyphs). */
     textOffsets: number[];
     /** User-space vector of one em (1000 glyph units) along the baseline, at this run's transform. */
@@ -134,6 +140,30 @@ export interface PdfPageInfo {
     hasImages: boolean;
     /** True when the page shows images but no glyph at all (scanned page). */
     imageOnly: boolean;
+    /**
+     * True when hidden text lies over an image on the page (a scan with an OCR text layer).
+     * Redacted values in it are painted over in the picture, and the page is exported as an image.
+     */
+    ocrText: boolean;
+    /**
+     * Lines of text the page shows that its text layer does not have: on a scan, text its OCR layer
+     * missed (a table, a stamp); on a text page, text inside an image. Without the host's OCR they
+     * cannot be found or redacted. Absent when the page was not checked (no canvas in the host) or
+     * nothing is missing.
+     */
+    ocrMissingLines?: number;
+    /**
+     * Words DocCloak read itself (the host's `recognizeText`) where the page's text layer had none
+     * (`ocrMissingLines`). They are detected like the layer's own words, and their values are painted
+     * over in the picture (a text page with such a value is exported as an image).
+     */
+    ocrReadWords?: number;
+    /**
+     * On a page without any text layer (a picture only): the words DocCloak read on the whole page
+     * with the host's OCR. Above 0 the page is handled as a scan with an OCR layer (`ocrText`); 0: read,
+     * no text found (the page stays as it is). Absent when the page was not read.
+     */
+    ocrWholePage?: number;
     /** Flat-text range of the page. */
     textStart: number;
     textEnd: number;
@@ -156,6 +186,85 @@ export interface PdfReadOptions {
     maxGlyphs?: number;
     /** User password for encrypted files. Without it an encrypted file is refused. */
     password?: string;
+    /**
+     * Look for text a page shows that its text layer does not have: on a scan with an OCR layer, text
+     * the OCR missed; on a text page with images, text inside the images (renders those pages at
+     * 100 dpi). Default true.
+     */
+    checkOcrCoverage?: boolean;
+    /**
+     * Read the pages without any text layer (pictures only) with `recognizeText`, so their text joins
+     * the document and their values are painted over like a scan's. Default true.
+     */
+    ocrImagePages?: boolean;
+    /** Progress of the host OCR: pages read so far of the pages to read (called before the first and after each). */
+    onOcrProgress?: (done: number, total: number) => void;
+    /** Node hosts and tests: canvas factory for that check. Browsers use OffscreenCanvas. */
+    canvasFactory?: CanvasFactory;
+    /**
+     * OCR for text a scan page's OCR layer does not have: read `region` (pixels) of `canvas` (the page
+     * rendered at `dpi`, 300) and return its lines, relative to the region. Without it such text is only
+     * reported (`ocrMissingLines`).
+     */
+    recognizeText?: RecognizeRegion;
+}
+/** A line a host OCR read: baseline and words with their letter boxes, in the pixels of the canvas given. */
+export interface RecognizedLine {
+    baseline: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    words: Array<{
+        text: string;
+        bbox: {
+            x0: number;
+            y0: number;
+            x1: number;
+            y1: number;
+        };
+        /** The OCR's confidence in the word, 0..100, when it gives one. */
+        confidence?: number;
+        symbols?: Array<{
+            text: string;
+            bbox: {
+                x0: number;
+                y0: number;
+                x1: number;
+                y1: number;
+            };
+        }>;
+    }>;
+}
+export type RecognizeRegion = (canvas: unknown, region: {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}, dpi: number) => Promise<RecognizedLine[]>;
+/** One glyph DocCloak read with its own OCR, in user space (origin on the baseline). */
+export interface ExtraOcrGlyph {
+    unicode: string;
+    x: number;
+    y: number;
+    advance: number;
+}
+/** A word DocCloak read with its own OCR: its glyphs, the text size and the baseline / up directions (unit vectors). */
+export interface ExtraOcrWord {
+    glyphs: ExtraOcrGlyph[];
+    size: number;
+    dir: [number, number];
+    up: [number, number];
+}
+/**
+ * Text DocCloak read on a page where the text layer had none, by line. The writer re-creates the
+ * same runs from it. `whole`: the page had no text layer at all and was read entirely.
+ */
+export interface ExtraOcrPage {
+    page: number;
+    lines: ExtraOcrWord[][];
+    whole?: boolean;
 }
 export interface PlaceholderFit {
     /** Lowest font-size ratio (placeholder size / original size) before condensing kicks in. Default 0.65. */
@@ -171,9 +280,9 @@ export interface PdfWriteOptions {
     allowUnredactable?: boolean;
     /** Placeholder fitting policy. */
     fit?: PlaceholderFit;
-    /** Rasterize pages whose text cannot be edited safely instead of refusing the file. Default true. */
+    /** Rasterize pages whose text cannot be edited safely instead of refusing the file. Default true. Scan pages are always rendered. */
     rasterizeUnsafePages?: boolean;
-    /** DPI for rasterized pages. Default 150. */
+    /** DPI for rasterized pages. Default 150; scan pages use the scan's own resolution (at least this, at most 300). */
     rasterDpi?: number;
     /** Skip the post-write verification (tests only; never in hosts). */
     skipVerify?: boolean;
@@ -184,8 +293,13 @@ export interface PdfWriteResult {
     warnings: string[];
     /** Parts dropped from the output (annotations, forms, ...). */
     removed: RemovedPart[];
-    /** 0-based indexes of pages that were rasterized. */
+    /** 0-based indexes of pages that were rasterized because their text could not be edited safely (black boxes). */
     rasterizedPages: number[];
+    /**
+     * 0-based indexes of scan pages with an OCR text layer whose values were painted over in the
+     * picture (placeholder labels at the values' places); each is exported as an image.
+     */
+    scanPages: number[];
     /** Placeholders whose fit needed a line shift (informational). */
     shiftedLines: number;
 }

package/dist/pdf/verify.js

@@ -107,6 +107,13 @@ export async function verifyPdf(input) {
             if (obj instanceof PDFRawStream) {
                 if (isImageEncoded(ctx, obj))
                     continue;
+                // Image samples (a Flate or uncompressed picture, a scan page we painted) are pixels, not
+                // text: a short value turns up in them by chance ("36" in a gray ramp 51, 54). Only the
+                // image dictionary's strings are searched.
+                if (namesOf(ctx, obj.dict.get(PDFName.of('Subtype')))[0] === 'Image') {
+                    scanStrings(obj.dict, ref.objectNumber, encodedNeedles, findings, new Set());
+                    continue;
+                }
                 let decoded;
                 try {
                     decoded = decodeStream(ctx, obj);
@@ -130,13 +137,16 @@ export async function verifyPdf(input) {
                 }
                 const type = namesOf(ctx, obj.dict.get(PDFName.of('Type')))[0];
                 const subtype = namesOf(ctx, obj.dict.get(PDFName.of('Subtype')))[0];
-                const isContent = type === undefined || type === 'Pattern' || (type === 'XObject' && subtype === 'Form');
+                const cmap = looksLikeCMap(decoded);
+                const isContent = !cmap && (type === undefined || type === 'Pattern' || (type === 'XObject' && subtype === 'Form'));
                 if (isContent)
                     contentStreams.push(decoded);
                 // A content stream shows text only through its string operands: numbers, names and
-                // operators ("/F1 12 Tf", coordinates) are not text a viewer displays. Other streams
-                // (XMP, CMaps, anything unknown) are scanned whole.
-                const haystack = haystackOf(isContent ? stringOperandsOf(decoded) : decoded);
+                // operators ("/F1 12 Tf", coordinates) are not text a viewer displays. A CMap's hex codes
+                // are character codes and code points ("<004A> <2019>" maps a code to the apostrophe), not
+                // text: a four-digit value turns up in them by chance; the rest of the CMap is searched.
+                // Other streams (XMP, anything unknown) are scanned whole.
+                const haystack = haystackOf(isContent ? stringOperandsOf(decoded) : cmap ? withoutHexStrings(decoded) : decoded);
                 if (isContent)
                     contentStrings.push(haystack);
                 for (const n of encodedNeedles) {
@@ -175,7 +185,7 @@ export async function verifyPdf(input) {
         }
     }
     // No whole-file byte pass: every object pdf-lib writes is either a stream (scanned decoded above,
-    // font programs and image codecs excepted) or a dict/array/string (scanned above). A raw scan would
+    // font programs, image codecs and image samples excepted) or a dict/array/string (scanned above). A raw scan would
     // only add false positives from font names ("Roman", "Georgia") inside embedded font programs.
     return dedupe(findings);
 }
@@ -444,3 +454,26 @@ function hex(bytes) {
         s += b.toString(16).padStart(2, '0');
     return s;
 }
+/** A CMap (a ToUnicode map, an embedded CID CMap): its program begins the CMap resource. */
+function looksLikeCMap(decoded) {
+    const head = new TextDecoder('latin1').decode(decoded.subarray(0, Math.min(decoded.length, 600)));
+    return /\bbegincmap\b/.test(head) || /\/CIDInit\b/.test(head);
+}
+/** The bytes of a CMap without its hex strings ("<004A>"), each replaced by one space. */
+function withoutHexStrings(decoded) {
+    const out = [];
+    for (let i = 0; i < decoded.length; i++) {
+        if (decoded[i] === 0x3c /* < */ && decoded[i + 1] !== 0x3c) {
+            let j = i + 1;
+            while (j < decoded.length && decoded[j] !== 0x3e /* > */ && /[0-9A-Fa-f\s]/.test(String.fromCharCode(decoded[j])))
+                j++;
+            if (j < decoded.length && decoded[j] === 0x3e) {
+                out.push(0x20);
+                i = j;
+                continue;
+            }
+        }
+        out.push(decoded[i]);
+    }
+    return new Uint8Array(out);
+}