feat(scanmate-scan): port illumination correction, bit-exact

[russoedu]

Levelling and contrast: enhance_raster, estimate_contrast_points and
resolve_contrast_points, with the options and the applied-enhancement report. Every page
is compared to the TypeScript as a whole image, sha256 over every byte, not sampled.

The two roundings, and why thirteen random pages don't catch them

Two roundings sit side by side in this slice, and either would be right on most pixels on
its own:

• the contrast stretch rounds a half up (Math.round)
• the unsharp mask writes into a Uint8ClampedArray, which rounds a half to even

A generated document never lands on a half, so both survive a whole-image hash of
thirteen random pages — which is exactly how a port using one rule for both would have
passed. Mutation testing said so, against a test file whose own docstring claimed the hash
covered it. It didn't.

So this adds pages built by hand, as recipes both sides follow. On a uniform page the
background mean is the page, so every ratio is exactly 1 and the stretch lands on exactly
255/6 = 42.5. The TypeScript reads 43; half-to-even would read 42.

The same reasoning applies to the contrast points. A generated page pins none of the
bounds — its percentiles land mid-block among near-identical ratios, where moving one by a
percent changes nothing. Two grey pages with a chosen histogram put a single pixel on
each boundary instead: both percentiles, both clamps, the >= the cumulative count is
tested with, and a ratio of 0.25, whose histogram position is exactly 42.5 — the one
value where the bin rounding is observable at all.

Absent, on purpose

sharpen_raster — it is this same unsharp mask with the blur done by libvips, and
blur_raster is absent from scanmate-ink for the reason that package's README gives.
sharpen here uses the box-blur mask, which is the one the sharpening was tuned with.

Mutation testing

23 mutants, 20 killed. The first pass killed 9 of 23; the fixtures above closed eleven
more. The three survivors are each provably equivalent or unreachable rather than untested,
and TestWhatNoFixtureCanSeparate asserts the fact that makes each safe:

Survivor	Why no input separates it
min(high, max(low, v)) ↔ max(low, min(high, v))	equal whenever low <= high, and both call sites pass literals that satisfy it
alpha taken from the despeckled pixels or the raw ones	despeckle copies alpha rather than filtering it, so they are equal for every page
the blur's own max(1, …) radius floor	the background radius is already floored at 4 before the blur sees it

Each is kept as written because the TypeScript is written that way — a reader comparing the
two files should find the same expression, not a locally-simplified one.

Also here

@mnci/nx-python-pip 0.2.10 (its own commit), which is the fix for this workspace's red
release: its twine executor now skips a project with no new version, so a release stops
uploading every Python package — the unbumped ones from their permanently-stale on-disk
0.0.1. That is what created the junk 0.0.1 releases on PyPI and what spent the
new-project rate limit that 429'd [email protected].

npm install dropped the four nested @emnapi entries under the wasm32-wasi resolver
bindings again (fourth time), which breaks npm ci; restored, and npm ci re-verified.

Verification

lint typecheck test build green for scanmate-scan; root ESLint clean; nx run-many -t test green across all 15 projects; parity:check reports the goldens fresh
against a real TypeScript build. 43 tests in the new slice.

🤖 Generated with Claude Code