@scanmate/diff 0.0.2

package/dist/src/change-detection/annotate-overlay.use-case.d.ts

@@ -0,0 +1,19 @@
+import type { Raster, Rect } from '@scanmate/ink';
+/**
+ * Outline what the report says onto the overlay, so the picture and the numbers
+ * can be checked against each other at a glance: green for an expected region
+ * that was filled in, amber for one that was not, magenta around every change
+ * nobody expected, and blue - the overlay's colour for lost ink - around ink
+ * that went missing.
+ */
+export type Rgba = readonly [number, number, number, number];
+export declare const IDENTIFIED: Rgba;
+export declare const NOT_IDENTIFIED: Rgba;
+export declare const UNEXPECTED: Rgba;
+export declare const MISSING: Rgba;
+export interface Annotation {
+    rect: Rect;
+    color: Rgba;
+}
+export declare function annotateOverlay(overlay: Raster, annotations: readonly Annotation[], thickness?: number): void;
+//# sourceMappingURL=annotate-overlay.use-case.d.ts.map

package/dist/src/change-detection/connected-components.use-case.d.ts

@@ -0,0 +1,44 @@
+import type { BinaryImage } from '@scanmate/ink';
+/**
+ * Connected-component labelling: which set pixels of a mask touch, and the box
+ * around each group.
+ *
+ * The overlay says *which pixels* changed; a caller asking "was anything added
+ * outside the boxes I expected" needs *regions*, so the pixels have to be grouped.
+ * No maintained package does this for a flat mask, and it is small enough that
+ * a dependency would cost more than it saves.
+ *
+ * Classic two-pass labelling with union-find. The first pass gives each set pixel
+ * the smallest label among its already-visited neighbours and records that any
+ * other neighbouring labels are the same component; the second resolves each
+ * label to its root and accumulates the box and pixel count, so a third pass is
+ * never needed. Union by size and path halving keep the forest flat.
+ */
+export interface Component {
+    /** Bounding box, in pixels, inclusive of every pixel in the component. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Set pixels in the component. */
+    pixels: number;
+}
+export interface LabelOptions {
+    /**
+     * `8` (the default) joins diagonal neighbours, so a handwritten stroke at an
+     * angle stays one component instead of shattering into a staircase of pieces.
+     */
+    connectivity?: 4 | 8;
+}
+export declare function connectedComponents(mask: BinaryImage, options?: LabelOptions): Component[];
+export interface LabelledComponents {
+    components: Component[];
+    /**
+     * Per pixel, one plus the index of its component in `components`; `0` where
+     * the mask is clear. What a caller needs to ask which pixels a component owns.
+     */
+    labels: Int32Array;
+}
+/** {@link connectedComponents}, keeping the label image the second pass resolves anyway. */
+export declare function labelComponents(mask: BinaryImage, options?: LabelOptions): LabelledComponents;
+//# sourceMappingURL=connected-components.use-case.d.ts.map

package/dist/src/change-detection/diff-pages.use-case.d.ts

@@ -0,0 +1,22 @@
+import type { AlignedPage } from '@scanmate/ink';
+import type { DiffOptions, ExpectedChange, PageDiff } from './page-diff.contract.js';
+/**
+ * What changed on each page, and whether it was supposed to.
+ *
+ * The overlay is the detection: the original's ink, fattened by a tolerance band,
+ * subtracted from the aligned scan, leaves the ink the scan added. What this adds
+ * is the reporting. What changed is grouped into changes - labelled, merged
+ * across small gaps, filtered below a physical size. A change whose ink lies
+ * mostly in an expected region belongs to that region; every other change is
+ * unexpected. Each region is also analysed on its own - its new ink grouped,
+ * its printed rules discarded, the rest measured - and is identified once that
+ * ink adds up to `minFillArea` without covering more than `maxFill` of it. The
+ * same grouping is done for ink the scan lost.
+ *
+ * Masks are built once per page and read four ways: the overlay, the expected
+ * regions, the added changes and the missing ones.
+ */
+export declare function diffPages(pages: readonly AlignedPage[], expected?: readonly ExpectedChange[], options?: DiffOptions): Promise<PageDiff[]>;
+/** One page. `expected` should already be the regions for this page. */
+export declare function diffPage(page: AlignedPage, expected?: readonly ExpectedChange[], options?: DiffOptions): Promise<PageDiff>;
+//# sourceMappingURL=diff-pages.use-case.d.ts.map

