browser-broker 0.1.0

package/dist/src/browser/setup.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { StartupRefusal } from "../errors.js";
+import { profileDirectory } from "./discovery.js";
+import { DEFAULT_BROWSER_IDS } from "./driver.js";
+/** The refusals this module raises, spelled as §7.2 spells them. */
+export const SETUP_RULES = {
+    profileNeverDestroyed: 'setup.profile_never_destroyed',
+};
+/**
+ * The lock a running browser leaves in its profile directory.
+ *
+ * ⚠️ **This is checked as evidence, never as a gate, and the difference is
+ * measured.** The single-instance lock a POSIX system leaves behind **does
+ * not exist on Windows**, so a cross-platform check looking for it does not
+ * report *no lock* there — it **always passes**. A guard that cannot fail on
+ * one platform is worse than no guard, because it is trusted equally on both.
+ *
+ * So this is used only in the direction where a positive result is
+ * meaningful: **finding one means a browser is very likely running**, which
+ * is worth naming in a refusal. Not finding one means **nothing at all**, and
+ * this module never concludes a profile is free from its absence. What
+ * actually establishes whether a browser is running is the verified discovery
+ * record (§1.2c), which works on every platform.
+ */
+const LOCK_ENTRIES = ['SingletonLock', 'SingletonSocket'];
+/**
+ * Whether another process appears to hold this profile.
+ *
+ * Returns `false` on every platform where the mechanism does not exist, which
+ * is why the caller must not read `false` as *the profile is free*. See
+ * {@link LOCK_ENTRIES}.
+ */
+export function profileLockLooksHeld(profileDir) {
+    for (const entry of LOCK_ENTRIES) {
+        try {
+            // `lstat`, not `stat`: the lock is a symbolic link whose target host
+            // and process need not exist, and following it would report absent for
+            // a lock that is present.
+            fs.lstatSync(path.join(profileDir, entry));
+            return true;
+        }
+        catch {
+            // Absent, or a platform without the mechanism. Both mean "no evidence",
+            // which is not the same as "no lock".
+        }
+    }
+    return false;
+}
+const REAL_FILESYSTEM = {
+    mkdirSync: (dir, options) => {
+        fs.mkdirSync(dir, options);
+    },
+    writeFileSync: (file, data) => {
+        fs.writeFileSync(file, data);
+    },
+    rmSync: (file, options) => {
+        fs.rmSync(file, options);
+    },
+};
+function assertProfileRootWritable(profileRoot, filesystem = REAL_FILESYSTEM) {
+    try {
+        filesystem.mkdirSync(profileRoot, { recursive: true });
+    }
+    catch (error) {
+        throw new StartupRefusal(SETUP_RULES.profileNeverDestroyed, `The profile root could not be created, so no browser profile can be established under it: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const probe = path.join(profileRoot, `.write-probe-${String(process.pid)}`);
+    try {
+        filesystem.writeFileSync(probe, '');
+        filesystem.rmSync(probe, { force: true });
+    }
+    catch (error) {
+        throw new StartupRefusal(SETUP_RULES.profileNeverDestroyed, `The profile root is not writable, so a profile that is absent could not be created: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+/**
+ * Establish one profile: create it if absent, use it as it is if present.
+ *
+ * **Never recreated, never cleared** — the whole of §1.2d's rule, and the
+ * reason the two branches differ only in whether a directory is made.
+ */
+function establishProfile(profileRoot, browser) {
+    const directory = profileDirectory(profileRoot, browser);
+    let present;
+    try {
+        present = fs.statSync(directory).isDirectory();
+    }
+    catch {
+        present = false;
+    }
+    if (present) {
+        if (profileLockLooksHeld(directory)) {
+            // Named in plain words rather than reported as a generic launch
+            // failure, because this is exactly the case the design protects
+            // against and a caller reading it needs to know it is not a bug.
+            throw new StartupRefusal(SETUP_RULES.profileNeverDestroyed, `The ${browser} browser's profile directory exists and another process holds its lock. Setup will not recreate or clear it: that profile holds a sign-in a person established by hand, and recreating it would sign them out. Close the other browser running against this profile, or attach to it instead of starting a second one.`);
+        }
+        // Found and used exactly as it is. No inspection of its contents, no
+        // repair, no clearing — there is deliberately no branch here that could
+        // decide a profile looks wrong.
+        return { browser, disposition: 'found', relativePath: browser };
+    }
+    fs.mkdirSync(directory, { recursive: true });
+    return { browser, disposition: 'created', relativePath: browser };
+}
+/**
+ * Run the handshake: confirm the two browser rows, and establish both
+ * profiles.
+ *
+ * The schema has already been stepped by the time this runs — `prepareStore`
+ * does it, and `startup.schema_stepped` (§7.2) puts it before anything else
+ * happens. This confirms the result rather than repeating it.
+ */
+export async function runSetupHandshake(store, profileRoot, options = {}) {
+    assertProfileRootWritable(profileRoot, options.filesystem);
+    // The configured browsers, or the ones the default configuration names.
+    // **The default is a fallback for a caller that has no environment
+    // snapshot to hand, never a statement about what this installation has** —
+    // every shipped caller passes the configured lists.
+    const browsers = options.browsers ?? DEFAULT_BROWSER_IDS;
+    const schemaVersion = await store.immediate(({ db }) => {
+        // The version is stamped in the store's own header rather than in a
+        // table, so it is read the way the stepper writes it.
+        const version = db.pragma('user_version', { simple: true });
+        // **The row count is deliberately not asserted, and that is a decision
+        // rather than an omission** (`DECISIONS.md` §13i). A browser's row is
+        // created when it is first launched, not from configuration at startup,
+        // so a store holding fewer rows than this process has browsers
+        // configured is the ordinary state of a fresh installation rather than a
+        // fault — and two processes may hold different configurations, so no
+        // count is the right count for all of them.
+        //
+        // What that check was actually protecting — *is this store stepped* — is
+        // read directly from the version the stepper stamps, which is the fact
+        // it was standing in for.
+        return { value: typeof version === 'number' ? version : 0 };
+    });
+    // Outside the transaction, deliberately. Creating a directory is filesystem
+    // work and the arbitration transaction serialises every writer on the
+    // machine — holding it open across a filesystem call on a slow or contended
+    // volume would block every other caller for that duration.
+    const profiles = browsers.map((browser) => establishProfile(profileRoot, browser));
+    return {
+        profiles,
+        browserRows: [...browsers],
+        schemaVersion,
+    };
+}
+/**
+ * The report as a line per profile, saying which it created against which it
+ * found.
+ *
+ * §1.2d asks setup to *report which profiles it created and which it found*,
+ * and the distinction is the useful part: a profile reported as created on a
+ * machine where somebody expected a sign-in is the earliest possible warning
+ * that they are about to be asked to sign in again.
+ */
+export function describeSetupReport(report) {
+    return report.profiles.map((profile) => `${profile.browser}: profile ${profile.disposition} at ${profile.relativePath} (under the configured profile root)`);
+}

package/dist/src/capture/accounting.js

@@ -0,0 +1,59 @@
+import { CAPTURES_BEFORE_WARNING } from "./tiers.js";
+/**
+ * Capture accounting per claim: **a loud warning, never a refusal**
+ * (`MILESTONES.md` #33, `SCHEMA.md` §3.11, §6.2, §7.3).
+ *
+ * ── The two properties, and why each is written the way it is ───────────
+ *
+ * **1. It never refuses.** There is no code path in this file that can
+ * produce a refusal, and that is structural rather than careful: the only
+ * thing exported is a function returning a **string or nothing**. There is no
+ * boolean anything downstream could branch on to deny, no threshold parameter
+ * an operator could raise into a wall, and no error type. `SCHEMA.md` §6.2
+ * deletes the setting outright — *"No 'refuse captures after N'. Nothing is
+ * ever refused on capture grounds, and a value that could turn a warning into
+ * a wall would make that promise conditional."* And §7.3's
+ * `capture.never_refused_for_cost` is the build rule asserting that absence.
+ *
+ * The reasoning, from `DECISIONS.md` §13d, is worth carrying rather than
+ * citing: **an agent stopped mid-run on a legitimate job concludes the service
+ * is an obstacle and starts looking for a way around it.** A service that is
+ * occasionally expensive survives that; a service that is occasionally
+ * *unusable* does not.
+ *
+ * **2. The message names the cheaper alternative, and that is the mechanism
+ * rather than decoration.** `MILESTONES.md` #33: a bare *"you have taken a lot
+ * of captures"* teaches a caller to ask for a bigger budget. A warning that
+ * **names the snapshot or the evaluation answering the same question** teaches
+ * the thing the policy exists to teach. So the text below is the row, and a
+ * change that shortened it into a bare count would pass every test that only
+ * checked a warning was present — which is why the test for this names the
+ * alternative it must mention.
+ *
+ * **3. It fires on every capture past the threshold, not only the first**
+ * (§3.11), *"because a warning that appears once has scrolled away by the time
+ * it matters."*
+ */
+/**
+ * The warning for a capture that is past the threshold, or nothing.
+ *
+ * @param capturesTakenBefore how many captures this lease had already taken
+ *   when this one was requested. Counted before rather than after, so the
+ *   caller of this function does not have to know whether the current capture
+ *   is included — an ambiguity that would put the boundary one either side of
+ *   where §6.2 puts it depending on who read it.
+ *
+ * @returns the warning text, or `undefined` when there is nothing to say.
+ *   **Never a refusal, and there is no shape here that could become one.**
+ */
+export function captureWarning(capturesTakenBefore) {
+    const thisCapture = capturesTakenBefore + 1;
+    if (thisCapture <= CAPTURES_BEFORE_WARNING)
+        return undefined;
+    return (`This lease has now taken ${String(thisCapture)} captures, past the point where a picture is ` +
+        `usually the expensive way to get an answer. This capture was served and always will be — ` +
+        `nothing here is ever refused on cost grounds. But if you are reading a value or checking ` +
+        `that an element is present, a snapshot or an evaluation returns it as text for a fraction ` +
+        `of what an image costs, because an image is re-read on every later turn of the ` +
+        `conversation and text is not.`);
+}

package/dist/src/capture/image.js

@@ -0,0 +1,112 @@
+// The one place an image library is reached, for the same reason `open.ts` is
+// the one place the database driver is. Decoding and re-encoding a PNG is the
+// only image work this service does, and keeping it behind one module is what
+// makes the choice reversible without touching the pipeline.
+import { PNG } from 'pngjs';
+/** Decode an encoded PNG into pixels. */
+export function decodePng(encoded) {
+    const png = PNG.sync.read(Buffer.from(encoded));
+    return { width: png.width, height: png.height, pixels: new Uint8Array(png.data) };
+}
+/** Encode pixels back into a PNG. */
+export function encodePng(image) {
+    const png = new PNG({ width: image.width, height: image.height });
+    png.data = Buffer.from(image.pixels);
+    return new Uint8Array(PNG.sync.write(png));
+}
+/**
+ * What a picture becomes when its long edge is capped.
+ *
+ * **The aspect ratio is preserved and the short edge is never rounded to
+ * zero.** A one-pixel-tall banner shrunk by a large factor would otherwise
+ * produce a zero-height image, which is not an image; the schema's
+ * `CHECK (height > 0)` would refuse the row, far away from the cause.
+ */
+export function scaledDimensions(width, height, longestEdge) {
+    const longest = Math.max(width, height);
+    // **Never upscale.** A picture smaller than the rung is written as it is,
+    // which is what makes `captures.width === captures.source_width` mean
+    // "nothing was shrunk" (§1.7) rather than "nothing needed to be".
+    if (longest <= longestEdge)
+        return { width, height };
+    const factor = longestEdge / longest;
+    return {
+        width: Math.max(1, Math.round(width * factor)),
+        height: Math.max(1, Math.round(height * factor)),
+    };
+}
+/**
+ * Shrink a picture to a target size by averaging each destination pixel over
+ * the source region it covers.
+ *
+ * A box filter rather than nearest-neighbour sampling, and the difference
+ * matters for what this service is for: nearest-neighbour throws away every
+ * source pixel but one, so a one-pixel rule or a thin line lands on a sampled
+ * pixel or vanishes entirely depending on where it happened to fall.
+ * Averaging keeps it as a fainter line, which is what a caller judging layout
+ * needs to still be able to see. It is also what makes the later diff's
+ * "smallest change reported" bound (§6.2) meaningful rather than a lottery.
+ *
+ * **Returns the same image when nothing needs shrinking**, so a caller cannot
+ * tell "already small enough" from "shrunk by a factor of one" by looking at
+ * the pixels — they are the same picture either way, which is the honest
+ * answer.
+ */
+export function downscale(image, longestEdge) {
+    const target = scaledDimensions(image.width, image.height, longestEdge);
+    if (target.width === image.width && target.height === image.height)
+        return image;
+    const pixels = new Uint8Array(target.width * target.height * 4);
+    const xRatio = image.width / target.width;
+    const yRatio = image.height / target.height;
+    for (let y = 0; y < target.height; y++) {
+        // The source rows this destination row covers. `Math.ceil` on the end and
+        // a floor on the start means adjacent destination pixels tile the source
+        // without gaps, so no source pixel is skipped by rounding.
+        const yStart = Math.floor(y * yRatio);
+        const yEnd = Math.min(image.height, Math.max(yStart + 1, Math.ceil((y + 1) * yRatio)));
+        for (let x = 0; x < target.width; x++) {
+            const xStart = Math.floor(x * xRatio);
+            const xEnd = Math.min(image.width, Math.max(xStart + 1, Math.ceil((x + 1) * xRatio)));
+            let red = 0;
+            let green = 0;
+            let blue = 0;
+            let alpha = 0;
+            let counted = 0;
+            for (let sourceY = yStart; sourceY < yEnd; sourceY++) {
+                for (let sourceX = xStart; sourceX < xEnd; sourceX++) {
+                    const at = (sourceY * image.width + sourceX) * 4;
+                    red += image.pixels[at] ?? 0;
+                    green += image.pixels[at + 1] ?? 0;
+                    blue += image.pixels[at + 2] ?? 0;
+                    alpha += image.pixels[at + 3] ?? 0;
+                    counted++;
+                }
+            }
+            const to = (y * target.width + x) * 4;
+            pixels[to] = Math.round(red / counted);
+            pixels[to + 1] = Math.round(green / counted);
+            pixels[to + 2] = Math.round(blue / counted);
+            pixels[to + 3] = Math.round(alpha / counted);
+        }
+    }
+    return { width: target.width, height: target.height, pixels };
+}
+/**
+ * A solid picture of a given size, encoded.
+ *
+ * Used by the fake driver so that a test's canned capture is something the
+ * pipeline can genuinely decode, and by tests that need a picture of known
+ * dimensions. It lives here rather than in the fake because the fake must not
+ * be the only thing that knows how to make one.
+ */
+export function solidPng(width, height, colour = [255, 255, 255, 255]) {
+    const pixels = new Uint8Array(width * height * 4);
+    for (let at = 0; at < pixels.length; at += 4) {
+        pixels[at] = colour[0];
+        pixels[at + 1] = colour[1];
+        pixels[at + 2] = colour[2];
+        pixels[at + 3] = colour[3];
+    }
+    return encodePng({ width, height, pixels });
+}

package/dist/src/capture/ladder.js

@@ -0,0 +1,72 @@
+/**
+ * The resolution-ladder harness (`MILESTONES.md` #34).
+ *
+ * Sweeps one picture down a ladder of longest-edge caps and records, per rung,
+ * what the study needs to compare rungs against each other: **the dimensions,
+ * the bytes, the downscale ratio, and the estimated token cost.**
+ *
+ * ── It measures the pipeline that ships, not a better one ───────────────
+ *
+ * Every rung here goes through {@link downscale} and {@link encodePng} — the
+ * same box filter and the same encoder the capture pipeline uses. That is the
+ * point rather than an economy: `image.ts` names its resampler's cost outright
+ * (box averaging is softer than a bicubic or Lanczos filter), and a study run
+ * on a hypothetical better resampler would settle rungs this service does not
+ * have. **The numbers this produces are only claims about this pipeline.**
+ *
+ * ── Where the fields come from ──────────────────────────────────────────
+ *
+ * `bytes` is the length of the re-encoded PNG, which is what `captures.bytes`
+ * records (§1.7) and therefore comparable with a real capture's telemetry.
+ * `estimatedTokens` comes from {@link estimateTokens} — the formula §6.4 fixes
+ * by the version, taking dimensions and nothing else, so a rung's cost here is
+ * computed exactly as a live capture's is.
+ *
+ * **This harness reaches no store and no browser.** It takes decoded pixels and
+ * returns numbers, which is what lets the study run its arithmetic rungs in
+ * continuous integration with no browser binary while the rendered-text rungs
+ * skip.
+ */
+import { downscale, encodePng, scaledDimensions } from "./image.js";
+import { estimateTokens } from "./tiers.js";
+/**
+ * Sweep one picture down a ladder of caps.
+ *
+ * The rungs are given rather than read from {@link TIER_LONGEST_EDGE}, because
+ * a study that could only measure the three numbers already shipped could never
+ * discover that a fourth is better. The shipped rungs are one input among
+ * several.
+ */
+export function sweepLadder(source, rungs) {
+    return rungs.map((longestEdge) => {
+        const shrunk = downscale(source, longestEdge);
+        const target = scaledDimensions(source.width, source.height, longestEdge);
+        const longest = Math.max(source.width, source.height);
+        return {
+            longestEdge,
+            width: shrunk.width,
+            height: shrunk.height,
+            bytes: encodePng(shrunk).length,
+            // Guarded against a zero-size source, which is not an image but is also
+            // not this function's business to refuse.
+            ratio: longest === 0 ? 1 : Math.min(1, target.width / Math.max(1, source.width)),
+            estimatedTokens: estimateTokens(shrunk.width, shrunk.height),
+            image: shrunk,
+        };
+    });
+}
+/**
+ * Render a sweep as a table, for the study's own report.
+ *
+ * Plain text rather than anything structured: this exists so a measurement can
+ * be **read** in a pull request body and checked against the assertions that
+ * quote it, which is the whole difference between publishing evidence and
+ * publishing numbers.
+ */
+export function formatLadder(rungs) {
+    const header = '| long edge | dimensions | ratio | bytes | est. tokens |';
+    const rule = '|---|---|---|---|---|';
+    const rows = rungs.map((rung) => `| ${String(rung.longestEdge)} | ${String(rung.width)}x${String(rung.height)} | ` +
+        `${rung.ratio.toFixed(3)} | ${String(rung.bytes)} | ${String(rung.estimatedTokens)} |`);
+    return [header, rule, ...rows].join('\n');
+}

package/dist/src/capture/legibility.js

@@ -0,0 +1,195 @@
+/**
+ * Objective, OCR-free proxies for what survives a downscale — the instruments
+ * the resolution study (`MILESTONES.md` #34) measures the rungs with.
+ *
+ * ── Why proxies, and what they are honestly worth ───────────────────────
+ *
+ * The claim the tiers rest on is a claim about **a reader**: *text legibility
+ * breaks at a higher resolution than layout critique does.* Settling that
+ * directly would mean asking somebody whether they can read a picture, at
+ * every rung, on every page — a judgement no test can make and no assertion
+ * can hold.
+ *
+ * So this module does not attempt it. It measures **physical properties of the
+ * pixels** that legibility depends on, and it is deliberate that each one is
+ * arithmetic over an array rather than an opinion:
+ *
+ * - {@link strokeContrast} — how much of a glyph's ink survives. A stroke
+ *   thinner than a destination pixel is averaged into its background by the
+ *   box filter, and what is left is a fainter mark on a lighter field. This
+ *   reports how far the darkest ink moved toward the page.
+ * - {@link featureSurvives} — whether a **known** one-pixel feature is still
+ *   distinguishable from the field around it at all. This is the layout-side
+ *   instrument: a hairline rule, a border, a focus ring.
+ * - {@link countDistinctRuns} — how many separate dark runs remain along a
+ *   line. Two glyphs that merge into one blob have lost the gap between them,
+ *   and a merged gap is the mechanism by which text stops being readable
+ *   before it stops being visible.
+ *
+ * ── ⚠️ WHAT THESE DO NOT ESTABLISH — read before quoting a number ───────
+ *
+ * **None of these is a legibility measurement, and no number here should be
+ * reported as one.** A proxy presented as an answer is worse than an honest
+ * gap. Specifically:
+ *
+ * 1. **A surviving stroke is not a readable glyph.** {@link strokeContrast}
+ *    can report healthy contrast on a letter whose distinguishing feature —
+ *    the gap that separates an `e` from a `c` — has closed. Contrast is
+ *    necessary for legibility and nowhere near sufficient.
+ * 2. **These say nothing about a model's vision.** What an agent looking at a
+ *    picture can actually resolve is a property of that model, not of the
+ *    pixels. These measure what the *pipeline* destroys, which bounds what any
+ *    reader could recover but does not predict what one will.
+ * 3. **They are measured on synthetic marks of known geometry**, not on
+ *    rendered prose. That is what makes them arithmetic rather than opinion,
+ *    and it is also why they cannot speak to font hinting, subpixel rendering
+ *    or the shapes of real letterforms.
+ *
+ * They are, within those limits, enough to answer the *comparative* question
+ * the study asks — whether the resolution at which fine text detail is
+ * destroyed is higher than the one at which a layout-scale feature is — because
+ * both sides are measured with the same instrument on the same ladder.
+ *
+ * ── This is orthogonal to the differ's tolerance ────────────────────────
+ *
+ * A separate measured limit exists in this repository: at the default
+ * tolerance a change fainter than roughly grey 225 on white is not reported.
+ * **That is a property of the comparison, not of resolution** — it says what
+ * the differ can see, and this module says what the downscale leaves behind.
+ * They are different questions and their numbers do not combine.
+ */
+/**
+ * Whether a row is actually on the picture.
+ *
+ * **A row off the end must refuse rather than read as blank.** A scan over a
+ * row that does not exist finds no ink, and "no ink" is indistinguishable from
+ * "the mark was averaged away" — so an off-by-one in a caller's row arithmetic
+ * would report a *destroyed feature* instead of a mistake, which is the study
+ * measuring nothing and saying so confidently. This was a real defect here: a
+ * shrink that moved a mark off the sampled row reported full contrast from an
+ * empty scan.
+ */
+function requireRow(image, row) {
+    if (!Number.isInteger(row) || row < 0 || row >= image.height) {
+        throw new RangeError(`row ${String(row)} is not on a picture ${String(image.width)}x${String(image.height)}: an off-picture row finds no ink, which would be misread as a destroyed feature`);
+    }
+}
+/** Luminance of one pixel, 0 (black) to 255 (white). */
+function luminanceAt(image, x, y) {
+    const at = (y * image.width + x) * 4;
+    const red = image.pixels[at] ?? 0;
+    const green = image.pixels[at + 1] ?? 0;
+    const blue = image.pixels[at + 2] ?? 0;
+    // Rec. 601 luma. The weights matter for coloured text; for the black-on-white
+    // marks this study uses, any reasonable weighting gives the same answer.
+    return 0.299 * red + 0.587 * green + 0.114 * blue;
+}
+/**
+ * How dark the darkest ink on a row still is, as a fraction of the original
+ * ink-to-background contrast.
+ *
+ * `1` means the mark survived at full strength; `0` means it was averaged away
+ * into the background entirely. A thin stroke shrunk past the point where it
+ * covers a whole destination pixel loses contrast in proportion to the fraction
+ * of that pixel it covers, which is exactly what a box filter does and exactly
+ * what this reports.
+ *
+ * @param background the field's luminance, which the mark is measured against.
+ * @param ink the mark's original luminance, before any shrinking.
+ */
+export function strokeContrast(image, row, background, ink) {
+    requireRow(image, row);
+    const full = Math.abs(background - ink);
+    if (full === 0)
+        return 0;
+    // The pixel on this row furthest from the background is the surviving ink.
+    let furthest = 0;
+    for (let x = 0; x < image.width; x++) {
+        const distance = Math.abs(luminanceAt(image, x, row) - background);
+        if (distance > furthest)
+            furthest = distance;
+    }
+    return Math.min(1, furthest / full);
+}
+/**
+ * Whether a known feature is still distinguishable from its background.
+ *
+ * **The threshold is stated as an argument rather than chosen here**, because
+ * "distinguishable" is the thing under study: a caller sweeping the ladder
+ * decides what fraction of the original contrast it is willing to call
+ * survival, and the sweep reports the answer at each. A constant baked in here
+ * would be this module quietly deciding the study's result.
+ */
+export function featureSurvives(image, row, background, ink, minimumContrast) {
+    return strokeContrast(image, row, background, ink) >= minimumContrast;
+}
+/**
+ * The strongest measurement anywhere in the picture, rather than on a row a
+ * caller had to predict.
+ *
+ * **This exists because mapping a source row to a destination row is not a
+ * measurement, it is a guess.** A mark 24 source pixels tall shrunk by 0.32
+ * lands across some 7 destination rows, and which of them carries the most ink
+ * depends on where the box filter's boundaries fell — so a study that computed
+ * `sourceRow * ratio` and read that one row would report a number that swings
+ * with rounding rather than with resolution. Scanning every row and taking the
+ * best removes that artefact entirely: the answer is *"the most that survived
+ * anywhere"*, which is the generous reading and therefore the honest one for a
+ * claim about what is destroyed.
+ *
+ * Returns the best run count and the contrast on the row that achieved it.
+ */
+export function bestSurvivingRow(image, background, ink, minimumContrast) {
+    let runs = 0;
+    let contrast = 0;
+    let row = 0;
+    for (let y = 0; y < image.height; y++) {
+        const here = countDistinctRuns(image, y, background, ink, minimumContrast);
+        if (here > runs) {
+            runs = here;
+            contrast = strokeContrast(image, y, background, ink);
+            row = y;
+        }
+    }
+    // A picture whose marks all fell below the ink threshold has no run anywhere;
+    // report the strongest contrast that survived, which is the fading a hairline
+    // shows before it disappears.
+    if (runs === 0) {
+        for (let y = 0; y < image.height; y++) {
+            const here = strokeContrast(image, y, background, ink);
+            if (here > contrast) {
+                contrast = here;
+                row = y;
+            }
+        }
+    }
+    return { runs, contrast, row };
+}
+/**
+ * How many separate dark runs remain along a row.
+ *
+ * This is the gap-closing instrument. A row of alternating one-pixel ink and
+ * one-pixel space has as many runs as it has marks; once the shrink averages
+ * neighbouring marks together the runs merge, and the count falls. **The count
+ * falling is the mechanism by which text becomes unreadable while remaining
+ * visible** — the ink is still there, the spaces between letters are not.
+ *
+ * A pixel counts as ink when it is at least `minimumContrast` of the way from
+ * the background toward the original ink, using the same scale
+ * {@link strokeContrast} reports on.
+ */
+export function countDistinctRuns(image, row, background, ink, minimumContrast) {
+    requireRow(image, row);
+    const full = Math.abs(background - ink);
+    if (full === 0)
+        return 0;
+    let runs = 0;
+    let inRun = false;
+    for (let x = 0; x < image.width; x++) {
+        const isInk = Math.abs(luminanceAt(image, x, row) - background) / full >= minimumContrast;
+        if (isInk && !inRun)
+            runs++;
+        inRun = isInk;
+    }
+    return runs;
+}