@scanmate/ocr 0.0.2

package/dist/src/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `@scanmate/ocr` - how closely a scan's text matches the original's.
+ *
+ * ```ts
+ * import { ocrPages } from '@scanmate/ocr'
+ *
+ * const report = await ocrPages(alignedPages)          // or enhanced pages
+ * report.score                                          // the document, 0-1
+ * report.pages[0].metrics.wordRecall                    // one of ten measures
+ * report.pages[0].differences                           // what differs, and where
+ * report.pages[0].original.text                         // both texts, in full
+ * report.pages[0].scanned.text
+ * ```
+ *
+ * The original's text is its text layer when it has one: exact, so every error
+ * is the scan's. The scan is read with tesseract - WebAssembly, offline, with
+ * nothing written to disk unless configured to be. Its words are placed back on
+ * the original's canvas and matched run by run to what the original printed
+ * there, so reading order never counts as a difference and every difference
+ * has a place on the page.
+ *
+ * Text is normalised before it is compared: Unicode compatibility forms,
+ * typography, line-end hyphens, diacritics, case, and OCR noise.
+ */
+export { ocrPages } from './page-reading/index.js';
+export type { OcrOptions, OcrReport, PageOcr, PlacedText, PositionedText, ReadablePage, RunReading, SideText, TextDifference } from './page-reading/index.js';
+export { createTesseractEngine, DEFAULT_TESSERACT_OPTIONS } from './ocr-engine/index.js';
+export type { OcrEngine, OcrLine, OcrWord, RecognisedText, RecogniseHints, TesseractCacheOptions, TesseractEngine, TesseractEngineOptions, TesseractSettings } from './ocr-engine/index.js';
+export { compareTexts } from './text-similarity/index.js';
+export type { ScoreMetric, TextMetrics } from './text-similarity/index.js';
+export { DEFAULT_NORMALISE, normaliseText, tokenise } from './text-normalisation/index.js';
+export type { NormaliseOptions } from './text-normalisation/index.js';
+export { claimWords, DEFAULT_RECHECK_PASSES, judgeRun, judgeRuns, matchWords, recheckRun } from './page-reading/index.js';
+export type { Claims, MatchOptions, Recheck, RecheckOptions, RecheckPass, Reference, Verdict, WordMatch } from './page-reading/index.js';
+export { cosine, dice, jaccard, jaroWinkler, levenshtein, levenshteinSimilarity, wordDistance, wordRecall } from './text-similarity/index.js';
+export { diacriticsMap, foldConfusables, foldDiacritics } from './text-normalisation/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/ocr-engine/index.d.ts

@@ -0,0 +1,5 @@
+/** Reading an image: the engine seam, and tesseract behind it. */
+export type { OcrEngine, OcrLine, OcrWord, RecognisedText, RecogniseHints } from './ocr-engine.contract.js';
+export { createTesseractEngine, DEFAULT_TESSERACT_OPTIONS } from './tesseract-engine.client.js';
+export type { TesseractCacheOptions, TesseractEngine, TesseractEngineOptions, TesseractSettings } from './tesseract-engine.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/ocr-engine/ocr-engine.contract.d.ts