package/dist/src/change-detection/index.d.ts

@@ -0,0 +1,13 @@
+/** What changed on a page and whether it was supposed to: changed pixels grouped into reportable regions. */
+export { annotateOverlay, IDENTIFIED, MISSING, NOT_IDENTIFIED, UNEXPECTED } from './annotate-overlay.use-case.js';
+export type { Annotation, Rgba } from './annotate-overlay.use-case.js';
+export { connectedComponents, labelComponents } from './connected-components.use-case.js';
+export type { Component, LabelledComponents, LabelOptions } from './connected-components.use-case.js';
+export { diffPage, diffPages } from './diff-pages.use-case.js';
+export { mergeBoxes } from './merge-boxes.use-case.js';
+export type { MergedBox } from './merge-boxes.use-case.js';
+export type { Change, CoordinateUnits, DiffOptions, ExpectedChange, ExpectedResult, PageDiff, RegionInkMetrics } from './page-diff.contract.js';
+export { measureRegionInk } from './region-ink.use-case.js';
+export type { RegionInk, RegionInkOptions } from './region-ink.use-case.js';
+export { composeSideBySide } from './side-by-side.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/change-detection/merge-boxes.use-case.d.ts

@@ -0,0 +1,27 @@
+import type { Component } from './connected-components.use-case.js';
+/**
+ * Join components that belong to one change.
+ *
+ * A signature is not one connected component: the pen lifts between letters,
+ * the dot of an i floats above its stem, a tick's two strokes may not quite meet.
+ * Reported raw, one signature would be forty boxes. So components whose boxes
+ * come within `gap` pixels of each other are merged, and merged boxes that now
+ * reach a neighbour merge again, until nothing moves.
+ *
+ * Naive pairwise merging is quadratic, and a badly aligned page can produce
+ * thousands of fragments. Boxes are bucketed on a grid of cells at least as
+ * large as the gap, so each box is only compared with the few that share or
+ * border its cells.
+ */
+export interface MergedBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Changed pixels inside the merged box. */
+    pixels: number;
+    /** How many components it was built from. */
+    components: number;
+}
+export declare function mergeBoxes(components: readonly Component[], gap: number): MergedBox[];
+//# sourceMappingURL=merge-boxes.use-case.d.ts.map

package/dist/src/change-detection/page-diff.contract.d.ts

