@doccloak/core 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to `@doccloak/core` are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.14.0] - 2026-10-22
+
+Scanned PDF pages with an OCR text layer are redacted where a reader sees
+them: in the picture. Additive for hosts (`PdfPageInfo.ocrText`,
+`GlyphRun.ocr`, `PdfWriteResult.scanPages`, `scanPages` from
+`redactOfficeFile`); one behaviour change: such pages are no longer reported
+as unredactable `'scanned-page'` parts, because they are now redacted.
+`CoreEnv.loadTokenizer` still works with its deprecation warning; its
+removal, announced for this release, moves to a later one.
+
+### Scanned pages with an OCR text layer are redacted in the picture (T235)
+
+Reported in DocCloak.Core#1: a court judgment scanned with an OCR text layer
+(Lutecia / 3-Heights: the text sits in a form XObject under an ExtGState
+with `/ca 0`) was "redacted" in its invisible text layer only; the picture,
+which is what a reader sees, still showed every name.
+
+- **Transparent text is hidden text.** The state machine follows `gs` and
+  keeps the fill and stroke alpha (`ca` / `CA`); text painted at alpha below
+  0.02 counts as hidden, like render mode 3 and white text. Text painted
+  before an opaque image that covers it ("text under the page image") is
+  hidden too.
+- **OCR text.** Hidden text over an image is marked `GlyphRun.ocr`, and its
+  page `PdfPageInfo.ocrText`. A scan page with OCR text is no longer an
+  unredactable part; a scan page without any text still is
+  (`'scanned-page'`, exported as is with `allowUnredactable`), and a file
+  without any text still reads as `empty`.
+- **Painted placeholders.** A page whose OCR text holds a redacted value is
+  rendered at the scan's resolution (from the images' size and placement, at
+  least `rasterDpi`, at most 300 dpi, within a 40 Mpx budget). Each value is
+  covered in the paper colour (median of the pixels around it) and its
+  placeholder is painted on the value's baseline. The cover grows along the
+  line to where the value's ink ends (stopping at a word space, at most one
+  em), because OCR layers set letters in their own font and a value's last
+  letters can run past the layer's end; its height and the label's size come
+  from the value's ink, because OCR layers often stretch their font size to
+  the line height. The label fits the value's width: squeezed down to 60 %,
+  then shrunk. Pieces of a value on one line join under one label; a value
+  wrapped to the next line is covered there without a label. All covers are
+  painted before any label, so a cover never clips the line above.
+- The page is embedded as a lossless Flate image (gray when the page is
+  gray), not a PNG: page 1 of the reported file stays the size of the scan.
+  It has no text layer. The writer lists it in the new
+  `PdfWriteResult.scanPages` (and `redactOfficeFile` in `scanPages`), with
+  a warning; `rasterizedPages` keeps meaning pages blacked out because
+  their text could not be edited safely.
+- Text-layer PDFs are unchanged: the founder's kit files 01-08 read
+  identically (text, pages, parts, warnings) to 0.13.0.
+- Tests: `pdf-scan.test.ts` (synthetic scans with values painted red: alpha,
+  render mode 3 and text-under-image layers, OCR letters narrower than the
+  scan, a mixed scan / picture-only / text file; transparent text without an
+  image; alpha in the state machine; cover growth; mark joining).
+
 ## [0.13.0] - 2026-09-25
 
 PDF-to-PDF redaction that keeps the text layer (new `@doccloak/core/pdf`

package/README.md

@@ -190,7 +190,7 @@ const assets = {
 const extraction = await readPdf(file, { assets });     // extraction.plainText -> detect
 const entities = await engine.detect(extraction.plainText);
 const replacements = entities.map((e) => ({ start: e.start, end: e.end, replacement: session.anonymize(e.value, e.type) }));
-const { blob, warnings, removed, rasterizedPages } = await writeAnonymizedPdfWithReport(
+const { blob, warnings, removed, rasterizedPages, scanPages } = await writeAnonymizedPdfWithReport(
   extraction, replacements, session.getEntries(), { assets },
 );
 ```
@@ -245,11 +245,28 @@ ToUnicode maps of edited fonts are trimmed to the codes still used,
 configuration is dropped as well, so content of hidden layers becomes
 visible (it is redacted like everything else).
 
+**Scanned pages with an OCR text layer.** A scan with OCR shows a picture;
+its text layer is invisible (render mode 3, fully transparent paint through
+an ExtGState `/ca 0`, or text painted under the picture). Editing that layer
+alone would leave every value visible in the picture, so the reader marks
+such text (`GlyphRun.ocr`, `PdfPageInfo.ocrText`) and the writer renders a
+page whose OCR text holds a redacted value at the scan's own resolution (at
+least `rasterDpi`, at most 300 dpi) and paints the value over in the
+picture: a cover in the paper colour, grown along the line to where the
+value's ink really ends (OCR letters rarely have the scan's widths), and the
+placeholder label in its place, on the value's baseline, sized from the
+value's ink and fitted to the value's width (squeezed, then shrunk). The
+page is exported as a lossless image (gray for a gray scan) without a text
+layer and listed in `scanPages`. Pages of the same file without any text are
+not touched.
+
 **Refusals.** Encrypted files (`'encrypted'`, pass `password`), files over
 50 MB or 500 pages (`'too-large'`), non-PDF bytes (`'invalid-package'`).
-Scanned pages (image without a text layer) and text no decoder can read are
+Scanned pages without a text layer (no OCR) and text no decoder can read are
 reported in `unredactable` (`'scanned-page'`, `'undecodable-text'`) and gate
-the export behind `allowUnredactable`, like Office packages.
+the export behind `allowUnredactable`, like Office packages; with it they
+are exported as they are. A file whose pages hold no text at all reads as
+`empty`.
 
 ## What is removed or normalised in Office packages
 

package/dist/dom/office.d.ts

@@ -127,6 +127,8 @@ export interface OfficeRedactionResult {
     removed?: RemovedPart[];
     /** PDF only: 0-based pages that were rasterized because they could not be edited safely. */
     rasterizedPages?: number[];
+    /** PDF only: 0-based scan pages whose OCR-found values were painted over in the picture. */
+    scanPages?: number[];
 }
 /** "report.docx" -> "report.redacted.docx"; extensionless names get a suffix. */
 export declare function redactedFileName(filename: string): string;

package/dist/dom/office.js

@@ -198,5 +198,6 @@ export async function redactOfficeFile(file, options) {
         unredactable: extraction.unredactable,
         removed: written.removed,
         rasterizedPages: written.rasterizedPages,
+        scanPages: written.scanPages,
     };
 }

package/dist/env.d.ts

@@ -42,7 +42,7 @@ export interface CoreEnv {
      * named by `tokenizerConfig.tokenizer_class`). May return a promise.
      *
      * Optional so hosts still on loadTokenizer keep compiling; required once
-     * loadTokenizer is removed (planned for 0.14.0).
+     * loadTokenizer is removed (planned for a later release).
      */
     buildTokenizer?(tokenizerJson: unknown, tokenizerConfig: unknown): unknown | Promise<unknown>;
     /**

package/dist/pdf/extract.d.ts

@@ -56,6 +56,8 @@ export interface PageRecord {
     /** Our decoder's runs and text of a raster-only page (kept for blacking out with our geometry too). */
     ownRuns?: GlyphRun[];
     ownText?: string;
+    /** Highest effective resolution of the images drawn on the page (pixels per inch; 0 without images). */
+    imageDpi: number;
 }
 export interface PdfModel {
     bytes: Uint8Array;

package/dist/pdf/extract.js

@@ -13,7 +13,7 @@
  * never modified.
  */
 import { PDFDocument } from '@cantoo/pdf-lib';
-import { PDFArray, PDFDict, PDFName, PDFNumber, PDFRef, PDFStream, StreamDecodeError, decodeStream, getArray, getDict, getName, getNumber, getStream, inheritedPageValue, itemsOf, numbersOf, pageContentStreams, pageResources, refKey, resolve, stringText, } from "./objects.js";
+import { PDFArray, PDFDict, PDFName, PDFNumber, PDFRef, PDFStream, StreamDecodeError, decodeStream, getArray, getBool, getDict, getName, getNumber, getStream, inheritedPageValue, itemsOf, numbersOf, pageContentStreams, pageResources, refKey, resolve, stringText, } from "./objects.js";
 import { lexContent, TEXT_SHOW_OPS } from "./lexer.js";
 import { StateMachine, adjustmentAdvance, apply, glyphAdvance, initialState, mul, matrixFromOperands } from "./textstate.js";
 import { loadFont } from "./fonts.js";
@@ -92,11 +92,12 @@ export async function extractPdf(bytes, options = {}) {
             index: p,
             dict: pageDict,
             ref: pageRef,
-            info: { index: p, width, height, rotate, hasImages: false, imageOnly: false, textStart: text.length, textEnd: text.length },
+            info: { index: p, width, height, rotate, hasImages: false, imageOnly: false, ocrText: false, textStart: text.length, textEnd: text.length },
             streams: [],
             issues: [],
             hiddenGlyphs: 0,
             oracleText: false,
+            imageDpi: 0,
         };
         model.pages.push(record);
         const pageTextStart = text.length;
@@ -143,8 +144,11 @@ export async function extractPdf(bytes, options = {}) {
         if (glyphCount > maxGlyphs) {
             throw new UnsupportedDocumentError('too-large', `PDF holds more than ${maxGlyphs} glyphs; the limit protects the host's memory`, [String(glyphCount)]);
         }
+        walker.markOcrText(runs, pageRunStart);
         record.info.hasImages = walker.sawImage;
         record.info.imageOnly = walker.sawImage && walker.visibleGlyphs === 0;
+        record.info.ocrText = walker.ocrGlyphs > 0;
+        record.imageDpi = walker.imageDpi();
         let oracleGarbage = false;
         if (options.oracle && !record.hostile) {
             let items = null;
@@ -186,16 +190,22 @@ export async function extractPdf(bytes, options = {}) {
                     appendOracleRuns(p, items, runs, text);
                     if (items.some((it) => it.str.trim() !== ''))
                         record.info.imageOnly = false;
+                    // The oracle's runs replace ours and carry no OCR marks: the page is blacked out as a raster-only page.
+                    record.info.ocrText = false;
                 }
             }
         }
         record.info.textEnd = text.length;
-        if (record.info.imageOnly) {
+        if (record.info.imageOnly && record.info.ocrText) {
+            // A scan with an OCR text layer: detection reads the layer, and the writer paints the
+            // placeholders into the picture where the layer says the values are.
+        }
+        else if (record.info.imageOnly) {
             unredactable.push({
                 part: `page ${p + 1}`,
                 kind: 'scanned-page',
                 label: record.hiddenGlyphs > 0
-                    ? `page ${p + 1} is a scanned image with a hidden OCR text layer: the text layer is redacted, the picture keeps the original`
+                    ? `page ${p + 1} is a scanned image with a hidden text layer that is not over the picture: the text layer is redacted, the picture keeps the original`
                     : `page ${p + 1} is an image without a text layer (scanned page); its content cannot be redacted`,
             });
         }
@@ -544,13 +554,18 @@ function appendOracleRuns(page, items, runs, text) {
         });
     });
 }