@@ -0,0 +1,54 @@
+import type { Raster } from '@scanmate/ink';
+/**
+ * The seam between reading and everything done with what was read.
+ *
+ * `ocrPages` needs text with positions and nothing else, so any engine can sit
+ * behind it: the bundled tesseract, a native one, a cloud service. It also
+ * means a batch pays an engine's start-up - loading tens of megabytes of model
+ * into a WASM heap - once, not once a page: create one engine, pass it to
+ * every call, terminate it when done.
+ */
+export interface OcrEngine {
+    readonly name: string;
+    readonly version: string;
+    readonly languages: readonly string[];
+    /** Read an image: a raster, or encoded bytes. Positions come back in the image's pixels. */
+    recognise(image: Raster | Uint8Array, hints?: RecogniseHints): Promise<RecognisedText>;
+    /** Release the engine. Safe to call twice. */
+    terminate(): Promise<void>;
+}
+/**
+ * What the caller knows about an image that the engine would otherwise guess.
+ * An engine that cannot use a hint ignores it.
+ */
+export interface RecogniseHints {
+    /**
+     * `'page'` (the default) finds the layout itself; `'line'` is one line of
+     * text, `'word'` a single word - what a crop around one printed run is.
+     */
+    layout?: 'page' | 'line' | 'word';
+    /** The only characters that may be read - digits and separators, for a figure. */
+    characters?: string;
+}
+/** A word as read, with its box in pixels of the image read. */
+export interface OcrWord {
+    text: string;
+    /** 0-100, the engine's own confidence. */
+    confidence: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface OcrLine {
+    text: string;
+    words: OcrWord[];
+}
+export interface RecognisedText {
+    /** Plain text, in the engine's reading order. */
+    text: string;
+    /** 0-100, for the whole image. */
+    confidence: number;
+    lines: OcrLine[];
+}
+//# sourceMappingURL=ocr-engine.contract.d.ts.map

package/dist/src/ocr-engine/tesseract-engine.client.d.ts

@@ -0,0 +1,71 @@
+import type { OcrEngine } from './ocr-engine.contract.js';
+/**
+ * Tesseract, through tesseract.js: WebAssembly, nothing to install on the host.
+ *
+ * Language data comes from the `@tesseract.js-data/<language>` packages -
+ * English is a dependency; any other language is `npm install
+ * @tesseract.js-data/<code>` - and is read from disk, never downloaded. `best`
+ * is the "best_int" LSTM model: measured on real scans it read as well as the
+ * standard model (word recall 0.917 against 0.917) at a quarter of the size.
+ *
+ * Nothing is written anywhere unless configured to be. That matters where the
+ * code is deployed read-only, as on Azure Functions: tesseract.js otherwise
+ * caches unpacked language data in the current directory. The two things that
+ * can write are both explicit, and both go under `cache.path`, which defaults to
+ * the OS temp directory:
+ *
+ * - `cache.method` other than `'none'` keeps tesseract.js's unpacked data there;
+ * - reading more than one language stages their files into one folder there,
+ *   because tesseract.js takes a single data folder for all of them. (It also
+ *   accepts the data itself instead of a folder, but in 7.0.0 initialises with
+ *   the data where the language code belongs, so that route is closed.)
+ *
+ * What was resolved is on `engine.settings`, so it can be logged and checked.
+ */
+export interface TesseractEngineOptions {
+    /** Tesseract language codes, read together. Default `['eng']`. */
+    languages?: readonly string[];
+    /** `'best'` (the default) is the LSTM "best_int" model; `'standard'` the larger 4.0.0 one. */
+    model?: 'best' | 'standard';
+    /** A folder holding `<code>.traineddata.gz` per language, instead of the data packages. */
+    languageData?: string;
+    cache?: TesseractCacheOptions;
+    /** Tesseract page segmentation mode. Default `3`, fully automatic - right for whole pages. */
+    pageSegmentation?: number;
+}
+export interface TesseractCacheOptions {
+    /**
+     * - `'none'` (the default): read language data from its package on every
+     *   start, write nothing.
+     * - `'write'`: keep tesseract.js's unpacked data under `path` and reuse it.
+     * - `'readOnly'`: reuse data a previous run left under `path`; never write.
+     * - `'refresh'`: rewrite it.
+     */
+    method?: 'none' | 'write' | 'readOnly' | 'refresh';
+    /** Where anything written goes. Default a `scanmate-ocr` folder in the OS temp directory. */
+    path?: string;
+}
+/** What an engine resolved its options to. */
+export interface TesseractSettings {
+    languages: readonly string[];
+    model: 'best' | 'standard';
+    /** The folder the language data is read from. */
+    languageData: string;
+    cacheMethod: NonNullable<TesseractCacheOptions['method']>;
+    cachePath: string;
+    pageSegmentation: number;
+}
+export interface TesseractEngine extends OcrEngine {
+    readonly settings: TesseractSettings;
+}
+export declare const DEFAULT_TESSERACT_OPTIONS: {
+    readonly languages: readonly ["eng"];
+    readonly model: "best";
+    readonly cache: {
+        readonly method: "none";
+        readonly path: string;
+    };
+    readonly pageSegmentation: 3;
+};
+export declare function createTesseractEngine(options?: TesseractEngineOptions): Promise<TesseractEngine>;
+//# sourceMappingURL=tesseract-engine.client.d.ts.map

package/dist/src/page-reading/index.d.ts

@@ -0,0 +1,8 @@
+/** Reading aligned pages and scoring the scan's text against the original's. */
+export { claimWords, judgeRun, judgeRuns, matchWords } from './match-words.use-case.js';
+export type { Claims, MatchOptions, Reference, Verdict, WordMatch } from './match-words.use-case.js';
+export { ocrPages } from './ocr-pages.use-case.js';
+export type { OcrOptions, OcrReport, PageOcr, PlacedText, PositionedText, ReadablePage, RunReading, SideText, TextDifference } from './ocr-report.contract.js';
+export { DEFAULT_RECHECK_PASSES, recheckRun } from './recheck-run.use-case.js';
+export type { Recheck, RecheckOptions, RecheckPass } from './recheck-run.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/page-reading/match-words.use-case.d.ts

@@ -0,0 +1,65 @@
+import type { NormaliseOptions } from '../text-normalisation/index.js';
+import type { PlacedText, TextDifference } from './ocr-report.contract.js';
+/**
+ * Put the scan's words back where the original printed them, then judge each
+ * run of the original by what was read in its place.
+ *
+ * After alignment the scan sits on the original's canvas, so a word read at
+ * some place belongs to the run of the original printed at that place. Each
+ * word goes to the run whose box - grown a little, since OCR boxes hug ink and
+ * alignment is good to a pixel or two - holds the word's centre; where boxes
+ * overlap, the smallest wins. Words no run claims were added. Runs no word
+ * reached are missing, and runs whose words read differently changed.
+ *
+ * Figures are held to a stricter standard than words. A run whose digits read
+ * back differently has changed, however alike the rest is: "Total 1,250.00"
+ * read as "Total 7,250.00" is 93% similar, and exactly the alteration a check
+ * exists to catch. Words keep the fuzzy tolerance OCR needs.
+ *
+ * Nothing here depends on reading order, which is the point: a two-column
+ * page read down one column and then the other is still matched run for run.
+ */
+export interface Reference extends PlacedText {
+    endsLine?: boolean;
+}
+export interface MatchOptions {
+    normalise: NormaliseOptions;
+    matchThreshold: number;
+    minWordConfidence: number;
+}
+/** Each run's reading, in the order of `references`, and the words no run claimed, grouped by line. */
+export interface Claims {
+    found: string[];
+    added: PlacedText[][];
+}
+export interface WordMatch {
+    /** The original's runs, each followed by what was read there, then added words. */
+    alignedText: string;
+    /** The original's runs in order, as one text. */
+    expectedText: string;
+    differences: TextDifference[];
+}
+/** How one run reads back: agreeing, or which difference it is. */
+export type Verdict = {
+    agrees: true;
+} | {
+    agrees: false;
+    kind: 'changed' | 'missing';
+    reason: 'numbers' | 'text';
+    similarity: number;
+};
+/** A run that is only a figure: digits and the marks figures are written with. */
+export declare const FIGURE: RegExp;
+export declare function claimWords(references: readonly Reference[], words: readonly PlacedText[], lineOf: readonly number[], options: MatchOptions): Claims;
+/**
+ * The rule every run is held to - on the page, and again when it is re-read on
+ * its own. A run that is only a figure agrees when its digits do, in order:
+ * OCR trades commas for full stops constantly, and `5,768,700.00` read as
+ * `5.768.700 00` is the same amount. Any other run must also keep its digits,
+ * and read within the similarity threshold.
+ */
+export declare function judgeRun(expected: string, found: string, options: MatchOptions): Verdict;
+export declare function judgeRuns(references: readonly Reference[], claims: Claims, options: MatchOptions): WordMatch;
+/** Claim and judge in one go, for a page read once. */
+export declare function matchWords(references: readonly Reference[], words: readonly PlacedText[], lineOf: readonly number[], options: MatchOptions): WordMatch;
+//# sourceMappingURL=match-words.use-case.d.ts.map

package/dist/src/page-reading/ocr-pages.use-case.d.ts

@@ -0,0 +1,17 @@
+import type { OcrOptions, OcrReport, ReadablePage } from './ocr-report.contract.js';
+/**
+ * Read every aligned page and say how closely the scan's text matches the
+ * original's - per page, and for the document.
+ *
+ * The scan is read from its enhanced image when there is one, otherwise from
+ * the aligned scan enlarged to `targetDpi`. The original comes from its text
+ * layer when it has one, which is exact, so every error counted is the scan's;
+ * otherwise it is read the same way. Both are then compared run by run of the
+ * original, on the shared canvas, rather than in whatever order the engine
+ * read them.
+ *
+ * One engine serves the whole call. Pass `engine` to share one across calls;
+ * it is then left running.
+ */
+export declare function ocrPages<Page extends ReadablePage>(pages: readonly Page[], options?: OcrOptions): Promise<OcrReport>;
+//# sourceMappingURL=ocr-pages.use-case.d.ts.map

package/dist/src/page-reading/ocr-report.contract.d.ts

@@ -0,0 +1,154 @@
+import type { AlignedPage, PageImage, ProgressCallback } from '@scanmate/ink';
+import type { OcrEngine, TesseractEngineOptions } from '../ocr-engine/index.js';
+import type { RecheckOptions } from './recheck-run.use-case.js';
+import type { NormaliseOptions } from '../text-normalisation/index.js';
+import type { ScoreMetric, TextMetrics } from '../text-similarity/index.js';
+/** A run of text placed on the page, in PDF points from the top-left - what `@scanmate/extract` calls a text item. */
+export interface PositionedText {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    endsLine?: boolean;
+}
+/**
+ * What `ocrPages` reads: an aligned page, and optionally its enhanced image
+ * (`@scanmate/enhance`) and the original's text layer (`@scanmate/extract`).
+ * Only the original's text layer is ever used. A scan's own text layer is
+ * ignored, deliberately - hidden or stale text must not vouch for what the
+ * paper shows.
+ */
+export type ReadablePage = AlignedPage & {
+    enhanced?: PageImage;
+    metadata?: {
+        original?: {
+            textItems?: readonly PositionedText[] | null;
+        };
+    };
+};
+export interface OcrOptions {
+    /** An engine to use and leave running. Default: a tesseract engine made for this call and terminated after it. */
+    engine?: OcrEngine;
+    /** Settings for that default engine: languages, model, cache. */
+    tesseract?: TesseractEngineOptions;
+    /**
+     * The original's text: `'auto'` (the default) takes its text layer when it
+     * has one - exact, and no OCR errors on that side - and reads it otherwise;
+     * `'text-layer'` insists; `'ocr'` always reads it.
+     */
+    original?: 'auto' | 'text-layer' | 'ocr';
+    /** Enlarge images below this before reading them. Default `300`; `null` reads them as they are. An `enhanced` image is read as it is. */
+    targetDpi?: number | null;
+    /** Resolution of a page that does not say. Default `150`. */
+    assumeDpi?: number;
+    normalise?: NormaliseOptions;
+    /** Which metric is a page's `score`. Default `'levenshteinSimilarity'`. */
+    scoreMetric?: ScoreMetric;
+    /** A run of the original read back below this similarity is a difference. Default `0.8`. */
+    matchThreshold?: number;
+    /** Scanned words not on any run of the original count as added only from this confidence. Default `60`. */
+    minWordConfidence?: number;
+    /**
+     * Re-read each run the page reading doubted, cropped and enlarged, before
+     * calling it a difference; it is cleared only when several passes agree with
+     * the original. On by default, since a false difference costs a person's
+     * time; `false` reports the page reading as it is. See `recheckRun`.
+     */
+    recheck?: RecheckOptions | false;
+    onProgress?: ProgressCallback;
+}
+/** A word or line, placed on the page in points from the top-left. */
+export interface PlacedText {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** 0-100; `null` for the text layer, which is not a reading. */
+    confidence?: number | null;
+}
+export interface SideText {
+    source: 'text-layer' | 'ocr';
+    /** In the source's own order: the text layer's, or the engine's reading order. */
+    text: string;
+    /** 0-100 for OCR; `null` for a text layer. */
+    confidence: number | null;
+    lines: PlacedText[];
+    words: PlacedText[];
+}
+/**
+ * - `changed`: a run of the original, read back as something else;
+ * - `missing`: a run of the original with nothing read where it should be;
+ * - `added`: words read where the original has none.
+ */
+export interface TextDifference {
+    kind: 'changed' | 'missing' | 'added';
+    expected: string | null;
+    found: string | null;
+    /** Normalised Levenshtein similarity of the two; `0` for missing or added. */
+    similarity: number;
+    /**
+     * Why a run counts as changed: its figures differ (`'numbers'`, held to an
+     * exact match, since one digit is the whole point), or its words fell below
+     * the match threshold (`'text'`). Always `'text'` for missing and added.
+     */
+    reason: 'numbers' | 'text';
+    /** Where on the page, in points from the top-left. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One run of the original, and what the scan reads in its place. */
+export interface RunReading {
+    /** The original's text. */
+    text: string;
+    /** What was read there - by the page reading, or by the recheck that cleared it. */
+    found: string;
+    /** The reading agrees with the original, by the rule every run is judged by. */
+    agrees: boolean;
+    /** The run was re-read on its own. */
+    rechecked: boolean;
+    /** Where the original prints it, in points from the top-left. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PageOcr {
+    page: number;
+    original: SideText;
+    scanned: SideText;
+    /** Every run of the original with its reading, in the original's order - what a search for required content consults. */
+    runs: RunReading[];
+    /**
+     * The scan's words re-ordered to follow the original: each run of the
+     * original followed by what was read in its place, then any added words.
+     * This, not the engine's reading order, is what the metrics compare - so a
+     * two-column page read column-wise is not a page of errors.
+     */
+    alignedText: string;
+    score: number;
+    metrics: TextMetrics;
+    differences: TextDifference[];
+    /** Runs the page reading doubted and re-read on their own, and how many of them the re-reading cleared. */
+    rechecks: {
+        attempted: number;
+        cleared: number;
+    };
+    warnings: string[];
+}
+export interface OcrReport {
+    /** Page scores weighted by each page's expected characters - a three-word page does not outvote a dense one. */
+    score: number;
+    /** Unweighted mean of page scores; the two disagreeing says the short pages read differently. */
+    pageMean: number;
+    pages: PageOcr[];
+    engine: {
+        name: string;
+        version: string;
+        languages: readonly string[];
+    };
+}
+//# sourceMappingURL=ocr-report.contract.d.ts.map

package/dist/src/page-reading/recheck-run.use-case.d.ts

@@ -0,0 +1,49 @@
+import type { Raster } from '@scanmate/ink';
+import type { OcrEngine } from '../ocr-engine/index.js';
+import type { MatchOptions, Reference } from './match-words.use-case.js';
+/**
+ * A second look at one run the page reading got wrong, before calling it a
+ * difference.
+ *
+ * Read as part of a whole page, a short run - a figure in a table, a word on
+ * a shaded bar - is at the mercy of the engine's layout analysis and of one
+ * resolution. Cropped to itself, enlarged further, read as a single line (or
+ * word, or as digits only when it is a figure), light-on-dark text inverted,
+ * contrast stretched, it often reads cleanly. Measured on real scans at 120
+ * and 144 dpi, cropped multi-pass reading confirmed 96-97% of every printed
+ * value on the page; at 93 dpi, a third.
+ *
+ * The danger is the opposite error: try enough readings and one may land on
+ * the expected text by chance - on a 93-dpi scan a single agreeing pass
+ * accepted 4 of 61 forged digits. So a run is cleared only when `agree`
+ * separate passes (two by default) read it as the original prints it, by the
+ * same rule the page is judged by: figures exactly, words within the threshold.
+ */
+export interface RecheckPass {
+    /** Resolution to enlarge the crop to; a crop already finer is not reduced. */
+    dpi: number;
+    /** Read the crop as one line of text, or as one word. */
+    layout: 'line' | 'word';
+    /** Stretch the crop's contrast to full black and white first. */
+    stretch?: boolean;
+}
+export interface RecheckOptions {
+    /** The readings to try, in order. Default {@link DEFAULT_RECHECK_PASSES}. */
+    passes?: readonly RecheckPass[];
+    /** Passes that must agree with the original to clear a run. Default `2`. */
+    agree?: number;
+}
+export declare const DEFAULT_RECHECK_PASSES: readonly RecheckPass[];
+export interface Recheck {
+    cleared: boolean;
+    /** An agreeing reading when cleared; `null` otherwise. */
+    reading: string | null;
+    /** Passes tried, and how many agreed. */
+    passes: number;
+    agreed: number;
+}
+export declare function recheckRun(engine: OcrEngine, image: {
+    raster: Raster;
+    dpi: number;
+}, run: Reference, options: MatchOptions & RecheckOptions): Promise<Recheck>;
+//# sourceMappingURL=recheck-run.use-case.d.ts.map

package/dist/src/text-normalisation/confusables.mapper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Characters and pairs OCR mistakes for one another, folded to one form each.
+ *
+ * Off by default, and deliberately so: `0` for `o` and `5` for `s` are OCR's
+ * commonest errors, and the very substitutions someone altering an amount or a
+ * reference would make. Folding them raises a score by hiding exactly what a
+ * check is for. Use it to compare prose, never figures.
+ *
+ * Applied after case folding, to lower-case text.
+ */
+export declare function foldConfusables(text: string): string;
+//# sourceMappingURL=confusables.mapper.d.ts.map

package/dist/src/text-normalisation/diacritics.mapper.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Letters with diacritics, ligatures and look-alike forms, folded to plain
+ * Latin: `é` to `e`, `Æ` to `AE`, a circled or full-width `Ａ` to `A`.
+ *
+ * OCR drops and invents accents - a scanned `é` reads as `e` or `è` as the
+ * print allows - so text is compared with them folded away. Some bases are two
+ * letters, so folding can lengthen a string. The table is the project's own
+ * diacritics map (86 bases, 874 letters), kept as escapes so every code point
+ * is visible in review; it is expanded into a lookup once, on first use.
+ */
+/** Every folded letter and what it folds to. */
+export declare function diacriticsMap(): ReadonlyMap<string, string>;
+/** Replace every letter in the table by its plain base; everything else is kept as it is. */
+export declare function foldDiacritics(text: string): string;
+//# sourceMappingURL=diacritics.mapper.d.ts.map

package/dist/src/text-normalisation/index.d.ts

@@ -0,0 +1,6 @@
+/** Making OCR text and a document's own text comparable: the noise OCR adds, removed. */
+export { foldConfusables } from './confusables.mapper.js';
+export { diacriticsMap, foldDiacritics } from './diacritics.mapper.js';
+export { DEFAULT_NORMALISE, normaliseText, tokenise } from './normalise-text.use-case.js';
+export type { NormaliseOptions } from './normalise-text.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/text-normalisation/normalise-text.use-case.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Text made comparable: the differences OCR introduces that say nothing about
+ * the document are removed, and nothing else.
+ *
+ * Each step is a judgement about which noise to forgive, so each can be turned
+ * off. In order:
+ *
+ * 1. Unicode NFKC - ligatures (`fi`), full-width and compatibility forms.
+ * 2. Typography - curly quotes, dashes, ellipses and odd spaces to plain ASCII.
+ * 3. De-hyphenation - `informa-` + newline + `tion` is `information`, or every
+ *    wrapped word counts as an edit.
+ * 4. Diacritics - `é` to `e`, `Æ` to `AE`.
+ * 5. Case.
+ * 6. Noise - tokens with no letter, digit or currency sign: table rules read
+ *    as `|`, underlines as `___`, specks as `.` or `~`.
+ * 7. Punctuation (off by default) - it carries real signal: `1,250.00` is not
+ *    `125000`.
+ * 8. OCR confusables (off by default) - `0/o`, `1/l/i`, `5/s`, `rn/m`. Folding
+ *    them forgives exactly the substitutions a forger would make.
+ * 9. Whitespace collapsed and trimmed.
+ */
+export interface NormaliseOptions {
+    nfkc?: boolean;
+    typography?: boolean;
+    dehyphenate?: boolean;
+    diacritics?: boolean;
+    caseFold?: boolean;
+    dropNoise?: boolean;
+    stripPunctuation?: boolean;
+    confusables?: boolean;
+}
+export declare const DEFAULT_NORMALISE: Required<NormaliseOptions>;
+export declare function normaliseText(text: string, options?: NormaliseOptions): string;
+/** Normalised words, in order. */
+export declare function tokenise(text: string, options?: NormaliseOptions): string[];
+//# sourceMappingURL=normalise-text.use-case.d.ts.map

package/dist/src/text-similarity/compare-texts.use-case.d.ts

@@ -0,0 +1,30 @@
+import type { NormaliseOptions } from '../text-normalisation/index.js';
+/** Every measure of how alike an expected text and an actual one are, after normalisation. */
+export interface TextMetrics {
+    /** Characters of edit between the normalised texts. */
+    levenshtein: number;
+    /** `1 - levenshtein / longer length`. */
+    levenshteinSimilarity: number;
+    /** Share of distinct words in common. */
+    jaccard: number;
+    /** Character-bigram overlap. */
+    dice: number;
+    /** Word-frequency cosine. */
+    cosine: number;
+    /** Only meaningful on short strings; reported for completeness. */
+    jaroWinkler: number;
+    /** Character error rate: edits over the expected length. Can exceed 1. */
+    characterErrorRate: number;
+    /** Word error rate: word edits over the expected word count. Can exceed 1. */
+    wordErrorRate: number;
+    /** Share of expected words present, each used once. */
+    wordRecall: number;
+    /** Actual length over expected length - near 0 when a page read as nothing. */
+    lengthRatio: number;
+    /** Normalised expected length, in characters: the weight this text carries in a total. */
+    characters: number;
+}
+export type ScoreMetric = 'levenshteinSimilarity' | 'wordRecall' | 'jaccard' | 'dice' | 'cosine';
+/** Normalise both texts the same way, then measure them every way. */
+export declare function compareTexts(expected: string, actual: string, options?: NormaliseOptions): TextMetrics;
+//# sourceMappingURL=compare-texts.use-case.d.ts.map

package/dist/src/text-similarity/index.d.ts

@@ -0,0 +1,5 @@
+/** How alike two texts are, measured the several ways they can differ. */
+export { compareTexts } from './compare-texts.use-case.js';
+export type { ScoreMetric, TextMetrics } from './compare-texts.use-case.js';
+export { cosine, dice, jaccard, jaroWinkler, levenshtein, levenshteinSimilarity, wordDistance, wordRecall } from './similarity-metrics.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/text-similarity/similarity-metrics.use-case.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Ways to say how alike two texts are. They fail differently, which is why
+ * several are reported rather than one:
+ *
+ * - edit distance counts every insertion, deletion and substitution, so it
+ *   notices a changed digit - and punishes text that reflowed;
+ * - set and bag measures (Jaccard, Dice, cosine, recall) ignore order, so they
+ *   survive reflow and a reading order OCR got wrong - and miss a swapped clause;
+ * - character and word error rates are what anyone who works with OCR expects
+ *   to see;
+ * - Jaro-Winkler is for short strings - names, references - and meaningless on
+ *   a page.
+ *
+ * All take text already normalised; similarities run from 0 to 1.
+ */
+/** Characters inserted, deleted or substituted to turn one text into the other (Myers' bit-parallel algorithm). */
+export declare function levenshtein(a: string, b: string): number;
+/** `1 - distance / longer length`: 1 for identical, 0 for nothing in common. */
+export declare function levenshteinSimilarity(a: string, b: string): number;
+/** Words inserted, deleted or substituted, as edit distance over words rather than characters. */
+export declare function wordDistance(a: readonly string[], b: readonly string[]): number;
+/** Shared distinct words over all distinct words. */
+export declare function jaccard(a: readonly string[], b: readonly string[]): number;
+/** Sørensen-Dice over character bigrams, counted with multiplicity. */
+export declare function dice(a: string, b: string): number;
+/** Cosine of the two word-frequency vectors. */
+export declare function cosine(a: readonly string[], b: readonly string[]): number;
+/** Share of the expected words found, each found word used once - the question "is what should be there, there?". */
+export declare function wordRecall(expected: readonly string[], actual: readonly string[]): number;
+/**
+ * Jaro-Winkler: characters matched within a window, transpositions counted, a
+ * bonus for a shared prefix of up to four. Tuned for short strings.
+ */
+export declare function jaroWinkler(a: string, b: string, prefixScale?: number): number;
+//# sourceMappingURL=similarity-metrics.use-case.d.ts.map