@@ -0,0 +1,206 @@
+import type { ImageFormat, InkOptions, ProgressCallback, Raster, Rect } from '@scanmate/ink';
+/**
+ * Coordinates for regions going in and changes coming out.
+ *
+ * `points` (the default) are PDF points, 1/72 inch, from the page's top-left
+ * corner - the units a document generator already knows its fields in, and the
+ * only ones that stay put when `@scanmate/extract` renders each document at its
+ * scan's resolution. `pixels` are the original's rendered pixels, for callers
+ * working from images rather than PDFs.
+ */
+export type CoordinateUnits = 'points' | 'pixels';
+/** A place on a page where a change is expected - a signature box, a tick box. */
+export interface ExpectedChange {
+    /** One-based page number in the original. */
+    page: number;
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DiffOptions {
+    /** Units of `ExpectedChange` rectangles and of every rectangle reported back. Default `'points'`. */
+    units?: CoordinateUnits;
+    /** Pixels the original's ink is fattened by before diffing, to absorb sub-pixel misalignment. Default `2`. */
+    tolerance?: number;
+    /**
+     * New ink an expected region needs to count as identified, in square
+     * millimetres. Default `2`.
+     *
+     * Counted from the region's changes - each already past `minChangeArea`, so
+     * scattered speckle never adds up to a signature - and in physical units, not
+     * as a share of the region: a pen signature is the same few tens of mm2
+     * whether its box is a stamp or the width of the page, and the same mark is
+     * four times the pixels at twice the dpi. A tick is about 5 mm2, initials a
+     * little more; after merging, the largest noise measured on real scans was
+     * 0.85 mm2.
+     */
+    minFillArea?: number;
+    /**
+     * Share of an expected region that may be new ink before it stops counting
+     * as filled in. Default `0.5`.
+     *
+     * A signature or a name leaves most of its box empty; a box more than half
+     * covered was scribbled out, blacked over or hit by a stamp. It is not
+     * identified, and its result says `overfilled`.
+     */
+    maxFill?: number;
+    /**
+     * A piece of new ink inside an expected region that spans at least this share
+     * of the region's width or height, and is thin, is a form rule, not writing.
+     * Default `0.9`.
+     *
+     * Field boxes are often drawn with printed borders, and where the alignment
+     * leaves a border a pixel or two out of place, a sliver of it outlives the
+     * tolerance band. Such slivers are discarded and counted in `ink.formLines`.
+     */
+    formLineSpan?: number;
+    /**
+     * How thin, in millimetres, a spanning piece must be to be a form rule - or
+     * 4% of the region's other side, if that is more. Default `0.6`: a printed
+     * rule is a few tenths of a millimetre, a pen stroke rarely runs the length of
+     * its box.
+     */
+    formLineThickness?: number;
+    /**
+     * Smallest change worth reporting, in square millimetres of ink. Default `1`.
+     *
+     * Measured on real scans: after merging, the largest noise specks came to
+     * 0.31-0.85 mm2, while a tick in a 6 mm box is about 5 mm2 and a signature
+     * tens of mm2. Physical units, because the render resolution varies with the
+     * scan and the same speck is four times the pixels at twice the dpi.
+     */
+    minChangeArea?: number;
+    /**
+     * Smallest loss of original ink worth reporting, in square millimetres.
+     * Default `4`.
+     *
+     * Higher than `minChangeArea` on purpose. The poorest of three real scans
+     * softened the ends of solid header bars into strips of 1-8 mm2 of apparent
+     * loss on most pages, while an erased word, a line or a paragraph measured
+     * 8-22 mm2 and more. Losses too small to clear this - a deleted three-letter
+     * word is about 1 mm2 - are textual, and are what `@scanmate/ocr` compares
+     * text for.
+     */
+    minMissingArea?: number;
+    /**
+     * Scan ink fainter than this fraction of the scan's own ink threshold counts
+     * as gone. Scanners wash colour out - a red link comes back pink - and faded
+     * is not missing. Default `0.25`.
+     */
+    faintInk?: number;
+    /**
+     * Changes within this many millimetres of each other are one change - the
+     * strokes and dots of a signature, the two arms of a tick. Default `3`.
+     */
+    mergeGap?: number;
+    /** Resolution assumed for a page that does not say what it was rendered at. Default `150`. */
+    assumeDpi?: number;
+    /** Fraction of a change's ink inside an expected region for the change to count as expected. Default `0.5`. */
+    regionOverlap?: number;
+    /**
+     * Most changes reported per page, largest first. A badly aligned page turns
+     * every stroke into a change; past this it is reported as `truncated`
+     * instead of as a thousand boxes. Default `50`.
+     */
+    maxChanges?: number;
+    /** Encoding of `diffImage`. `'none'` skips it. Default `'png'`. */
+    output?: ImageFormat | 'none';
+    /** Draw each expected region and each unexpected change onto the overlay. Default `false`. */
+    annotate?: boolean;
+    /**
+     * Also compose the original and the aligned scan side by side, with every
+     * expected region, unexpected change and missing ink boxed on both halves -
+     * the image a reviewer looks at. Encoded like the overlay. Default `false`:
+     * it is twice a page of pixels.
+     */
+    sideBySide?: boolean;
+    ink?: InkOptions;
+    onProgress?: ProgressCallback;
+}
+/** What happened in one expected region. */
+export interface ExpectedResult {
+    id: string;
+    /** The region gained enough new ink to count as filled in. */
+    identified: boolean;
+    /** The region as given, in the requested units. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** New ink in the region's changes, in square millimetres. */
+    addedInk: number;
+    /** Original ink the region lost, in square millimetres. */
+    removedInk: number;
+    /** `addedInk` as a share of `minFillArea`, clamped to `[0, 1]`. */
+    score: number;
+    /** More of the region is new ink than `maxFill` allows: blacked out or scribbled over, not filled in. */
+    overfilled: boolean;
+    /** The shape of the region's new ink. */
+    ink: RegionInkMetrics;
+}
+/** How the new ink in an expected region is laid out. */
+export interface RegionInkMetrics {
+    /** Separate changes, after grouping the pieces of each - one for a signature, two for a name and a date. */
+    changes: number;
+    /** Ink in the largest change, in square millimetres. */
+    largestArea: number;
+    /** Box around all of it, in the requested units; `null` when there is none. */
+    bounds: Rect | null;
+    /** `bounds` as a share of the region's width and height. */
+    widthRatio: number;
+    heightRatio: number;
+    /**
+     * Share of the ink lying along the region's border (a band 3% of its shorter
+     * side). Writing sits inside its box; ink that is mostly border-band came in
+     * from outside or is the box's own frame.
+     */
+    edgeTouch: number;
+    /** Share of the region's area that is new ink. */
+    fill: number;
+    /** Form-rule slivers discarded before measuring. */
+    formLines: number;
+}
+/** A change found where nothing was expected, or ink that went missing. */
+export interface Change {
+    /** Bounding box, in the requested units. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Changed ink, in square millimetres. */
+    inkArea: number;
+    /** Changed pixels. */
+    pixels: number;
+}
+export interface PageDiff {
+    page: number;
+    /** The overlay: red added, blue lost, grey agreed - annotated when asked. */
+    diffRaster: Raster;
+    diffImage: Uint8Array | null;
+    /** Original and aligned scan side by side with the report boxed on both, when `sideBySide` was asked for. */
+    sideBySideRaster: Raster | null;
+    sideBySideImage: Uint8Array | null;
+    expected: ExpectedResult[];
+    /** New ink outside every expected region, merged into one box per change. */
+    unexpected: Change[];
+    /**
+     * Original ink the scan lost. A dropped line is as suspicious as an added one.
+     * A scan blurry enough to wash out a hairline rule reports that rule here too:
+     * it is gone from the image, whatever happened to the paper.
+     */
+    missing: Change[];
+    /** More changes than `maxChanges` were found - usually a sign the alignment failed. */
+    truncated: boolean;
+    summary: {
+        /** Page-wide fraction of new ink. */
+        addedInk: number;
+        removedInk: number;
+        identified: number;
+        notIdentified: number;
+        unexpected: number;
+        missing: number;
+    };
+}
+//# sourceMappingURL=page-diff.contract.d.ts.map

package/dist/src/change-detection/region-ink.use-case.d.ts

@@ -0,0 +1,47 @@
+import type { BinaryImage, Rect } from '@scanmate/ink';
+/**
+ * The shape of the new ink inside one expected region.
+ *
+ * "Was ink added here" is one number; whether that ink is a filled-in field is
+ * a question about its shape. A signature is a few strokes somewhere inside the
+ * box. A field someone blacked out is ink across most of it. A sliver along one
+ * border, spanning the whole box and a hair thick, is the field's own printed
+ * rule that the alignment left a pixel or two out of place - no one wrote it.
+ * So the region is analysed on its own: its new ink labelled, form-rule slivers
+ * discarded, the rest grouped the way page-level changes are, and measured.
+ *
+ * Everything here is in pixels of the region; the caller converts.
+ */
+export interface RegionInkOptions {
+    /** Pixels within which pieces of ink are one change. */
+    mergeGap: number;
+    /** Smallest change, in pixels, that counts. */
+    minChangePixels: number;
+    /** A piece spanning at least this share of the region's width (or height) may be a form rule. */
+    lineSpan: number;
+    /** ...if it is also no thicker than this many pixels, */
+    lineThickness: number;
+    /** ...or than this share of the region's other side, whichever is more. */
+    lineThicknessRatio: number;
+    /** Width of the border band, as a share of the region's shorter side (at least one pixel). */
+    edgeBand: number;
+}
+export interface RegionInk {
+    /** New-ink pixels in the changes that count. */
+    pixels: number;
+    /** Changes that count, after grouping. */
+    changes: number;
+    /** Pixels in the largest one. */
+    largest: number;
+    /** Box around every change that counts, in page pixels; `null` when there is none. */
+    bounds: Rect | null;
+    /** Share of those pixels that lie in the band along the region's border. */
+    edgeTouch: number;
+    /** Share of the region's area that is counted new ink. */
+    fill: number;
+    /** Form-rule slivers discarded. */
+    formLines: number;
+}
+/** Analyse `added` (the page's new-ink mask) inside `rect` (page pixels). */
+export declare function measureRegionInk(added: BinaryImage, rect: Rect, options: RegionInkOptions): RegionInk;
+//# sourceMappingURL=region-ink.use-case.d.ts.map

package/dist/src/change-detection/side-by-side.use-case.d.ts

@@ -0,0 +1,4 @@
+import type { Raster } from '@scanmate/ink';
+import type { Annotation } from './annotate-overlay.use-case.js';
+export declare function composeSideBySide(original: Raster, aligned: Raster, annotations: readonly Annotation[], thickness: number, gutter: number): Raster;
+//# sourceMappingURL=side-by-side.use-case.d.ts.map

package/dist/src/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@scanmate/diff` - what changed between an original and its aligned scan, where,
+ * and whether it was supposed to.
+ *
+ * ```ts
+ * const diffs = await diffPages(alignedPages, [
+ *   { page: 1, id: 'signature', x: 76, y: 700, width: 300, height: 60 },
+ * ])
+ * diffs[0].expected    // [{ id: 'signature', identified: true, ... }]
+ * diffs[0].unexpected  // changes outside every expected region, one box each
+ * ```
+ *
+ * Every function here assumes both images already share a canvas - which is what
+ * `@scanmate/align` produces. Feed it a raw scan and every rectangle names a
+ * different part of the page in each image.
+ */
+export { diffPage, diffPages } from './change-detection/index.js';
+export type { Change, CoordinateUnits, DiffOptions, ExpectedChange, ExpectedResult, PageDiff, RegionInkMetrics } from './change-detection/index.js';
+export { compareRegions, diffDocument, renderDiff } from './region-comparison/index.js';
+export type { DocumentDiff, Region, RegionOptions, RegionReport } from './region-comparison/index.js';
+export { annotateOverlay, composeSideBySide, connectedComponents, IDENTIFIED, labelComponents, measureRegionInk, mergeBoxes, MISSING, NOT_IDENTIFIED, UNEXPECTED } from './change-detection/index.js';
+export type { Annotation, Component, LabelledComponents, LabelOptions, MergedBox, RegionInk, RegionInkOptions, Rgba } from './change-detection/index.js';
+export { buildMasks, measureRegion, paintOverlay } from './region-comparison/index.js';
+export type { Masks } from './region-comparison/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/region-comparison/compare-regions.use-case.d.ts

@@ -0,0 +1,31 @@
+import type { ImageInput } from '@scanmate/ink';
+import type { Masks } from './ink-masks.use-case.js';
+import type { DocumentDiff, Region, RegionOptions, RegionReport } from './region.model.js';
+/**
+ * What changed, and where.
+ *
+ * Once the scan sits on the original's canvas, "was this box signed?" stops
+ * being an image problem and becomes arithmetic: count the ink inside the
+ * rectangle that is present in the scan and absent from the original.
+ *
+ * The one subtlety is the tolerance band. Alignment is good to a pixel or so,
+ * never to zero, and printed text is mostly edges — so a half-pixel shift
+ * lights up the outline of every character as "new ink". Dilating the
+ * original's mask first (fattening every stroke by a couple of pixels) absorbs
+ * that, the way a proofreader ignores a letter sitting a hair off the baseline.
+ * What it cannot absorb is a signature, which is ink in places the original has
+ * none.
+ */
+/**
+ * Compare an aligned scan against its original over a set of known rectangles.
+ *
+ * `aligned` must be the output of `alignScan` - or anything else already on the
+ * original's canvas. Feeding a raw scan in produces confident nonsense, because
+ * every rectangle then names a different part of the page in each image.
+ */
+export declare function compareRegions(original: ImageInput, aligned: ImageInput, regions: readonly Region[], options?: RegionOptions): Promise<RegionReport[]>;
+/** Page-wide added/removed ink, plus per-region detail for any regions supplied. */
+export declare function diffDocument(original: ImageInput, aligned: ImageInput, regions?: readonly Region[], options?: RegionOptions): Promise<DocumentDiff>;
+/** One region's added and removed ink, from masks already built. */
+export declare function measureRegion(region: Region, masks: Masks, defaultThreshold: number): RegionReport;
+//# sourceMappingURL=compare-regions.use-case.d.ts.map

package/dist/src/region-comparison/index.d.ts

@@ -0,0 +1,8 @@
+/** Which known rectangles gained ink, what changed page-wide, and an overlay to look at. */
+export { compareRegions, diffDocument, measureRegion } from './compare-regions.use-case.js';
+/** Consumed by change-detection, which builds the masks once per page and reads them several ways. */
+export { buildMasks } from './ink-masks.use-case.js';
+export type { Masks } from './ink-masks.use-case.js';
+export type { DocumentDiff, Region, RegionOptions, RegionReport } from './region.model.js';
+export { paintOverlay, renderDiff } from './render-diff.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/region-comparison/ink-masks.use-case.d.ts

@@ -0,0 +1,36 @@
+import type { BinaryImage, ImageInput, InkOptions } from '@scanmate/ink';
+/**
+ * The ink masks every comparison starts from, plus their tolerance bands.
+ *
+ * Both images must already share a canvas - that is what alignment is for - so
+ * a size mismatch is refused outright rather than compared into nonsense.
+ *
+ * ## Why "lost" uses a lower bar than "added"
+ *
+ * Deciding that the scan *added* ink and deciding that it *lost* ink are not
+ * symmetric, because scanning is not. A scanner washes colour out: on real
+ * scans a crisp red hyperlink came back pink and a purple header bar came back
+ * lavender, both light enough to fall below the scan's own ink threshold -
+ * which, judged by the same bar as added ink, reported them as missing on every
+ * page. Nothing had gone; it had faded. So the scan's ink is read twice: at its
+ * normal threshold for what it added, and at `faintInk` times that threshold for
+ * what is still there at all. Original ink counts as lost only where the scan
+ * shows none even at the lower bar. An erased word leaves bare paper, which
+ * fails both.
+ */
+export interface Masks {
+    width: number;
+    height: number;
+    original: BinaryImage;
+    /** The scan's ink at its normal threshold: what counts as *added*. */
+    scan: BinaryImage;
+    /** The scan's ink at the faint threshold: anything still there at all. */
+    scanFaint: BinaryImage;
+    originalDilated: BinaryImage;
+    /** `scanFaint`, fattened by the tolerance: original ink outside it is *lost*. */
+    scanDilated: BinaryImage;
+}
+/** Default for {@link buildMasks}' `faintInk`, measured against real scans. */
+export declare const FAINT_INK = 0.25;
+export declare function buildMasks(original: ImageInput, aligned: ImageInput, ink: InkOptions | undefined, tolerance: number, faintInk?: number): Promise<Masks>;
+//# sourceMappingURL=ink-masks.use-case.d.ts.map

package/dist/src/region-comparison/region.model.d.ts

@@ -0,0 +1,46 @@
+import type { InkOptions, Rect } from '@scanmate/ink';
+export interface Region {
+    id: string;
+    /** In the *original's* pixel coordinates - the whole point of aligning first. */
+    rect: Rect;
+    /** Fraction of the region that must be new ink before `filled` is true. Overrides the global default. */
+    threshold?: number;
+}
+export interface RegionOptions {
+    ink?: InkOptions;
+    /**
+     * Radius, in pixels, that the original's ink is fattened by before diffing.
+     * Raise it if alignment is loose; lower it to catch very fine additions.
+     */
+    tolerance?: number;
+    /** Default fraction of new ink that counts as filled. */
+    threshold?: number;
+    /**
+     * Scan ink fainter than this fraction of the scan's own ink threshold counts
+     * as gone. Anything lighter but still visible has faded, not disappeared -
+     * scanners wash colour out. Default `0.25`.
+     */
+    faintInk?: number;
+}
+export interface RegionReport {
+    id: string;
+    rect: Rect;
+    /** Ink coverage of the region in the original, in `[0, 1]`. */
+    originalInk: number;
+    /** Ink coverage of the region in the aligned scan. */
+    scanInk: number;
+    /** Coverage that is ink in the scan and not within `tolerance` of ink in the original. */
+    added: number;
+    /** Coverage that is ink in the original and missing from the scan. Mostly a faint-scan warning. */
+    removed: number;
+    filled: boolean;
+    /** `added` as a multiple of the threshold, clamped to `[0, 1]`. A reportable confidence. */
+    score: number;
+}
+export interface DocumentDiff {
+    /** Page-wide version of {@link RegionReport.added}. */
+    added: number;
+    removed: number;
+    regions: RegionReport[];
+}
+//# sourceMappingURL=region.model.d.ts.map

package/dist/src/region-comparison/render-diff.use-case.d.ts

@@ -0,0 +1,15 @@
+import type { ImageInput, Raster } from '@scanmate/ink';
+import type { Masks } from './ink-masks.use-case.js';
+import type { RegionOptions } from './region.model.js';
+/**
+ * An RGBA overlay of the comparison, for looking at with your own eyes.
+ *
+ * Red is ink the scan added, blue is ink it lost, grey is ink both agree on.
+ * A correctly aligned pair of a signed form is almost entirely grey with a red
+ * signature; a misaligned one is red and blue confetti along every stroke,
+ * which is the fastest way to tell the two failures apart.
+ */
+export declare function renderDiff(original: ImageInput, aligned: ImageInput, options?: RegionOptions): Promise<Raster>;
+/** The overlay, from masks already built. Red added, blue lost, grey agreed, white paper. */
+export declare function paintOverlay(masks: Masks): Raster;
+//# sourceMappingURL=render-diff.use-case.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@scanmate/diff",
+  "version": "0.0.2",
+  "description": "What changed between an original and its aligned scan: expected regions filled in, unexpected marks, lost ink, and a side-by-side evidence image.",
+  "license": "MIT",
+  "author": "Eduardo Russo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/russoedu/scanmate.git",
+    "directory": "packages/diff"
+  },
+  "homepage": "https://github.com/russoedu/scanmate/tree/main/packages/diff#readme",
+  "bugs": {
+    "url": "https://github.com/russoedu/scanmate/issues"
+  },
+  "keywords": [
+    "scan",
+    "diff",
+    "signature-detection",
+    "document",
+    "verification"
+  ],
+  "type": "module",
+  "main": "./dist/index.esm.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "default": "./dist/index.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo",
+    "!**/*.d.ts.map",
+    "!**/*.js.map"
+  ],
+  "dependencies": {
+    "@scanmate/ink": "^0.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@scanmate/align": "^0.0.2"
+  }
+}