-/* ------------------------------------------------------------------ */
-/* Content walker                                                      */
-/* ------------------------------------------------------------------ */
+/** Constant alpha below this paints nothing a reader can see. */
+const MIN_VISIBLE_ALPHA = 0.02;
 class Walker {
     constructor(model, page, runs, text, box) {
         this.sawImage = false;
         this.visibleGlyphs = 0;
+        /** Glyphs of text hidden over an image (an OCR layer), counted by markOcrText. */
+        this.ocrGlyphs = 0;
+        this.images = [];
+        /** Paint order of text runs and images on this page (text drawn before an opaque image is covered by it). */
+        this.order = 0;
+        this.runOrder = new Map();
         this.undecodableGlyphs = 0;
         /** A composite font without a usable CMap/ToUnicode showed text: pdf.js's reading of it is a guess (glyph ids), never trusted. */
         this.unreadableCompositeFont = false;
@@ -569,6 +584,13 @@ class Walker {
         const { ctx } = this.model;
         const fontsDict = getDict(ctx, stream.resources, 'Font');
         const resolveFont = (name) => loadFont(ctx, fontsDict, name, this.model.fonts);
+        const statesDict = getDict(ctx, stream.resources, 'ExtGState');
+        const resolveGState = (name) => {
+            const d = resolve(ctx, statesDict?.get(PDFName.of(name)));
+            if (!(d instanceof PDFDict))
+                return undefined;
+            return { fillAlpha: getNumber(ctx, d, 'ca'), strokeAlpha: getNumber(ctx, d, 'CA') };
+        };
         const sm = new StateMachine(base);
         // Text can also live in tiling pattern cells and soft-mask groups of this stream's resources.
         this.walkAuxiliary(stream, base, depth, active);
@@ -582,17 +604,19 @@ class Walker {
             if (TEXT_SHOW_OPS.has(op.op)) {
                 // ' and " move to the next line (and set spacing) before showing.
                 if (op.op === "'" || op.op === '"')
-                    sm.update(op, resolveFont);
+                    sm.update(op, resolveFont, resolveGState);
                 this.show(stream, i, op, sm, resolveFont);
                 continue;
             }
             if (op.op === 'Do') {
-                sm.update(op, resolveFont);
+                sm.update(op, resolveFont, resolveGState);
                 this.doXObject(stream, op, sm, depth, active);
                 continue;
             }
             if (op.op === 'BI') {
                 this.sawImage = true;
+                // Inline images are small (the format caps them at 4 KB in practice): placed, never trusted as opaque.
+                this.placeImage(sm, 0, 0, false);
                 continue;
             }
             if (op.op === 'd0' || op.op === 'd1') {
@@ -601,7 +625,62 @@ class Walker {
             if (op.op === 'sh') {
                 // Shading is drawing, not text; nothing to do.
             }
-            sm.update(op, resolveFont);
+            sm.update(op, resolveFont, resolveGState);
+        }
+    }
+    /** Record an image painted at the current CTM (it fills the unit square of image space). */
+    placeImage(sm, widthPx, heightPx, opaque) {
+        const m = sm.state.ctm;
+        const corners = [apply(m, 0, 0), apply(m, 1, 0), apply(m, 0, 1), apply(m, 1, 1)];
+        const xs = corners.map((c) => c[0]);
+        const ys = corners.map((c) => c[1]);
+        // Pixels per inch along each image axis: the axis spans |row| user units (1/72 in).
+        const alongX = Math.hypot(m[0], m[1]) / 72;
+        const alongY = Math.hypot(m[2], m[3]) / 72;
+        const dpi = Math.max(alongX > 0 ? widthPx / alongX : 0, alongY > 0 ? heightPx / alongY : 0);
+        this.images.push({
+            x0: Math.min(...xs), y0: Math.min(...ys), x1: Math.max(...xs), y1: Math.max(...ys),
+            dpi: Number.isFinite(dpi) ? dpi : 0,
+            opaque: opaque && sm.state.fillAlpha >= 1,
+            order: this.order++,
+        });
+    }
+    /** Highest effective resolution of the images on the page. */
+    imageDpi() {
+        let dpi = 0;
+        for (const im of this.images)
+            dpi = Math.max(dpi, im.dpi);
+        return dpi;
+    }
+    /**
+     * After the walk: text hidden over an image is an OCR layer (`ocr`), the reading of what the
+     * picture shows. Text painted BEFORE an opaque image that covers it is hidden too ("text under
+     * the page image", another common OCR layout), so it counts as hidden and as OCR text.
+     */
+    markOcrText(runs, from) {
+        if (this.images.length === 0)
+            return;
+        for (let r = from; r < runs.length; r++) {
+            const run = runs[r];
+            if (run.space || run.oracle)
+                continue;
+            const order = this.runOrder.get(run) ?? -1;
+            const shown = run.glyphs.filter((g) => g.unicode.trim() !== '');
+            if (shown.length === 0)
+                continue;
+            const within = (im) => shown.filter((g) => glyphInside(im, g, run)).length * 2 >= shown.length;
+            if (!run.hidden) {
+                if (!this.images.some((im) => im.opaque && im.order > order && within(im)))
+                    continue;
+                run.hidden = true;
+                this.visibleGlyphs -= shown.length;
+                this.page.hiddenGlyphs += run.glyphs.length;
+            }
+            else if (!this.images.some(within)) {
+                continue;
+            }
+            run.ocr = true;
+            this.ocrGlyphs += shown.length;
         }
     }
     /**
@@ -707,6 +786,10 @@ class Walker {
         const subtype = getName(ctx, xobj.dict, 'Subtype');
         if (subtype === 'Image') {
             this.sawImage = true;
+            const d = xobj.dict;
+            const masked = getBool(ctx, d, 'ImageMask') === true || d.get(PDFName.of('SMask')) !== undefined
+                || d.get(PDFName.of('Mask')) !== undefined || (getNumber(ctx, d, 'SMaskInData') ?? 0) !== 0;
+            this.placeImage(sm, getNumber(ctx, d, 'Width') ?? 0, getNumber(ctx, d, 'Height') ?? 0, !masked);
             return;
         }
         if (subtype !== 'Form')
@@ -755,6 +838,8 @@ class Walker {
         inner.text = { ...sm.state.text };
         inner.fillLuminance = sm.state.fillLuminance;
         inner.strokeLuminance = sm.state.strokeLuminance;
+        inner.fillAlpha = sm.state.fillAlpha;
+        inner.strokeAlpha = sm.state.strokeAlpha;
         active.add(key);
         this.walk(record, inner, depth + 1, active);
         active.delete(key);
@@ -817,9 +902,14 @@ class Walker {
         const emY = [trm0[2], trm0[3]];
         const hiddenByMode = t.renderMode === 3 || t.renderMode === 7;
         const hiddenByColor = t.renderMode === 0 && sm.state.fillLuminance !== null && sm.state.fillLuminance > 0.97;
+        // Fully transparent paint (ExtGState /ca, /CA): the OCR layer of many scanners.
+        const fills = [0, 2, 4, 6].includes(t.renderMode);
+        const strokes = [1, 2, 5, 6].includes(t.renderMode);
+        const hiddenByAlpha = (fills || strokes)
+            && (!fills || sm.state.fillAlpha < MIN_VISIBLE_ALPHA) && (!strokes || sm.state.strokeAlpha < MIN_VISIBLE_ALPHA);
         const sizeUser = Math.hypot(trm0[2], trm0[3]);
         const tiny = sizeUser < 0.5;
-        const hidden = hiddenByMode || hiddenByColor || tiny;
+        const hidden = hiddenByMode || hiddenByColor || hiddenByAlpha || tiny;
         const glyphs = [];
         const textOffsets = [];
         let advanceSoFar = 0; // unscaled text-space x from the run start
@@ -898,8 +988,18 @@ class Walker {
             ...(this.space ? { space: this.space } : {}),
         };
         this.runs.push(run);
+        this.runOrder.set(run, this.order++);
     }
 }
+/** True when the middle of glyph `g` (half an advance along, a third of an em up) lies inside `b`. */
+function glyphInside(b, g, run) {
+    const exLen = Math.hypot(run.emX[0], run.emX[1]) || 1;
+    const eyLen = Math.hypot(run.emY[0], run.emY[1]) || 1;
+    const w = g.advance * (exLen / (run.local.fontSize * run.local.hscale || 1));
+    const x = g.x + (run.emX[0] / exLen) * (w / 2) + (run.emY[0] / eyLen) * (g.fontSize / 3);
+    const y = g.y + (run.emX[1] / exLen) * (w / 2) + (run.emY[1] / eyLen) * (g.fontSize / 3);
+    return insideBox(b, x, y);
+}
 /**
  * Consecutive pages with the same kind of problem collapse into one part ("pages 2-22"), so a
  * document whose body font is unreadable shows one line to consent to, not one per page.

package/dist/pdf/raster.d.ts

@@ -6,6 +6,11 @@
  * canvas, after the render: the PNG never contains what was under a box.
  * The caller (writer) replaces the page contents with this image and
  * reports the page in `rasterizedPages`.
+ *
+ * Scan pages with an OCR text layer (T235) are rendered the same way at the
+ * scan's resolution, but each redacted value is covered in paper colour and
+ * its placeholder label is painted in its place, along the baseline and
+ * within the value's width (`rasterizeScanPage`).
  */
 import type { CanvasFactory, OracleDocument } from './oracle.js';
 import type { Rect } from './types.js';
@@ -43,3 +48,72 @@ export declare function padAndClamp(box: PixelBox, pad: number, widthPx: number,
  * encode the canvas as PNG.
  */
 export declare function rasterizePage(doc: OracleDocument, index: number, boxes: Rect[], options: RasterizeOptions): Promise<RasterizedPage>;
+/**
+ * A value to paint over on a scan page, in user space: the baseline segment
+ * the value occupies and the label to show there.
+ */
+export interface PaintMark {
+    /** Baseline point where the value starts. */
+    x: number;
+    y: number;
+    /** Unit vector along the baseline and unit vector "up" (the text's em direction). */
+    ux: number;
+    uy: number;
+    vx: number;
+    vy: number;
+    /** Length of the value along the baseline, user units. */
+    length: number;
+    /** Font size of the value's text, user units. */
+    size: number;
+    /** Placeholder to show; '' only covers (the rest of a value wrapped onto the next line). */
+    label: string;
+}
+/** A rendered scan page: raw pixels, 1 (gray) or 3 (RGB) bytes each, row-major. */
+export interface ScanRaster {
+    pixels: Uint8Array;
+    channels: 1 | 3;
+    widthPx: number;
+    heightPx: number;
+    widthPt: number;
+    heightPt: number;
+}
+/**
+ * Render page `index` at `options.dpi`, cover every mark in the paper colour
+ * around it and paint its label in the value's place: the baseline the OCR
+ * layer gives, the value's width (the label is squeezed, then shrunk, to fit;
+ * a shorter label leaves the rest of the width blank). Every cover is painted
+ * before any label, so a cover on the next line never clips a label above it.
+ * Returns the pixels, in gray when the page is gray (a scan usually is), so
+ * the writer can embed them losslessly at a size close to the original scan.
+ */
+export declare function rasterizeScanPage(doc: OracleDocument, index: number, marks: PaintMark[], options: RasterizeOptions): Promise<ScanRaster>;
+/**
+ * Vertical extent of the value's ink (user units from the baseline): the block of inked rows
+ * across [start, end] that holds the letters' bodies, grown up and down until a blank row (the
+ * leading between lines), within INK_REACH_BELOW / INK_REACH_ABOVE. Null when no ink is there.
+ */
+export declare function inkRows(rgba: Uint8ClampedArray, width: number, height: number, at: (along: number, up: number) => [number, number], m: PaintMark, start: number, end: number, inkBelow: number): {
+    bottom: number;
+    top: number;
+} | null;
+/**
+ * How far the ink of a value really reaches along its baseline (user units from the mark's
+ * start; `start` <= 0 and `end` >= length when the ink runs past the OCR layer's ends). Walks
+ * outwards pixel by pixel from inside the value and stops at the first blank gap of a word
+ * space, or after MAX_GROWTH.
+ */
+export declare function inkExtent(rgba: Uint8ClampedArray, width: number, height: number, at: (along: number, up: number) => [number, number], m: PaintMark, inkBelow: number): {
+    start: number;
+    end: number;
+};
+/**
+ * The paper colour around a cover: per-channel median of the pixels on a ring
+ * three pixels outside the quad's bounding box (mostly background, whatever
+ * text the ring crosses is a minority). White when the ring is off canvas.
+ */
+export declare function paperColour(rgba: Uint8ClampedArray, width: number, height: number, quad: Array<[number, number]>): [number, number, number];
+/** RGBA canvas pixels to gray (every pixel has R = G = B) or RGB bytes; alpha is dropped (pdf.js paints an opaque page). */
+export declare function packPixels(rgba: Uint8ClampedArray): {
+    pixels: Uint8Array;
+    channels: 1 | 3;
+};

package/dist/pdf/raster.js

@@ -6,6 +6,11 @@
  * canvas, after the render: the PNG never contains what was under a box.
  * The caller (writer) replaces the page contents with this image and
  * reports the page in `rasterizedPages`.
+ *
+ * Scan pages with an OCR text layer (T235) are rendered the same way at the
+ * scan's resolution, but each redacted value is covered in paper colour and
+ * its placeholder label is painted in its place, along the baseline and
+ * within the value's width (`rasterizeScanPage`).
  */
 /**
  * Map a user-space rectangle to canvas pixels through the pdf.js viewport
@@ -87,3 +92,314 @@ export async function rasterizePage(doc, index, boxes, options) {
         heightPt: page.heightPt,
     };
 }
+/**
+ * Cover extent around a value, in em of its font size: along the baseline, and below and above
+ * it when the picture shows no ink to measure. The OCR layer's font size is only a hint (layers
+ * often stretch it to the line height), so the cover's height and the label's size come from
+ * the ink itself (see inkRows), within INK_REACH_BELOW / INK_REACH_ABOVE of the baseline; the
+ * cover always holds the core band COVER_CORE_BELOW..COVER_CORE_ABOVE.
+ */
+const COVER_PAD_ALONG = 0.12;
+const COVER_BELOW = 0.32;
+const COVER_ABOVE = 0.92;
+const COVER_CORE_BELOW = 0.15;
+const COVER_CORE_ABOVE = 0.6;
+const INK_REACH_BELOW = 0.45;
+const INK_REACH_ABOVE = 1.1;
+/**
+ * OCR layers place words well but size letters from their own font, so a value's ink can run
+ * past the layer's ends. A cover grows along the baseline to the end of the ink it touches: the
+ * search starts this far inside the value, stops at a blank gap of WORD_GAP (a word space is
+ * about 0.28 em, gaps between letters stay under about 0.12 em) and never grows by more than
+ * MAX_GROWTH; ink is looked for in the band of the letters' bodies only, so the lines above and
+ * below do not count. All in em of the value's font size.
+ */
+const INK_SEARCH_INSIDE = 0.25;
+const WORD_GAP = 0.16;
+const MAX_GROWTH = 1;
+const INK_BAND_BELOW = 0.12;
+const INK_BAND_ABOVE = 0.68;
+/** A pixel is ink when its luminance is below this fraction of the paper's. */
+const INK_LUMINANCE = 0.65;
+/**
+ * Label size: the value's ink height (capitals and ascenders reach about 0.72 em) gives the
+ * label's em; without ink the OCR font size does, times LABEL_SIZE. The label is squeezed
+ * horizontally down to LABEL_MIN_SQUEEZE to fit the value's width, then shrunk.
+ */
+const INK_TOP_EM = 0.76;
+const LABEL_SIZE = 0.8;
+const LABEL_MIN_SQUEEZE = 0.6;
+const LABEL_FONT = '"Liberation Sans", Arial, Helvetica, sans-serif';
+/**
+ * Render page `index` at `options.dpi`, cover every mark in the paper colour
+ * around it and paint its label in the value's place: the baseline the OCR
+ * layer gives, the value's width (the label is squeezed, then shrunk, to fit;
+ * a shorter label leaves the rest of the width blank). Every cover is painted
+ * before any label, so a cover on the next line never clips a label above it.
+ * Returns the pixels, in gray when the page is gray (a scan usually is), so
+ * the writer can embed them losslessly at a size close to the original scan.
+ */
+export async function rasterizeScanPage(doc, index, marks, options) {
+    if (!(options.dpi > 0) || !Number.isFinite(options.dpi))
+        throw new RangeError(`invalid dpi ${options.dpi}`);
+    const page = await doc.render(index, options.dpi / 72, options.canvasFactory);
+    const ctx = page.canvas.context;
+    const before = page.canvas.getImageData();
+    const [a, b, c, d, e, f] = page.transform;
+    const toPx = (x, y) => [a * x + c * y + e, b * x + d * y + f];
+    // Measure every cover on the untouched pixels first.
+    const covers = marks.map((m) => {
+        const at = (along, up) => toPx(m.x + m.ux * along + m.vx * up, m.y + m.uy * along + m.vy * up);
+        const pad = COVER_PAD_ALONG * m.size;
+        const paper = paperColour(before, page.widthPx, page.heightPx, quadOf(at, -pad, m.length + pad, -COVER_BELOW * m.size, COVER_ABOVE * m.size));
+        const inkBelow = luminance(paper) * INK_LUMINANCE;
+        const along = inkExtent(before, page.widthPx, page.heightPx, at, m, inkBelow);
+        const start = Math.min(0, along.start) - pad;
+        const end = Math.max(m.length, along.end) + pad;
+        const rows = inkRows(before, page.widthPx, page.heightPx, at, m, start, end, inkBelow);
+        const onePx = 1 / (Math.hypot(...sub(at(0, 1), at(0, 0))) || 1);
+        const bottom = rows ? Math.min(-COVER_CORE_BELOW * m.size, rows.bottom - 1.5 * onePx) : -COVER_BELOW * m.size;
+        const top = rows ? Math.max(COVER_CORE_ABOVE * m.size, rows.top + 1.5 * onePx) : COVER_ABOVE * m.size;
+        const ink = rows ? inkColour(before, page.widthPx, page.heightPx, at, start, end, rows.bottom, rows.top, inkBelow) : null;
+        return { mark: m, at, start, end, bottom, top, inkTop: rows ? rows.top : null, paper, ink };
+    });
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalAlpha = 1;
+    ctx.globalCompositeOperation = 'source-over';
+    for (const cv of covers) {
+        const quad = quadOf(cv.at, cv.start, cv.end, cv.bottom, cv.top);
+        const fill = `rgb(${cv.paper[0]}, ${cv.paper[1]}, ${cv.paper[2]})`;
+        ctx.fillStyle = fill;
+        ctx.strokeStyle = fill;
+        ctx.lineWidth = 2; // the stroke grows the cover by a pixel on every side (anti-aliased glyph edges)
+        ctx.beginPath();
+        ctx.moveTo(quad[0][0], quad[0][1]);
+        for (let i = 1; i < 4; i++)
+            ctx.lineTo(quad[i][0], quad[i][1]);
+        ctx.closePath();
+        ctx.fill();
+        ctx.stroke();
+    }
+    for (const cv of covers) {
+        const m = cv.mark;
+        if (!m.label)
+            continue;
+        const pad = COVER_PAD_ALONG * m.size;
+        const [x0, y0] = cv.at(cv.start + pad, 0);
+        const [x1, y1] = cv.at(cv.start + pad + 1, 0);
+        const [xu, yu] = cv.at(cv.start + pad, 1);
+        const pxPerUnit = Math.hypot(x1 - x0, y1 - y0);
+        const pxPerUnitUp = Math.hypot(xu - x0, yu - y0);
+        const available = (cv.end - cv.start - 2 * pad) * pxPerUnit;
+        const em = cv.inkTop !== null && cv.inkTop > 0 ? cv.inkTop / INK_TOP_EM : LABEL_SIZE * m.size;
+        let fontPx = Math.min(em, 1.2 * m.size) * pxPerUnitUp;
+        if (!(fontPx > 0) || !(available > 0))
+            continue;
+        ctx.font = `${fontPx}px ${LABEL_FONT}`;
+        const natural = ctx.measureText(m.label).width;
+        let squeeze = natural > available ? available / natural : 1;
+        if (squeeze < LABEL_MIN_SQUEEZE) {
+            fontPx *= squeeze / LABEL_MIN_SQUEEZE;
+            squeeze = LABEL_MIN_SQUEEZE;
+            ctx.font = `${fontPx}px ${LABEL_FONT}`;
+        }
+        ctx.save();
+        ctx.translate(x0, y0);
+        ctx.rotate(Math.atan2(y1 - y0, x1 - x0));
+        ctx.scale(squeeze, 1);
+        ctx.fillStyle = cv.ink !== null ? `rgb(${cv.ink}, ${cv.ink}, ${cv.ink})` : luminance(cv.paper) > 0.45 ? '#000000' : '#ffffff';
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'alphabetic';
+        ctx.fillText(m.label, 0, 0);
+        ctx.restore();
+    }
+    ctx.restore();
+    const rgba = page.canvas.getImageData();
+    const { pixels, channels } = packPixels(rgba);
+    return { pixels, channels, widthPx: page.widthPx, heightPx: page.heightPx, widthPt: page.widthPt, heightPt: page.heightPt };
+}
+function sub(p, q) {
+    return [p[0] - q[0], p[1] - q[1]];
+}
+/** Pixel corners of the box [lo, hi] along the baseline by [bottom, top] across it. */
+function quadOf(at, lo, hi, bottom, top) {
+    return [at(lo, bottom), at(hi, bottom), at(hi, top), at(lo, top)];
+}
+/** Luminance (0..1) of the pixel under a baseline-frame point, or null off canvas. */
+function lumAt(rgba, width, height, p) {
+    const px = Math.round(p[0]);
+    const py = Math.round(p[1]);
+    if (px < 0 || py < 0 || px >= width || py >= height)
+        return null;
+    const i = (py * width + px) * 4;
+    return (0.2126 * rgba[i] + 0.7152 * rgba[i + 1] + 0.0722 * rgba[i + 2]) / 255;
+}
+/**
+ * Vertical extent of the value's ink (user units from the baseline): the block of inked rows
+ * across [start, end] that holds the letters' bodies, grown up and down until a blank row (the
+ * leading between lines), within INK_REACH_BELOW / INK_REACH_ABOVE. Null when no ink is there.
+ */
+export function inkRows(rgba, width, height, at, m, start, end, inkBelow) {
+    const pxAlong = Math.hypot(...sub(at(1, 0), at(0, 0)));
+    const pxUp = Math.hypot(...sub(at(0, 1), at(0, 0)));
+    if (!(pxAlong > 0) || !(pxUp > 0))
+        return null;
+    const stepAlong = 1 / pxAlong;
+    const stepUp = 1 / pxUp;
+    const rowHasInk = (up) => {
+        for (let along = start; along <= end; along += stepAlong) {
+            const lum = lumAt(rgba, width, height, at(along, up));
+            if (lum !== null && lum < inkBelow)
+                return true;
+        }
+        return false;
+    };
+    // Seed in the letters' bodies (every letter has ink between the baseline and the x-height).
+    let seed = null;
+    for (let up = 0.1 * m.size; up <= 0.45 * m.size; up += stepUp) {
+        if (rowHasInk(up)) {
+            seed = up;
+            break;
+        }
+    }
+    if (seed === null)
+        return null;
+    let top = seed;
+    for (let up = seed; up <= INK_REACH_ABOVE * m.size && rowHasInk(up); up += stepUp)
+        top = up;
+    let bottom = seed;
+    for (let up = seed; up >= -INK_REACH_BELOW * m.size && rowHasInk(up); up -= stepUp)
+        bottom = up;
+    return { bottom, top };
+}
+/**
+ * How far the ink of a value really reaches along its baseline (user units from the mark's
+ * start; `start` <= 0 and `end` >= length when the ink runs past the OCR layer's ends). Walks
+ * outwards pixel by pixel from inside the value and stops at the first blank gap of a word
+ * space, or after MAX_GROWTH.
+ */
+export function inkExtent(rgba, width, height, at, m, inkBelow) {
+    const [ox, oy] = at(0, 0);
+    const [ax, ay] = at(1, 0);
+    const pxPerUnit = Math.hypot(ax - ox, ay - oy);
+    if (!(pxPerUnit > 0))
+        return { start: 0, end: m.length };
+    const step = 1 / pxPerUnit; // one pixel along the baseline, in user units
+    const [bx, by] = at(0, INK_BAND_BELOW * -m.size);
+    const [tx, ty] = at(0, INK_BAND_ABOVE * m.size);
+    const bandPx = Math.max(1, Math.ceil(Math.hypot(tx - bx, ty - by)));
+    const isInk = (along) => {
+        for (let k = 0; k <= bandPx; k++) {
+            const up = -INK_BAND_BELOW * m.size + (k / bandPx) * (INK_BAND_ABOVE + INK_BAND_BELOW) * m.size;
+            const lum = lumAt(rgba, width, height, at(along, up));
+            if (lum !== null && lum < inkBelow)
+                return true;
+        }
+        return false;
+    };
+    const inside = Math.min(INK_SEARCH_INSIDE * m.size, m.length / 2);
+    const gap = WORD_GAP * m.size;
+    const reach = (from, dir, limit) => {
+        let last = from;
+        for (let along = from; dir > 0 ? along <= limit : along >= limit; along += dir * step) {
+            if (isInk(along))
+                last = along;
+            else if (Math.abs(along - last) >= gap)
+                break;
+        }
+        return last + dir * step;
+    };
+    return {
+        start: Math.min(0, reach(inside, -1, -MAX_GROWTH * m.size)),
+        end: Math.max(m.length, reach(m.length - inside, 1, m.length + MAX_GROWTH * m.size)),
+    };
+}
+/**
+ * Gray level (0..255) of the ink in the box [start, end] x [bottom, top]: the median luminance of
+ * its ink pixels, without their hue (a label never repeats the colour a value was printed in).
+ * Null without ink.
+ */
+function inkColour(rgba, width, height, at, start, end, bottom, top, inkBelow) {
+    const stepAlong = 1 / (Math.hypot(...sub(at(1, 0), at(0, 0))) || 1);
+    const stepUp = 1 / (Math.hypot(...sub(at(0, 1), at(0, 0))) || 1);
+    const levels = [];
+    for (let up = bottom; up <= top; up += stepUp) {
+        for (let along = start; along <= end; along += stepAlong) {
+            const [x, y] = at(along, up);
+            const px = Math.round(x);
+            const py = Math.round(y);
+            if (px < 0 || py < 0 || px >= width || py >= height)
+                continue;
+            const i = (py * width + px) * 4;
+            const level = 0.2126 * rgba[i] + 0.7152 * rgba[i + 1] + 0.0722 * rgba[i + 2];
+            if (level / 255 < inkBelow)
+                levels.push(level);
+        }
+    }
+    if (levels.length === 0)
+        return null;
+    return Math.round(levels.sort((p, q) => p - q)[levels.length >> 1]);
+}
+/**
+ * The paper colour around a cover: per-channel median of the pixels on a ring
+ * three pixels outside the quad's bounding box (mostly background, whatever
+ * text the ring crosses is a minority). White when the ring is off canvas.
+ */
+export function paperColour(rgba, width, height, quad) {
+    const xs = quad.map((p) => p[0]);
+    const ys = quad.map((p) => p[1]);
+    const left = Math.floor(Math.min(...xs)) - 3;
+    const right = Math.ceil(Math.max(...xs)) + 3;
+    const top = Math.floor(Math.min(...ys)) - 3;
+    const bottom = Math.ceil(Math.max(...ys)) + 3;
+    const channels = [[], [], []];
+    const take = (x, y) => {
+        if (x < 0 || y < 0 || x >= width || y >= height)
+            return;
+        const i = (y * width + x) * 4;
+        channels[0].push(rgba[i]);
+        channels[1].push(rgba[i + 1]);
+        channels[2].push(rgba[i + 2]);
+    };
+    for (let x = left; x <= right; x++) {
+        take(x, top);
+        take(x, bottom);
+    }
+    for (let y = top + 1; y < bottom; y++) {
+        take(left, y);
+        take(right, y);
+    }
+    if (channels[0].length === 0)
+        return [255, 255, 255];
+    const median = (v) => v.sort((p, q) => p - q)[v.length >> 1];
+    return [median(channels[0]), median(channels[1]), median(channels[2])];
+}
+function luminance(rgb) {
+    return (0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]) / 255;
+}
+/** RGBA canvas pixels to gray (every pixel has R = G = B) or RGB bytes; alpha is dropped (pdf.js paints an opaque page). */
+export function packPixels(rgba) {
+    const n = rgba.length >> 2;
+    let gray = true;
+    for (let i = 0; i < n; i++) {
+        const r = rgba[i * 4];
+        if (r !== rgba[i * 4 + 1] || r !== rgba[i * 4 + 2]) {
+            gray = false;
+            break;
+        }
+    }
+    if (gray) {
+        const pixels = new Uint8Array(n);
+        for (let i = 0; i < n; i++)
+            pixels[i] = rgba[i * 4];
+        return { pixels, channels: 1 };
+    }
+    const pixels = new Uint8Array(n * 3);
+    for (let i = 0; i < n; i++) {
+        pixels[i * 3] = rgba[i * 4];
+        pixels[i * 3 + 1] = rgba[i * 4 + 1];
+        pixels[i * 3 + 2] = rgba[i * 4 + 2];
+    }
+    return { pixels, channels: 3 };
+}

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

@@ -81,8 +81,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 +139,11 @@ 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;
     /** Flat-text range of the page. */
     textStart: number;
     textEnd: number;
@@ -171,9 +181,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 +194,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/write.d.ts

@@ -16,12 +16,15 @@
  *    attachments, JavaScript, named destinations, structure tree and the
  *    incremental-update history of the input never reach the output;
  * 6. pages that cannot be edited safely are rendered by pdf.js and replaced
- *    by an image with the redacted regions blacked out in the pixels;
+ *    by an image with the redacted regions blacked out in the pixels; scan
+ *    pages whose OCR text layer holds a redacted value are rendered at the
+ *    scan's resolution with each value covered and its placeholder painted in;
  * 7. verify the output with both extractors and a byte scan; refuse on any trace.
  */
 import type { ValueReplacement } from '../docx.js';
 import type { PageRecord } from './extract.js';
 import type { CanvasFactory, OracleDocument } from './oracle.js';
+import type { PaintMark } from './raster.js';
 import type { Segment } from './surgery.js';
 import type { GlyphRun, PdfWriteOptions, PdfWriteResult, Rect } from './types.js';
 import type { PdfExtraction } from './read.js';
@@ -41,6 +44,13 @@ interface Replacement {
     replacement: string;
 }
 export declare function writeAnonymizedPdfWithReport(extraction: PdfExtraction, replacements: Replacement[], valueReplacements?: ValueReplacement[], options?: PdfWriteOptionsInternal): Promise<PdfWriteResult>;
+/**
+ * Where each redacted value sits on a scan page, for painting: one mark per line a value
+ * occupies (the pieces of a value on one line, split across operators, join into one), the
+ * placeholder on the value's first line and a blank cover on the lines it wraps onto.
+ * Whitespace glyphs at either end of a piece are left out.
+ */
+export declare function paintMarksForPage(segments: Segment[], page: number, replacements: Replacement[]): PaintMark[];
 /**
  * Axis-aligned user-space boxes of every covered glyph on a page (for rasterization). On a page
  * whose text came from pdf.js, our own decoder's glyphs that spell a value are blacked out as

package/dist/pdf/write.js

@@ -16,10 +16,12 @@
  *    attachments, JavaScript, named destinations, structure tree and the
  *    incremental-update history of the input never reach the output;
  * 6. pages that cannot be edited safely are rendered by pdf.js and replaced
- *    by an image with the redacted regions blacked out in the pixels;
+ *    by an image with the redacted regions blacked out in the pixels; scan
+ *    pages whose OCR text layer holds a redacted value are rendered at the
+ *    scan's resolution with each value covered and its placeholder painted in;
  * 7. verify the output with both extractors and a byte scan; refuse on any trace.
  */
-import { PDFDict, PDFDocument, PDFName, PDFRawStream, PDFString } from '@cantoo/pdf-lib';
+import { PDFDict, PDFDocument, PDFName, PDFRawStream, PDFString, concatTransformationMatrix, drawObject, popGraphicsState, pushGraphicsState } from '@cantoo/pdf-lib';
 import { PDFRef } from '@cantoo/pdf-lib';
 import { UnsupportedDocumentError } from "../dom/errors.js";
 import { normalizeReplacements } from "../docx.js";
@@ -27,11 +29,15 @@ import { extractPdf } from "./extract.js";
 import { FallbackFontEmbedder, FallbackFontProvider, faceFor } from "./fallback-fonts.js";
 import { getDict, getStream, refOf, resolve } from "./objects.js";
 import { findOccurrences, openWithOracle, searchIndex } from "./oracle.js";
-import { rasterizePage } from "./raster.js";
+import { rasterizePage, rasterizeScanPage } from "./raster.js";
 import { serializeToUnicode } from "./cmap.js";
 import { planEdits, rewriteStream, segmentsFor } from "./surgery.js";
 import { PdfVerifyError, verifyPdf } from "./verify.js";
 import { lexContent } from "./lexer.js";
+/** Scan pages render at the scan's own resolution, up to this. */
+const MAX_SCAN_DPI = 300;
+/** Pixel budget of one rendered scan page (a 300 dpi A3 page fits; larger pages render coarser). */
+const MAX_SCAN_PIXELS = 40000000;
 /** Same normalised date the docx writer stamps. */
 export const NORMALISED_PDF_DATE = new Date('2000-01-01T00:00:00Z');
 export class StalePdfExtractionError extends Error {
@@ -112,13 +118,20 @@ export async function writeAnonymizedPdfWithReport(extraction, replacements, val
                 if (page.issues.length > 0 || page.oracleText)
                     rasterPages.add(page.index);
             }
+            // Scan pages: an edit in an OCR text layer would leave the value in the picture under it, so the
+            // page is rendered and the value painted over where the layer says it is.
+            const scanPages = new Set();
+            for (const s of segments)
+                if (s.run.ocr && !rasterPages.has(s.run.page))
+                    scanPages.add(s.run.page);
+            const paintedPages = new Set([...rasterPages, ...scanPages]);
             // Text in a pattern cell or soft-mask group cannot be blacked out in a raster (the cell is tiled
             // over its fill area, the group sits behind a mask): such a page must be edited in place or not at all.
-            const hostile = [...rasterPages].filter((p) => model.pages[p]?.hostile);
+            const hostile = [...paintedPages].filter((p) => model.pages[p]?.hostile);
             if (hostile.length > 0) {
                 throw new UnsupportedDocumentError('unredactable-parts', `pages ${hostile.map((p) => p + 1).join(', ')} hold content a viewer cannot render safely (rasterization refused)`, hostile.map((p) => `page ${p + 1}`));
             }
-            const rasterWithAux = [...rasterPages].filter((p) => segments.some((sg) => sg.run.page === p && sg.run.space));
+            const rasterWithAux = [...paintedPages].filter((p) => segments.some((sg) => sg.run.page === p && sg.run.space));
             if (rasterWithAux.length > 0) {
                 throw new UnsupportedDocumentError('unredactable-parts', `pages ${rasterWithAux.map((p) => p + 1).join(', ')} hold redacted text inside a pattern or soft mask and cannot be rasterized safely`, rasterWithAux.map((p) => `page ${p + 1}`));
             }
@@ -142,9 +155,9 @@ export async function writeAnonymizedPdfWithReport(extraction, replacements, val
                 const stream = model.streams.get(key);
                 if (!stream)
                     continue;
-                if ([...stream.pages].every((p) => rasterPages.has(p)))
+                if ([...stream.pages].every((p) => paintedPages.has(p)))
                     continue;
-                const segs = (plan.byStream.get(key) ?? []).filter((s) => !rasterPages.has(s.run.page));
+                const segs = (plan.byStream.get(key) ?? []).filter((s) => !paintedPages.has(s.run.page));
                 const result = rewriteStream(model, stream, runsByStreamOp.get(key) ?? new Map(), segs, plan.shiftedRuns);
                 for (const [k, codes] of result.usedCodes)
                     mergeCodes(usedCodes, k, codes);
@@ -167,12 +180,39 @@ export async function writeAnonymizedPdfWithReport(extraction, replacements, val
             scrubToUnicode(model, editedFonts, usedCodes, warnings);
             scrubSourceSideChannels(model);
             // 5. Rebuild into the fresh document.
-            const keptIndexes = model.pages.map((p) => p.index).filter((i) => !rasterPages.has(i));
+            const keptIndexes = model.pages.map((p) => p.index).filter((i) => !paintedPages.has(i));
             const copied = keptIndexes.length > 0 ? await outDoc.copyPages(model.doc, keptIndexes) : [];
             const copiedByIndex = new Map();
             keptIndexes.forEach((idx, k) => copiedByIndex.set(idx, copied[k]));
             const rasterized = [];
+            const scanned = [];
+            const sortedReplacements = [...all].sort((a, b) => a.start - b.start || a.end - b.end); // segmentsFor's order
             for (const page of model.pages) {
+                if (scanPages.has(page.index)) {
+                    const marks = paintMarksForPage(segments, page.index, sortedReplacements);
+                    let raster;
+                    try {
+                        raster = await rasterizeScanPage(oracle, page.index, marks, { dpi: scanDpi(page, options.rasterDpi), canvasFactory: options.canvasFactory });
+                    }
+                    catch (err) {
+                        throw new UnsupportedDocumentError('unredactable-parts', `page ${page.index + 1} cannot be rendered: ${err.message ?? String(err)}`, [`page ${page.index + 1}`]);
+                    }
+                    // Raw pixels in a Flate image (gray for a gray scan): lossless, and far smaller than an RGBA PNG.
+                    const image = outDoc.context.register(outDoc.context.flateStream(raster.pixels, {
+                        Type: 'XObject',
+                        Subtype: 'Image',
+                        Width: raster.widthPx,
+                        Height: raster.heightPx,
+                        ColorSpace: raster.channels === 1 ? 'DeviceGray' : 'DeviceRGB',
+                        BitsPerComponent: 8,
+                    }));
+                    const newPage = outDoc.addPage([raster.widthPt, raster.heightPt]);
+                    const name = newPage.node.newXObject('Scan', image);
+                    newPage.pushOperators(pushGraphicsState(), concatTransformationMatrix(raster.widthPt, 0, 0, raster.heightPt, 0, 0), drawObject(name), popGraphicsState());
+                    scanned.push(page.index);
+                    warnings.push(`page ${page.index + 1}: scan with an OCR text layer; the values are painted over in the picture with their placeholders and the page is exported as an image (its text layer is gone)`);
+                    continue;
+                }
                 if (rasterPages.has(page.index)) {
                     const boxes = boxesForPage(segments, page.index, fresh.runs, page, [...needles]);
                     const dpi = options.rasterDpi ?? 150;
@@ -217,7 +257,7 @@ export async function writeAnonymizedPdfWithReport(extraction, replacements, val
             scrubOutputObjects(outDoc);
             stampMetadata(outDoc);
             const bytes = await outDoc.save({ useObjectStreams: false, updateFieldAppearances: false, addDefaultPage: false });
-            return { bytes, needles: [...needles], removedSequences, rasterized, shiftedLines: plan.shiftedLines, removed: fresh.removed, placeholders: [...new Set(all.map((r) => r.replacement))] };
+            return { bytes, needles: [...needles], removedSequences, rasterized, scanned, shiftedLines: plan.shiftedLines, removed: fresh.removed, placeholders: [...new Set(all.map((r) => r.replacement))] };
         }
         finally {
             await oracle.close();
@@ -241,6 +281,7 @@ export async function writeAnonymizedPdfWithReport(extraction, replacements, val
         warnings: [...new Set(warnings)],
         removed: produced.removed,
         rasterizedPages: produced.rasterized,
+        scanPages: produced.scanned,
         shiftedLines: produced.shiftedLines,
     };
 }
@@ -550,6 +591,71 @@ function stampMetadata(outDoc) {
     outDoc.setCreationDate(NORMALISED_PDF_DATE);
     outDoc.setModificationDate(NORMALISED_PDF_DATE);
 }
+/** Resolution for a scan page: the scan's own (at least `base`, at most 300 dpi), within the pixel budget. */
+function scanDpi(page, base = 150) {
+    const dpi = Math.max(base, Math.min(MAX_SCAN_DPI, Math.round(page.imageDpi)));
+    const squareInches = Math.max(1e-6, (page.info.width / 72) * (page.info.height / 72));
+    return Math.max(36, Math.min(dpi, Math.floor(Math.sqrt(MAX_SCAN_PIXELS / squareInches))));
+}
+/**
+ * Where each redacted value sits on a scan page, for painting: one mark per line a value
+ * occupies (the pieces of a value on one line, split across operators, join into one), the
+ * placeholder on the value's first line and a blank cover on the lines it wraps onto.
+ * Whitespace glyphs at either end of a piece are left out.
+ */
+export function paintMarksForPage(segments, page, replacements) {
+    const marks = [];
+    let lastIndex = -1;
+    for (const s of segments) {
+        const run = s.run;
+        if (run.page !== page || run.space)
+            continue;
+        let from = s.from;
+        let to = s.to;
+        while (from < to && run.glyphs[from].unicode.trim() === '')
+            from++;
+        while (to > from && run.glyphs[to - 1].unicode.trim() === '')
+            to--;
+        if (from >= to)
+            continue;
+        const exLen = Math.hypot(run.emX[0], run.emX[1]) || 1;
+        const eyLen = Math.hypot(run.emY[0], run.emY[1]) || 1;
+        const ux = run.emX[0] / exLen;
+        const uy = run.emX[1] / exLen;
+        const vx = run.emY[0] / eyLen;
+        const vy = run.emY[1] / eyLen;
+        const scale = exLen / (run.local.fontSize * run.local.hscale || 1);
+        const first = run.glyphs[from];
+        let lo = 0;
+        let hi = 0;
+        let size = 0;
+        for (let i = from; i < to; i++) {
+            const g = run.glyphs[i];
+            const along = (g.x - first.x) * ux + (g.y - first.y) * uy;
+            lo = Math.min(lo, along);
+            hi = Math.max(hi, along + g.advance * scale);
+            size = Math.max(size, g.fontSize);
+        }
+        const x = first.x + ux * lo;
+        const y = first.y + uy * lo;
+        const prev = marks[marks.length - 1];
+        if (prev && s.replacementIndex === lastIndex) {
+            // Same value: join when this piece continues the previous one's line.
+            const across = (x - prev.x) * prev.vx + (y - prev.y) * prev.vy;
+            const along = (x - prev.x) * prev.ux + (y - prev.y) * prev.uy;
+            const lineSize = Math.max(prev.size, size);
+            if (Math.abs(across) < 0.4 * lineSize && along > -0.5 * lineSize && along < prev.length + 2 * lineSize) {
+                prev.length = Math.max(prev.length, along + (hi - lo));
+                prev.size = lineSize;
+                continue;
+            }
+        }
+        const label = s.replacementIndex === lastIndex ? '' : replacements[s.replacementIndex]?.replacement ?? '';
+        marks.push({ x, y, ux, uy, vx, vy, length: hi - lo, size, label });
+        lastIndex = s.replacementIndex;
+    }
+    return marks;
+}
 /**
  * Axis-aligned user-space boxes of every covered glyph on a page (for rasterization). On a page
  * whose text came from pdf.js, our own decoder's glyphs that spell a value are blacked out as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccloak/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Environment-agnostic document anonymization engine for the DocCloak ecosystem.",
   "license": "Apache-2.0",
   "author": "Witold Lojek",