@doccloak/core 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,183 @@ 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.15.0] - 2026-10-23
+
+0.14.1 was tagged but never published to npm, so this is the first release
+on npm after 0.14.0 and it carries the 0.14.1 changes too (listed under
+0.14.1 below). New `readPdf` options (`ocrImagePages`, `onOcrProgress`),
+hence the minor version; nothing a 0.14.0 host uses was removed.
+
+Each PDF page is handled by what it holds (T239). The founder's mixed scan
+had a picture page without any text layer between two OCR scans: its
+personal data came out untouched.
+
+- **Pages without a text layer are read with the host's OCR.** With a
+  `recognizeText`, `readPdf` reads a picture page that has no text at all on
+  the whole page (Tesseract's automatic segmentation only). A page with fewer
+  than three words read with 30 % confidence or more (a photo, a stamp,
+  noise) stays as it is, still listed as a scanned page. Otherwise every word
+  read is kept: Tesseract is least sure of elided words ("d'avril 2009",
+  "rachat d'actions"), and a word left out could be neither found nor
+  covered (seen on the issue file). A page read this way becomes a scan
+  with an OCR layer (`ocrText`, `PdfPageInfo.ocrWholePage` = the words
+  read): its values are detected, painted over in the picture and the page
+  keeps an invisible searchable layer. `ocrImagePages: false` turns this
+  off; without a host OCR nothing changes.
+- **Text inside images on text pages.** The coverage check now also runs on
+  text pages with images, with every glyph of the page's own layer as
+  covered, so only text the images show is found and read. A text page with
+  a value inside an image is painted (rendered at 300 dpi) like a scan; a
+  text page whose images hold no value stays vector text, edited in place.
+  Its note says "an image on the page shows text its text layer does not
+  have", and the generic "contains images; text inside images is not
+  scanned" is no longer given for the pages a host OCR checked.
+- **Values glued to an elision whose apostrophe OCR dropped.**
+  `propagateEntities` also finds a capitalised value right after a
+  lowercase "d", "l", "qu" and the other French and Italian elisions that
+  start a word ("dALTAMIR GERANCE", "lAltamir"); "McAltamir", "daltamir" and
+  "mALTAMIRE" are still left alone.
+- **A value inside an OCR word is covered from its first letter.** Where a
+  value starts or ends inside a word ("ALTAMIR" of "d'ALTAMIR"), the cover
+  ended in the valley between two letters nearest the OCR's estimate,
+  either way. Tesseract placed that "A" from its middle, the nearest valley
+  was the one after it, and the "A" stayed visible ("d'A[PERSON_13]"). The
+  valley is now looked for on the side away from the value only (up to
+  0.8 em out, 0.05 em in): at worst the cover takes one letter of the rest
+  of the word, never leaves one of the value.
+- **OCR progress.** `onOcrProgress(done, total)` reports the pages read so
+  far; the web app shows "page X of Y" while a scanned file loads.
+- **One Tesseract worker per file.** `recognizeCanvasLines` keeps its worker
+  between pages (`releaseOcrWorker()` ends it) and takes `wholePage`; word
+  confidences are passed on in `RecognizedLine`.
+- **The verifier no longer reads character codes in a font's ToUnicode map
+  as text.** The fallback font's map holds `<2019>` (the code of a closing
+  quote), so a detected year "2019" refused the export of the issue file. In
+  a CMap stream the hex strings are skipped; any other text in it is still
+  searched.
+- Tests: each page kind (a picture read whole and painted, its values
+  covered when the OCR is unsure of their words, a picture with only noise,
+  a mixed file, a text page with an image with and without a value, no host
+  OCR); a value glued to an elision; a value whose first letter the OCR
+  places half a letter late; a value in a CMap's hex codes and in its
+  comment.
+
+## [0.14.1] - 2026-10-22 (not published; shipped in 0.15.0)
+
+Two fixes found by the acceptance run of web 0.15.0 on the preview (T237).
+
+- **Long values on scans whose OCR letters are narrower than the print.** A
+  cover grew at most one em past the OCR layer's end. A layer 15 % narrower
+  than the print ends about 2 em short of a 13 em e-mail address, so its
+  last letters (".com") stayed visible. The cover may now grow by one em or
+  35 % of the value's length, whichever is more, still stopping at the first
+  word space. Measured on synthetic scans with two long values: clean down to
+  OCR letters at 75 % of the print's width (at 70 % a fragment remains).
+- **The verifier no longer searches picture pixels for values.** It scanned
+  the decoded bytes of every stream not compressed with an image codec,
+  pixels of Flate pictures included, so a short value (the street number
+  "36") could match two neighbouring gray levels (51, 54) by chance and
+  refuse the export. Painted scan pages are such pictures, and so are Flate
+  logos and scans in any PDF. Image samples are skipped; the image
+  dictionary's strings are still searched.
+- Tests: a long e-mail on the narrow-OCR scan; the verifier ignores a value's
+  bytes in an image's samples and finds them in the image dictionary and in
+  another stream.
+
+Found by the next preview runs on real Tesseract scans (T238):
+
+- **Values ending at punctuation glued to them in an OCR word.** Tesseract
+  gives every glyph of its invisible font the same width, so a value that
+  stops before glued punctuation ("+48 527 870 616," "12/4,") ended at a
+  guessed point inside its last letter, and the cover's growth stopped at the
+  0.23 em gap after a narrow "1": half of the last digit stayed visible.
+  Glued punctuation is now covered with the value, so the cover ends where
+  the OCR word does, and painted again around the placeholder
+  ("[PHONE_1]," "([PHONE_1])."), so the picture reads like the redacted
+  text; on the line a value wraps onto, at the end of that line's cover,
+  where it was printed.
+- **Diacritics standing apart above a value.** The cover's height follows
+  the letters' ink up to the first blank row, so the dot of "Ż" in
+  "Krzysztof Żółć" (and an accent over a word without ascenders) stayed in
+  the picture above the label. Small marks just above the letters that do
+  not run on into the line above get a cover of their own.
+- **Short values' labels use the blank paper next to them.** A placeholder
+  never took more room than its value, so the label for "ul." or "Kraków,"
+  was squeezed and shrunk until it was hard to read. It now first takes the
+  blank paper after the value, then before it (a right-aligned line), up to
+  a word space before the next ink, half the gap to the next value on the
+  line and never outside the text column (where the page's OCR words start
+  and end, a margin note or a stamp left out), so a label never grows into
+  the margin. Values with no room on either side keep the squeezed label;
+  the text layer holds every placeholder in full.
+- **Table rules the OCR read as "|" no longer hide a cell's word from
+  detection.** "|Kraków" (a vertical rule glued to the city in a scanned
+  table) was missed by the model while the same city without the rule was
+  found. On OCR text those characters read as spaces in the flat text, one
+  for one, so every offset still maps to its glyph (the layer keeps them).
+- **Polish street addresses take in the flat number** (`regex:pl:street`):
+  "ul. Słoneczna 7 m. 12" and "al. Jerozolimskie 44 lok. 3B" match whole. On
+  a scan of a letter the model found "ul. Słoneczna 7" without "m. 12",
+  which stayed in the picture; the text PDF of the same letter got all of it.
+- **Tesseract stretches each word with its trailing space.** Its shows hold
+  the word and a space, stretched together over the word's box, so a word's
+  last letter reaches past its own advance (the "7" of "31-147" stuck out).
+  When only whitespace follows a value in an OCR show, the end of the show
+  bounds where the value's ink may be (`PaintMark.reach`): ink up to there is
+  covered across gaps; in layers that are not stretched that space is blank
+  and nothing more is covered.
+- **Text a scan's OCR layer does not have is reported.** A table or a stamp
+  the OCR could not read is not in the layer, so it cannot be found and stays
+  in the picture. `readPdf` now renders each page with OCR text at 100 dpi
+  and looks for rows of letter-sized ink that no OCR glyph covers
+  (`src/pdf/coverage.ts`); it sets `PdfPageInfo.ocrMissingLines` and adds a
+  warning. Rules, frames, signatures and pictures are larger than letters and
+  never count, nor do single marks or rows shorter than 2 em. Calibrated on
+  the scans of the acceptance run: the two tables Tesseract could not read
+  are reported, the court judgment (signature, stamp) and complete scans are
+  not. Options: `checkOcrCoverage` (default true), `canvasFactory` for Node
+  hosts; without a canvas the check is skipped.
+- **Hosts can read that text with their own OCR.** `readPdf` takes an
+  optional `recognizeText(canvas, region)`: the page rendered at 300 dpi and
+  the region around the missing lines. The words it returns (lines with
+  baselines and letter boxes) that do not lie under the layer's own glyphs
+  join the page as hidden OCR runs after its text (`PdfPageInfo.ocrReadWords`,
+  `PdfExtraction.extraOcr`); the writer re-creates the same runs, so their
+  values are detected and painted like the layer's. `@doccloak/core/dom`
+  adds `recognizeCanvasLines`, which tries Tesseract's automatic,
+  single-column and single-block segmentation on the crop and keeps the
+  reading with the most letters (the same crop reads in one mode and gives
+  nothing in another). The tables Tesseract garbled on full pages read
+  cleanly this way. The region reaches 2.5 em above and below the missing
+  lines: a row whose only OCR text is junk ("[miesiąc | opowiezany ema Je |")
+  looks covered and is never reported missing itself. A word read there is
+  dropped only when the layer's glyphs under it spell about the same word
+  (60 % of the letters in order); under junk it is added.
+- **Values inside a longer OCR word.** In a Tesseract word ("2026/03/017")
+  the letters of a value that is only part of it are placed by Helvetica
+  proportions over the printed word, and the cover ends in the blank gap
+  between two letters nearest that point, with a pixel of margin: "2026" of
+  "2026/03/017" leaves "/03/017" whole (before, the cover grew through "/0").
+- **Painted scan pages stay searchable.** Their text, every redacted value
+  replaced by its placeholder, is written as an invisible layer (render mode
+  3, Liberation Sans) over the picture: each run on its own baseline,
+  stretched to its original width, so search and selection work as on the
+  input and sit over the printed words, on rotated pages too (the layer is
+  mapped through the same transform that placed the page in the picture).
+  A placeholder spans its whole value even when the OCR wrote the value as
+  several shows (Tesseract: one per word), and the punctuation after it
+  follows on the same line ("Telefon: [PHONE_1], e-mail").
+  The verifier reads the new layer like any text.
+- The stretched-space reach applies only to shows whose glyphs all have the
+  same advance (Tesseract's invisible font): in a layer set in a real font
+  the trailing space is the gap before the next word, and the cover took in
+  the next word's first letter.
+- Tests: glued punctuation and the Tesseract word reach (unit, fail without
+  the fixes), a Tesseract-style synthetic layer (one show per word with its
+  trailing space, equal letter widths, values red with black punctuation),
+  the missing-text finder (unit) and `readPdf` on a scan with a line the
+  layer lacks.
+
 ## [0.14.0] - 2026-10-22
 
 Scanned PDF pages with an OCR text layer are redacted where a reader sees

package/README.md

@@ -255,15 +255,39 @@ 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.
+value's ink and fitted to the value's width, taking blank paper beside a
+short value first (then squeezed, then shrunk). The
+page is exported as a lossless image (gray for a gray scan) with an invisible
+text layer holding its text, the placeholders in place of the values, so it
+stays searchable, and listed in `scanPages`. Pages of the same file without any text are
+not touched. Text the OCR layer does not have (a table or a stamp the OCR
+could not read) cannot be found, so it stays in the picture: `readPdf`
+renders each scan page with OCR text at 100 dpi, looks for rows of
+letter-sized ink no OCR glyph covers and reports them in
+`PdfPageInfo.ocrMissingLines` and `warnings` (`checkOcrCoverage: false` turns
+the check off; Node hosts pass a `canvasFactory`, without one it is skipped).
+A host with OCR passes `recognizeText(canvas, region)` (the web app hands in
+Tesseract through `recognizeCanvasLines` from `@doccloak/core/dom`): the
+words it reads there join the page as OCR text (`ocrReadWords`), and their
+values are found and painted over like the rest.
+
+**Each page by what it holds.** With a host OCR, a page that is only a
+picture (no text layer at all) is read whole with Tesseract's automatic
+segmentation. With fewer than three words read at 30 % confidence or more
+the page stays as it is; otherwise every word read is kept, the unsure ones
+too (`PdfPageInfo.ocrWholePage` gives the count).
+A page read this way is handled as a scan with an OCR layer, so a file can
+mix vector text pages, OCR scans and pictures, each redacted its own way. Text
+pages with images get the same coverage check, with the page's own glyphs
+counted as covered: text that only an image shows is read, and a text page
+with a value in an image is exported painted, like a scan; without such a
+value it stays vector text. `ocrImagePages: false` turns the whole-page
+reading off, and `onOcrProgress(done, total)` reports the pages read.
 
 **Refusals.** Encrypted files (`'encrypted'`, pass `password`), files over
 50 MB or 500 pages (`'too-large'`), non-PDF bytes (`'invalid-package'`).
-Scanned pages without a text layer (no OCR) and text no decoder can read are
-reported in `unredactable` (`'scanned-page'`, `'undecodable-text'`) and gate
+Scanned pages without a text layer (no OCR, and none the host's OCR could
+read) and text no decoder can read are reported in `unredactable` (`'scanned-page'`, `'undecodable-text'`) and gate
 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`.
@@ -318,7 +342,8 @@ Independently of what was detected, every exported .docx / .xlsx has:
   encoding names); a placeholder is never drawn with a Type3 font unless the
   font itself showed every character of it. Digital signatures are
   invalidated by any change.
-- Images are copied unchanged; text inside pictures is not OCR-scanned.
+- Images are copied unchanged. Without a host OCR, text inside pictures is
+  not OCR-scanned; with one, see "Each page by what it holds" above.
 - Forms, annotations, bookmarks and attachments are dropped, not redacted.
 - Right-to-left text: pdf.js reports it in visual order, so the cross-check
   compares the characters of such pages as a set; detection runs on our
@@ -407,7 +432,7 @@ interface CoreEnv {
   fetch: typeof fetch;            // injectable for tests/proxies
   wasm: { paths: string; numThreads?: number };  // onnxruntime-web asset location
   buildTokenizer?(tokenizerJson: unknown, tokenizerConfig: unknown): unknown | Promise<unknown>;
-  /** @deprecated since 0.12.0, removal planned for 0.14.0; used only when buildTokenizer is absent */
+  /** @deprecated since 0.12.0, removal planned for a later release; used only when buildTokenizer is absent */
   loadTokenizer?(hfModelId: string): Promise<unknown>;
   hardware?: HardwareHints;       // deviceMemoryGB / isMobile, feeds provider default
   persistStorage?: () => Promise<boolean>;  // e.g. navigator.storage.persist()
@@ -444,7 +469,7 @@ are the three pinned `resolve/<commit>/...` files of the active provider.
 `loadTokenizer(hfModelId)` (0.11 and earlier) is still honoured in 0.13.0
 when `buildTokenizer` is absent, with a one-time deprecation warning. It
 lets the host library probe the mutable `resolve/main` branch and keep an
-unverified second cache, so migrate now: the removal is planned for 0.14.0,
+unverified second cache, so migrate now: the removal is planned for a later release,
 where `buildTokenizer` becomes required.
 
 ### autoLoad and ModelNotLoadedError

package/dist/dom/ocr.d.ts

@@ -61,6 +61,47 @@ export declare function loadImageToCanvas(file: Blob): Promise<OcrCanvas>;
  * TesseractAssetPaths). onProgress receives 0..1 during the recognition phase.
  */
 export declare function recognizeCanvas(canvas: OcrCanvas, uiLanguage: string, assets: TesseractAssetPaths, onProgress?: (progress: number) => void): Promise<OcrExtraction>;
+/** One line Tesseract read: its baseline and words, each word with its letters' boxes (pixels) and its confidence (0..100). */
+export interface OcrLine {
+    baseline: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    words: Array<{
+        text: string;
+        bbox: {
+            x0: number;
+            y0: number;
+            x1: number;
+            y1: number;
+        };
+        confidence?: number;
+        symbols: Array<{
+            text: string;
+            bbox: {
+                x0: number;
+                y0: number;
+                x1: number;
+                y1: number;
+            };
+        }>;
+    }>;
+}
+/** Terminate the worker recognizeCanvasLines keeps between calls (after the last page of a document). */
+export declare function releaseOcrWorker(): Promise<void>;
+/**
+ * OCR a canvas holding part of a page and return its lines with baselines, words and letter
+ * boxes. Used on the parts of a scanned PDF page whose OCR layer has no text: cropped to such a
+ * part, a table that full-page segmentation turned into junk reads cleanly. Tesseract's page
+ * segmentation is picky about a crop (the same table reads in one mode and gives nothing in
+ * another), so the automatic, single-column and single-block modes are tried in turn and the
+ * reading with the most letters wins.
+ */
+export declare function recognizeCanvasLines(canvas: OcrCanvas, uiLanguage: string, assets: TesseractAssetPaths, dpi?: number, options?: {
+    wholePage?: boolean;
+}): Promise<OcrLine[]>;
 interface BlockLike {
     paragraphs: {
         lines: {

package/dist/dom/ocr.js

@@ -139,6 +139,84 @@ export async function recognizeCanvas(canvas, uiLanguage, assets, onProgress) {
         await worker.terminate();
     }
 }
+/**
+ * One Tesseract worker for the pages of a document: starting one loads the engine and the language
+ * data, which costs about a second, so the pages of a PDF are read by the same worker. The host
+ * releases it when the document is read (releaseOcrWorker).
+ */
+let shared = null;
+function sharedWorker(langs, assets) {
+    const key = `${langs.join('+')}|${assets.workerPath}|${assets.corePath}|${assets.langPath}`;
+    if (shared && shared.key === key)
+        return shared.worker;
+    void releaseOcrWorker();
+    const worker = Tesseract.createWorker(langs, 1, { workerPath: assets.workerPath, corePath: assets.corePath, langPath: assets.langPath });
+    shared = { key, worker };
+    // A worker that failed to start is not kept: the next call tries again.
+    worker.catch(() => { if (shared?.worker === worker)
+        shared = null; });
+    return worker;
+}
+/** Terminate the worker recognizeCanvasLines keeps between calls (after the last page of a document). */
+export async function releaseOcrWorker() {
+    const current = shared;
+    shared = null;
+    if (!current)
+        return;
+    try {
+        await (await current.worker).terminate();
+    }
+    catch {
+        /* never started, or already gone */
+    }
+}
+/**
+ * OCR a canvas holding part of a page and return its lines with baselines, words and letter
+ * boxes. Used on the parts of a scanned PDF page whose OCR layer has no text: cropped to such a
+ * part, a table that full-page segmentation turned into junk reads cleanly. Tesseract's page
+ * segmentation is picky about a crop (the same table reads in one mode and gives nothing in
+ * another), so the automatic, single-column and single-block modes are tried in turn and the
+ * reading with the most letters wins.
+ */
+export async function recognizeCanvasLines(canvas, uiLanguage, assets, dpi, options = {}) {
+    const worker = await sharedWorker(buildLangList(uiLanguage), assets);
+    let best = [];
+    let bestLetters = 0;
+    // A whole page is what automatic segmentation is made for; the other modes are for crops.
+    const modes = options.wholePage ? [Tesseract.PSM.AUTO] : [Tesseract.PSM.AUTO, Tesseract.PSM.SINGLE_COLUMN, Tesseract.PSM.SINGLE_BLOCK];
+    for (const mode of modes) {
+        // The resolution is known (a rendered page): Tesseract does not have to guess it (and log the guess).
+        await worker.setParameters({ tessedit_pageseg_mode: mode, ...(dpi ? { user_defined_dpi: String(Math.round(dpi)) } : {}) });
+        const { data } = await worker.recognize(canvas, {}, { blocks: true });
+        const lines = linesOf(data.blocks ?? []);
+        const letters = lines.reduce((n, l) => n + l.words.reduce((m, w) => m + w.text.length, 0), 0);
+        if (letters > bestLetters) {
+            best = lines;
+            bestLetters = letters;
+        }
+    }
+    return best;
+}
+function linesOf(blocks) {
+    const lines = [];
+    for (const block of blocks) {
+        for (const paragraph of block.paragraphs ?? []) {
+            for (const line of paragraph.lines ?? []) {
+                const words = (line.words ?? [])
+                    .filter((w) => (w.text ?? '').trim() !== '')
+                    .map((w) => ({
+                    text: (w.text ?? '').trim(),
+                    bbox: w.bbox,
+                    ...(typeof w.confidence === 'number' ? { confidence: w.confidence } : {}),
+                    symbols: (w.symbols ?? []).filter((x) => (x.text ?? '').trim() !== '').map((x) => ({ text: x.text ?? '', bbox: x.bbox })),
+                }));
+                if (words.length > 0)
+                    lines.push({ baseline: line.baseline, words });
+            }
+        }
+    }
+    return lines;
+}
 /**
  * Reconstruct plain text from Tesseract's block hierarchy while recording
  * each word's character range. The reconstruction (not Tesseract's own

package/dist/env.d.ts

@@ -46,7 +46,7 @@ export interface CoreEnv {
      */
     buildTokenizer?(tokenizerJson: unknown, tokenizerConfig: unknown): unknown | Promise<unknown>;
     /**
-     * @deprecated since 0.12.0, removal planned for 0.14.0. Used only when
+     * @deprecated since 0.12.0, removal planned for a later release. Used only when
      * buildTokenizer is absent. Loading by Hugging Face model id lets the
      * host library probe mutable `resolve/main` and keep an unverified
      * second cache (security report S1/S3); implement buildTokenizer.

package/dist/pdf/coverage.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @doccloak/core/pdf - text in a scan that its OCR layer does not have (T238).
+ *
+ * A scan page is redacted through its OCR text layer: what the layer does not
+ * hold (a table the OCR could not read, a stamp, a margin note) cannot be
+ * found, so it stays in the picture. This module finds such places so the
+ * reader can say so. It works on the rendered page: ink is grouped into
+ * letter-sized shapes, shapes that no OCR glyph box covers are grouped into
+ * lines, and a line of several such shapes is text the layer does not have.
+ * Rules, frames, signatures and pictures are larger than letters and never
+ * count; single marks (a page number, a tick) are too short to form a line.
+ */
+import type { GlyphRun } from './types.js';
+/** Pixel box, top-left origin, inclusive start and exclusive end. */
+export interface PxBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** A line of text-like ink no OCR glyph covers. */
+export interface MissingLine extends PxBox {
+    /** Letter-sized shapes on the line. */
+    shapes: number;
+}
+/**
+ * Lines of text-like ink in `rgba` (width x height, RGBA) that none of
+ * `ocrBoxes` covers. `emPx` is the page's typical OCR text size in pixels.
+ */
+export declare function findTextWithoutOcr(rgba: Uint8ClampedArray, width: number, height: number, ocrBoxes: PxBox[], emPx: number): MissingLine[];
+/**
+ * Pixel boxes of every OCR glyph on `page` (runs marked `ocr`; with `allText`, every glyph of the
+ * page's text layer), from 0.3 em below the baseline to 0.9 em above it, through the render
+ * transform [a b c d e f]; and the median glyph size in pixels (the page's text size, the scale
+ * every rule above is measured in).
+ */
+export declare function ocrGlyphBoxes(runs: GlyphRun[], page: number, transform: number[], allText?: boolean): {
+    boxes: PxBox[];
+    chars: string[];
+    emPx: number;
+};

package/dist/pdf/coverage.js

@@ -0,0 +1,193 @@
+/**
+ * @doccloak/core/pdf - text in a scan that its OCR layer does not have (T238).
+ *
+ * A scan page is redacted through its OCR text layer: what the layer does not
+ * hold (a table the OCR could not read, a stamp, a margin note) cannot be
+ * found, so it stays in the picture. This module finds such places so the
+ * reader can say so. It works on the rendered page: ink is grouped into
+ * letter-sized shapes, shapes that no OCR glyph box covers are grouped into
+ * lines, and a line of several such shapes is text the layer does not have.
+ * Rules, frames, signatures and pictures are larger than letters and never
+ * count; single marks (a page number, a tick) are too short to form a line.
+ */
+/** A pixel is ink when its luminance is below this fraction of the paper's. */
+const INK_LUMINANCE = 0.6;
+/** Letter-sized: height within these multiples of the page's OCR text size (em, in pixels). */
+const SHAPE_MIN_HEIGHT = 0.25;
+const SHAPE_MAX_HEIGHT = 1.6;
+const SHAPE_MAX_WIDTH = 2.5;
+/** A shape counts as covered when this share of its box lies under an OCR glyph box. */
+const COVERED_SHARE = 0.3;
+/** Shapes join a line when their centres are this close vertically and the gap between them this small (em). */
+const LINE_SAME_ROW = 0.45;
+const LINE_MAX_GAP = 1.2;
+/** A line needs this many shapes and this width (em): a short word, never a lone mark or the tip of a covered word. */
+const LINE_MIN_SHAPES = 5;
+const LINE_MIN_WIDTH = 2;
+/**
+ * Lines of text-like ink in `rgba` (width x height, RGBA) that none of
+ * `ocrBoxes` covers. `emPx` is the page's typical OCR text size in pixels.
+ */
+export function findTextWithoutOcr(rgba, width, height, ocrBoxes, emPx) {
+    if (!(emPx >= 4) || width <= 0 || height <= 0)
+        return [];
+    const n = width * height;
+    const paper = paperLuminance(rgba, n);
+    const ink = new Uint8Array(n);
+    for (let i = 0; i < n; i++) {
+        const lum = 0.2126 * rgba[i * 4] + 0.7152 * rgba[i * 4 + 1] + 0.0722 * rgba[i * 4 + 2];
+        if (lum < paper * INK_LUMINANCE)
+            ink[i] = 1;
+    }
+    // Coverage: every OCR glyph box, grown by a third of an em (layers sit a little off the print).
+    const covered = new Uint8Array(n);
+    const grow = Math.round(emPx / 3);
+    for (const b of ocrBoxes) {
+        const x0 = Math.max(0, Math.floor(b.x0) - grow);
+        const x1 = Math.min(width, Math.ceil(b.x1) + grow);
+        const y0 = Math.max(0, Math.floor(b.y0) - grow);
+        const y1 = Math.min(height, Math.ceil(b.y1) + grow);
+        for (let y = y0; y < y1; y++)
+            covered.fill(1, y * width + x0, y * width + x1);
+    }
+    const shapes = letterShapes(ink, covered, width, height, emPx);
+    return groupLines(shapes, emPx);
+}
+/** Median luminance of a sample of pixels: the paper, on any page that is mostly paper. */
+function paperLuminance(rgba, n) {
+    const sample = [];
+    const step = Math.max(1, Math.floor(n / 20000));
+    for (let i = 0; i < n; i += step)
+        sample.push(0.2126 * rgba[i * 4] + 0.7152 * rgba[i * 4 + 1] + 0.0722 * rgba[i * 4 + 2]);
+    sample.sort((a, b) => a - b);
+    return sample[sample.length >> 1] || 255;
+}
+/** Connected ink components (4-neighbour) that are letter-sized and not covered by the OCR layer. */
+function letterShapes(ink, covered, width, height, emPx) {
+    const label = new Int32Array(width * height);
+    const out = [];
+    const stack = [];
+    let next = 0;
+    for (let start = 0; start < ink.length; start++) {
+        if (!ink[start] || label[start])
+            continue;
+        next++;
+        label[start] = next;
+        stack.push(start);
+        let x0 = width, y0 = height, x1 = 0, y1 = 0, count = 0, under = 0;
+        while (stack.length > 0) {
+            const p = stack.pop();
+            const x = p % width;
+            const y = (p - x) / width;
+            count++;
+            if (covered[p])
+                under++;
+            if (x < x0)
+                x0 = x;
+            if (x > x1)
+                x1 = x;
+            if (y < y0)
+                y0 = y;
+            if (y > y1)
+                y1 = y;
+            if (x > 0 && ink[p - 1] && !label[p - 1]) {
+                label[p - 1] = next;
+                stack.push(p - 1);
+            }
+            if (x < width - 1 && ink[p + 1] && !label[p + 1]) {
+                label[p + 1] = next;
+                stack.push(p + 1);
+            }
+            if (y > 0 && ink[p - width] && !label[p - width]) {
+                label[p - width] = next;
+                stack.push(p - width);
+            }
+            if (y < height - 1 && ink[p + width] && !label[p + width]) {
+                label[p + width] = next;
+                stack.push(p + width);
+            }
+        }
+        const h = y1 - y0 + 1;
+        const w = x1 - x0 + 1;
+        if (h < SHAPE_MIN_HEIGHT * emPx || h > SHAPE_MAX_HEIGHT * emPx || w > SHAPE_MAX_WIDTH * emPx)
+            continue;
+        if (count < 3 || under / count >= COVERED_SHARE)
+            continue;
+        out.push({ x0, y0, x1: x1 + 1, y1: y1 + 1, cx: (x0 + x1) / 2, cy: (y0 + y1) / 2 });
+    }
+    return out;
+}
+/** Shapes on one row, each close to the next, as lines; only lines of LINE_MIN_SHAPES or more. */
+function groupLines(shapes, emPx) {
+    const sorted = [...shapes].sort((a, b) => a.cy - b.cy || a.x0 - b.x0);
+    const rows = [];
+    for (const s of sorted) {
+        const row = rows.find((r) => Math.abs(r[0].cy - s.cy) <= LINE_SAME_ROW * emPx);
+        if (row)
+            row.push(s);
+        else
+            rows.push([s]);
+    }
+    const lines = [];
+    for (const row of rows) {
+        row.sort((a, b) => a.x0 - b.x0);
+        let run = [];
+        const flush = () => {
+            const x0 = Math.min(...run.map((s) => s.x0));
+            const x1 = Math.max(...run.map((s) => s.x1));
+            if (run.length >= LINE_MIN_SHAPES && x1 - x0 >= LINE_MIN_WIDTH * emPx) {
+                lines.push({ x0, y0: Math.min(...run.map((s) => s.y0)), x1, y1: Math.max(...run.map((s) => s.y1)), shapes: run.length });
+            }
+            run = [];
+        };
+        for (const s of row) {
+            if (run.length > 0 && s.x0 - run[run.length - 1].x1 > LINE_MAX_GAP * emPx)
+                flush();
+            run.push(s);
+        }
+        flush();
+    }
+    return lines;
+}
+/**
+ * Pixel boxes of every OCR glyph on `page` (runs marked `ocr`; with `allText`, every glyph of the
+ * page's text layer), from 0.3 em below the baseline to 0.9 em above it, through the render
+ * transform [a b c d e f]; and the median glyph size in pixels (the page's text size, the scale
+ * every rule above is measured in).
+ */
+export function ocrGlyphBoxes(runs, page, transform, allText = false) {
+    const [a, b, c, d, e, f] = transform;
+    const scale = Math.hypot(a, b) || 1;
+    const boxes = [];
+    const chars = [];
+    const sizes = [];
+    for (const run of runs) {
+        if (run.page !== page || run.space || (!allText && !run.ocr))
+            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 k = exLen / (run.local.fontSize * run.local.hscale || 1);
+        for (const g of run.glyphs) {
+            if (g.unicode.trim() === '')
+                continue;
+            const w = g.advance * k;
+            const xs = [];
+            const ys = [];
+            for (const [along, up] of [[0, -0.3], [w, -0.3], [w, 0.9], [0, 0.9]]) {
+                const x = g.x + ux * along + vx * up * g.fontSize;
+                const y = g.y + uy * along + vy * up * g.fontSize;
+                xs.push(a * x + c * y + e);
+                ys.push(b * x + d * y + f);
+            }
+            boxes.push({ x0: Math.min(...xs), y0: Math.min(...ys), x1: Math.max(...xs), y1: Math.max(...ys) });
+            chars.push(g.unicode);
+            sizes.push(g.fontSize * scale);
+        }
+    }
+    sizes.sort((p, q) => p - q);
+    return { boxes, chars, emPx: sizes[sizes.length >> 1] ?? 0 };
+}

package/dist/pdf/extract.d.ts

@@ -17,7 +17,7 @@ import type { PDFContext } from './objects.js';
 import { PDFDict, PDFRef, PDFStream } from './objects.js';
 import type { ContentOp } from './lexer.js';
 import type { LoadedFont } from './fonts.js';
-import type { GlyphRun, PdfPageInfo, RemovedPart } from './types.js';
+import type { ExtraOcrPage, GlyphRun, PdfPageInfo, RemovedPart } from './types.js';
 import type { UnredactablePart } from '../dom/errors.js';
 import type { OracleDocument } from './oracle.js';
 /** One content stream we may rewrite: page contents (joined) or a form XObject. */
@@ -89,6 +89,12 @@ export interface ExtractOptions {
      * taken from the oracle (so detection still sees what a viewer shows).
      */
     oracle?: OracleDocument;
+    /**
+     * Text DocCloak read itself where a scan page's OCR layer had none (readPdf's recognizeText): its
+     * words join the page as hidden OCR runs after the page's own text, so the reader and the writer
+     * build the same flat text from the same bytes.
+     */
+    extraOcr?: ExtraOcrPage[];
 }
 export declare const DEFAULT_MAX_BYTES: number;
 export declare const DEFAULT_MAX_PAGES = 500;