browser-broker 0.1.0

package/dist/src/diff/geometry.js

@@ -0,0 +1,122 @@
+/**
+ * Geometry reconciliation — what happens when the two pictures are not the
+ * same size (`SCHEMA.md` §1.9, §3.11, `MILESTONES.md` #40).
+ *
+ * ── The coupling this file exists to keep cut ───────────────────────────
+ *
+ * §3.11 records an arrangement that was deliberately deleted: a capture that
+ * consulted a canonical picture for the view it named and **took the picture
+ * at that picture's geometry**. That made the ordinary capture path depend on
+ * the comparison feature's data model, and gave every capture a reason to fail
+ * that had nothing to do with capturing.
+ *
+ * **So geometry is handled here, at diff time, where both images are already
+ * in hand.** Nothing constrains a capture, and a mismatch is reported against
+ * the specific pair that mismatched rather than pre-empted by a rule.
+ *
+ * ── The two mismatches are not the same fact, and that is the design ────
+ *
+ * - **A width mismatch is reported in the result.** Two pictures of the same
+ *   page at different widths are pictures of different layouts, and a diff
+ *   over them is close to meaningless — nearly every pixel moves. It is still
+ *   not a refusal: the caller gets its picture and the fact, per §1.9's
+ *   standing rule that a diff is an optional argument whose failure cannot
+ *   withhold a screenshot that succeeded.
+ * - **A full page's height is allowed to differ**, because "two full-page
+ *   pictures of one page legitimately differ in height when the content gets
+ *   longer" (§3.11). The change in page length is reported **as its own fact
+ *   rather than as a region** — a page that grew by two hundred pixels has not
+ *   changed in two hundred places, and reporting the growth as a region would
+ *   drown the actual change.
+ *
+ * **The comparison runs over the height they share** (§3.11), which is the
+ * only region where the question "did this pixel change" has an answer at all.
+ */
+/**
+ * Reconcile the two geometries.
+ *
+ * Takes the kind of the **new** capture. The earlier capture's own kind is
+ * deliberately not consulted: what a caller can act on is what it just asked
+ * for, and a full-page picture compared against a viewport one is a caller
+ * mistake that the page-length fact describes perfectly well without a second
+ * enumeration of which-kind-against-which-kind.
+ */
+export function reconcileGeometry(earlier, current, kind) {
+    const widthMismatch = earlier.width !== current.width;
+    // A width mismatch stops the comparison outright. There is no honest
+    // sub-rectangle to fall back to: content reflows across a width change, so
+    // the leftmost shared column of a 1024-wide page is not the same content as
+    // the leftmost shared column of a 1440-wide one. Comparing the overlap
+    // would produce a confident number about two different layouts.
+    if (widthMismatch) {
+        return {
+            width: null,
+            comparableHeight: null,
+            widthMismatch: true,
+            pageLengthChange: null,
+            comparable: false,
+            explanation: `The two captures are different widths — the earlier one is ${String(earlier.width)} pixels ` +
+                `wide and this one is ${String(current.width)}. No diff was produced: content reflows across a ` +
+                'width change, so comparing them would report a difference at nearly every pixel. Capture both at ' +
+                'the same viewport width to compare them.',
+        };
+    }
+    const heightMismatch = earlier.height !== current.height;
+    const fullPage = kind === 'full_page';
+    if (!heightMismatch) {
+        return {
+            width: current.width,
+            comparableHeight: current.height,
+            widthMismatch: false,
+            pageLengthChange: null,
+            comparable: true,
+            explanation: null,
+        };
+    }
+    // A height mismatch on anything but a full page is the same situation a
+    // width mismatch is: a viewport is a fixed rectangle, so two viewport
+    // pictures of different heights were taken at different viewport sizes, and
+    // an element that changed height changed shape rather than grew a page.
+    if (!fullPage) {
+        return {
+            width: null,
+            comparableHeight: null,
+            widthMismatch: false,
+            pageLengthChange: null,
+            comparable: false,
+            explanation: `The two captures are different heights — the earlier one is ${String(earlier.height)} pixels ` +
+                `tall and this one is ${String(current.height)} — and this is a ${kind} capture, whose height is ` +
+                'fixed by what was captured rather than by how much content there was. No diff was produced. A ' +
+                'full-page capture is the one whose height is allowed to differ.',
+        };
+    }
+    const shared = Math.min(earlier.height, current.height);
+    const change = current.height - earlier.height;
+    // Two full pages that share no rows at all. Vanishingly unlikely in
+    // practice and still a real shape — a page that failed to render is one
+    // pixel tall — and a comparison over zero rows would report zero changed
+    // pixels, which reads as "nothing changed".
+    if (shared <= 0) {
+        return {
+            width: null,
+            comparableHeight: null,
+            widthMismatch: false,
+            pageLengthChange: change,
+            comparable: false,
+            explanation: `The two full-page captures share no rows to compare — the earlier one is ` +
+                `${String(earlier.height)} pixels tall and this one is ${String(current.height)}. No diff was ` +
+                'produced.',
+        };
+    }
+    return {
+        width: current.width,
+        comparableHeight: shared,
+        widthMismatch: false,
+        pageLengthChange: change,
+        comparable: true,
+        explanation: `The page got ${change > 0 ? 'longer' : 'shorter'} by ${String(Math.abs(change))} pixels — the ` +
+            `earlier capture is ${String(earlier.height)} tall and this one is ${String(current.height)}. That ` +
+            `is reported as a change in page length rather than as a changed region. The comparison ran over ` +
+            `the top ${String(shared)} rows they share.`,
+    };
+}

package/dist/src/diff/image.js

@@ -0,0 +1,132 @@
+import { PNG } from 'pngjs';
+/**
+ * A decoded image, and the two operations the comparison feature performs on
+ * one: cutting a rectangle out of it, and drawing a rectangle onto it.
+ *
+ * **Why this file exists at all**, given that the comparison itself is a
+ * library call: the library takes raw pixel buffers and returns a count. It
+ * does not decode a file, it does not crop, and it does not draw. Those three
+ * are what turn "how many pixels differ" into the paths §1.9 promises, and
+ * they are small enough that a second dependency for them would be a larger
+ * commitment than the code it saved.
+ *
+ * **Four channels, eight bits each, row-major from the top left**, which is
+ * both what the decoder produces and the layout the comparison library
+ * requires. §1.9 measures every region "in the capture's own pixels, measured
+ * from the top left", and that is the same origin, so nothing here has to
+ * flip a coordinate.
+ */
+/** How many bytes one pixel occupies. Red, green, blue, alpha. */
+export const CHANNELS = 4;
+/** Decode PNG bytes. */
+export function decodePng(bytes) {
+    const png = PNG.sync.read(Buffer.from(bytes));
+    return { width: png.width, height: png.height, data: new Uint8Array(png.data) };
+}
+/** Encode an image as PNG bytes. */
+export function encodePng(image) {
+    const png = new PNG({ width: image.width, height: image.height });
+    png.data = Buffer.from(image.data);
+    return new Uint8Array(PNG.sync.write(png));
+}
+/** A transparent image of the given size, which every drawing surface starts as. */
+export function blankImage(width, height) {
+    return { width, height, data: new Uint8Array(width * height * CHANNELS) };
+}
+/**
+ * Clamp a rectangle to an image's bounds.
+ *
+ * **This is what makes padding safe**, and it is the reason padding is applied
+ * by widening a rectangle and then clamping rather than by checking first. A
+ * region touching the top edge of a page — a header, which is the single most
+ * likely thing to change — cannot be padded upwards, and §1.9 asks for "the
+ * crop from the earlier capture and the crop from the new one, cut from the
+ * same rectangle". Clamping keeps that sameness true: one rectangle is
+ * computed, clamped once against the geometry both crops are taken at, and
+ * used for both.
+ *
+ * Returns `null` when nothing survives, which happens only for a rectangle
+ * entirely outside the image.
+ */
+export function clampToImage(rectangle, width, height) {
+    const left = Math.max(0, Math.min(rectangle.x, width));
+    const top = Math.max(0, Math.min(rectangle.y, height));
+    const right = Math.min(width, rectangle.x + rectangle.width);
+    const bottom = Math.min(height, rectangle.y + rectangle.height);
+    if (right <= left || bottom <= top) {
+        return null;
+    }
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+/**
+ * Cut a rectangle out of an image.
+ *
+ * The rectangle must already be within the image; `clampToImage` is what puts
+ * it there. Reading outside would produce a crop padded with whatever the
+ * buffer happened to hold, which is a picture of nothing presented as a
+ * picture of something.
+ */
+export function crop(image, rectangle) {
+    if (rectangle.x < 0 ||
+        rectangle.y < 0 ||
+        rectangle.x + rectangle.width > image.width ||
+        rectangle.y + rectangle.height > image.height ||
+        rectangle.width <= 0 ||
+        rectangle.height <= 0) {
+        throw new Error(`A crop of ${String(rectangle.width)}x${String(rectangle.height)} at ` +
+            `${String(rectangle.x)},${String(rectangle.y)} does not fit an image of ` +
+            `${String(image.width)}x${String(image.height)}. Clamp the rectangle first.`);
+    }
+    const out = blankImage(rectangle.width, rectangle.height);
+    for (let row = 0; row < rectangle.height; row += 1) {
+        const from = ((rectangle.y + row) * image.width + rectangle.x) * CHANNELS;
+        out.data.set(image.data.subarray(from, from + rectangle.width * CHANNELS), row * rectangle.width * CHANNELS);
+    }
+    return out;
+}
+/** Set one pixel, ignoring anything outside the image. */
+function setPixel(image, x, y, colour) {
+    if (x < 0 || y < 0 || x >= image.width || y >= image.height) {
+        return;
+    }
+    const at = (y * image.width + x) * CHANNELS;
+    image.data[at] = colour.red;
+    image.data[at + 1] = colour.green;
+    image.data[at + 2] = colour.blue;
+    image.data[at + 3] = colour.alpha;
+}
+/**
+ * Draw a rectangle's outline, `thickness` pixels wide, growing inwards.
+ *
+ * **Inwards rather than centred on the edge**, so an outline around a region
+ * flush with the image border is still fully visible. An outline drawn
+ * outwards or centred loses half its width off the edge exactly where the
+ * region is hardest to locate — the very top of a page.
+ *
+ * Mutates the image it is given, because the overlay is one image with a dozen
+ * outlines on it and copying per outline would copy a full page a dozen times.
+ */
+export function outlineRectangle(image, rectangle, colour, thickness) {
+    const depth = Math.max(1, Math.floor(thickness));
+    for (let ring = 0; ring < depth; ring += 1) {
+        const left = rectangle.x + ring;
+        const top = rectangle.y + ring;
+        const right = rectangle.x + rectangle.width - 1 - ring;
+        const bottom = rectangle.y + rectangle.height - 1 - ring;
+        if (right < left || bottom < top) {
+            break;
+        }
+        for (let x = left; x <= right; x += 1) {
+            setPixel(image, x, top, colour);
+            setPixel(image, x, bottom, colour);
+        }
+        for (let y = top; y <= bottom; y += 1) {
+            setPixel(image, left, y, colour);
+            setPixel(image, right, y, colour);
+        }
+    }
+}
+/** Copy an image, so a drawing operation does not alter what it drew onto. */
+export function copyImage(image) {
+    return { width: image.width, height: image.height, data: new Uint8Array(image.data) };
+}

package/dist/src/diff/mask.js

@@ -0,0 +1,46 @@
+import pixelmatch from 'pixelmatch';
+import { CHANNELS } from "./image.js";
+/**
+ * Compare two images and return the mask.
+ *
+ * Both images must be the same width, and the compared height must fit in
+ * both. `geometry.ts` is what establishes that; this throws rather than
+ * guessing, because a silent adjustment here would produce a confident mask of
+ * two misaligned pictures.
+ */
+export function computeMask(earlier, current, options) {
+    if (earlier.width !== current.width) {
+        throw new Error(`A mask needs two images of one width; got ${String(earlier.width)} and ${String(current.width)}. ` +
+            'Reconcile the geometry first.');
+    }
+    const width = current.width;
+    const height = options.height ?? Math.min(earlier.height, current.height);
+    if (height > earlier.height || height > current.height) {
+        throw new Error(`A mask over ${String(height)} rows does not fit images of ${String(earlier.height)} and ` +
+            `${String(current.height)} rows.`);
+    }
+    const pixels = width * height;
+    // The library writes its output as four channels, and `diffMask` makes the
+    // unchanged ones transparent — which is what turns "an image a person looks
+    // at" into "a bitmap something iterates".
+    const output = new Uint8Array(pixels * CHANNELS);
+    const changedPixels = pixelmatch(earlier.data.subarray(0, pixels * CHANNELS), current.data.subarray(0, pixels * CHANNELS), output, width, height, {
+        threshold: options.colourTolerance,
+        // Transparent background, opaque where something changed. Without this
+        // the output is the original image dimmed underneath the differences,
+        // and every pixel is non-zero.
+        diffMask: true,
+        // Anti-aliased pixels are excluded from the count rather than coloured
+        // in, which is the default and is the behaviour §3.11's settling
+        // requirement depends on.
+        includeAA: false,
+    });
+    const changed = new Uint8Array(pixels);
+    for (let index = 0; index < pixels; index += 1) {
+        // The alpha channel is the decision. With `diffMask` set, an unchanged
+        // pixel is fully transparent and a changed one is not — so any non-zero
+        // alpha is a change, whatever colour the library chose to mark it with.
+        changed[index] = output[index * CHANNELS + 3] === 0 ? 0 : 1;
+    }
+    return { width, height, changed, changedPixels };
+}

package/dist/src/diff/regions.js

@@ -0,0 +1,263 @@
+/**
+ * Changed-region extraction (`MILESTONES.md` #41).
+ *
+ * Three steps, in order, and each one is a decision the milestone names:
+ *
+ * 1. **Connected components** over the mask, into bounding boxes.
+ * 2. **Merged at a configurable distance** (§6.2, default 8 pixels), because
+ *    two words changing in one sentence are one change to a person.
+ * 3. **Filtered on area with a thin-line allowance** — and the negative half
+ *    of that is the point of the row.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * THE FILTER, AND THE SHAPE IT MUST NOT DISCARD
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * #41: filtered "**on area with a thin-line allowance** — not on the shorter
+ * side, which discards a one-pixel line across a wide page". §6.2 says the
+ * same from the other direction: "the size filter is on area with a thin-line
+ * allowance, so a one-pixel line across a page survives it".
+ *
+ * **The rejected rule and why it is so tempting.** Filtering on the shorter
+ * side — the smaller of width and height against a minimum — reads as
+ * obviously right: it drops specks, and a speck is small in both directions.
+ * It is wrong because the changes most worth catching in a visual review are
+ * thin by nature:
+ *
+ * | Change | Shape | Shorter side |
+ * |---|---|---|
+ * | A border width going from one pixel to two | a line the width of an element | **1** |
+ * | A focus ring appearing | a thin rectangle outline | **1–2** |
+ * | An underline added or removed | a line the width of a word | **1** |
+ * | A horizontal rule moving | a line the width of a page | **1** |
+ *
+ * Every one of those is invisible to a shorter-side filter and every one is a
+ * real regression somebody wants to see. A one-pixel line across a page a
+ * thousand pixels wide has an area of a thousand, which is many times the
+ * default minimum — so **area alone already keeps it**, and the shorter-side
+ * rule is strictly worse than the simpler thing.
+ *
+ * **So what is the allowance for, if area alone keeps the long line?** For the
+ * *short* thin line — a two-pixel-tall underline beneath a single short word,
+ * area perhaps forty against a minimum of sixty-four. Area alone eats that,
+ * and it is the same class of change as the long one. The allowance is a
+ * second way to survive: **a region that is thin and long relative to its
+ * thickness is kept whatever its area**, because being line-shaped is itself
+ * evidence that it is a deliberate piece of a layout rather than a rendering
+ * speck. A speck is small in both directions and roughly square; a line is
+ * not.
+ *
+ * The two tests that pin this are the ones to read before touching the
+ * numbers: a one-pixel line across a wide page survives, and a short thin
+ * underline survives, and both fail if the filter reverts to the shorter side.
+ */
+/**
+ * How long a thin region must be, as a multiple of its thickness, to be kept
+ * regardless of area.
+ *
+ * **Six rather than a larger number**, because the shortest change worth
+ * keeping is an underline beneath one short word: two pixels tall and perhaps
+ * twenty long is a ratio of ten, and a two-by-three speck is a ratio of one
+ * and a half. Six sits between them with room on both sides, and the cost of
+ * it being slightly too low is an extra small region in a list that is ordered
+ * largest first and capped anyway.
+ */
+export const THIN_LINE_ASPECT_RATIO = 6;
+/**
+ * The thickest a region can be and still be judged a line, in pixels.
+ *
+ * Without this, a large block on a wide page whose sides happen to sit at a
+ * ratio of six would be kept "as a line" — which is harmless, since a region
+ * that size passes on area many times over, but it makes the allowance mean
+ * something it does not. Four pixels covers a border, a focus ring, an
+ * underline and a rule at the device pixel ratios a capture is taken at.
+ */
+export const THIN_LINE_MAXIMUM_THICKNESS = 4;
+/**
+ * Connected components over the mask, four-connected.
+ *
+ * **Four rather than eight**, and the difference matters here in one
+ * direction: eight-connectivity joins two areas touching only at a corner,
+ * which is how two separate one-pixel changes a diagonal apart become one box
+ * spanning both. Merging is a separate, configurable step immediately below,
+ * so the conservative connectivity loses nothing — anything that should have
+ * been joined is joined by distance, under a number somebody can see and
+ * change.
+ *
+ * Iterative rather than recursive: a full-page region can be a million pixels,
+ * and a recursive flood fill on one is a stack overflow rather than a slow
+ * answer.
+ */
+function components(mask) {
+    const { width, height, changed } = mask;
+    const seen = new Uint8Array(width * height);
+    const found = [];
+    // Reused across components. A per-component array would allocate once per
+    // region, and a page-wide re-render produces a lot of them.
+    const stack = [];
+    for (let start = 0; start < changed.length; start += 1) {
+        if (changed[start] === 0 || seen[start] === 1) {
+            continue;
+        }
+        seen[start] = 1;
+        stack.length = 0;
+        stack.push(start);
+        let left = width;
+        let right = -1;
+        let top = height;
+        let bottom = -1;
+        let count = 0;
+        while (stack.length > 0) {
+            // `pop` on a non-empty array, which the loop condition guarantees.
+            const at = stack.pop();
+            const x = at % width;
+            const y = (at - x) / width;
+            count += 1;
+            if (x < left)
+                left = x;
+            if (x > right)
+                right = x;
+            if (y < top)
+                top = y;
+            if (y > bottom)
+                bottom = y;
+            if (x > 0 && changed[at - 1] === 1 && seen[at - 1] === 0) {
+                seen[at - 1] = 1;
+                stack.push(at - 1);
+            }
+            if (x + 1 < width && changed[at + 1] === 1 && seen[at + 1] === 0) {
+                seen[at + 1] = 1;
+                stack.push(at + 1);
+            }
+            if (y > 0 && changed[at - width] === 1 && seen[at - width] === 0) {
+                seen[at - width] = 1;
+                stack.push(at - width);
+            }
+            if (y + 1 < height && changed[at + width] === 1 && seen[at + width] === 0) {
+                seen[at + width] = 1;
+                stack.push(at + width);
+            }
+        }
+        found.push({
+            x: left,
+            y: top,
+            width: right - left + 1,
+            height: bottom - top + 1,
+            changedPixels: count,
+        });
+    }
+    return found;
+}
+/** Do two boxes come within `distance` of each other, in both axes? */
+function within(a, b, distance) {
+    const horizontalGap = Math.max(0, Math.max(a.x - (b.x + b.width), b.x - (a.x + a.width)));
+    const verticalGap = Math.max(0, Math.max(a.y - (b.y + b.height), b.y - (a.y + a.height)));
+    return horizontalGap <= distance && verticalGap <= distance;
+}
+/** The smallest box containing both. */
+function union(a, b) {
+    const x = Math.min(a.x, b.x);
+    const y = Math.min(a.y, b.y);
+    const right = Math.max(a.x + a.width, b.x + b.width);
+    const bottom = Math.max(a.y + a.height, b.y + b.height);
+    return {
+        x,
+        y,
+        width: right - x,
+        height: bottom - y,
+        // Summed rather than recounted from the mask. The two components are
+        // disjoint by construction, so the sum is exact, and recounting would mean
+        // a second pass over the union's area for every merge.
+        changedPixels: a.changedPixels + b.changedPixels,
+    };
+}
+/**
+ * Merge boxes that come within `distance` of one another, repeatedly.
+ *
+ * **Repeatedly, until nothing moves**, and that is not an optimisation detail:
+ * merging one box into another can bring the union within reach of a third
+ * that was too far from either alone. A single pass would report two regions
+ * where a person sees one, and which two would depend on the order the
+ * components happened to be found in.
+ */
+function merge(regions, distance) {
+    let current = regions;
+    let moved = true;
+    while (moved) {
+        moved = false;
+        const next = [];
+        for (const region of current) {
+            let merged = region;
+            let index = 0;
+            while (index < next.length) {
+                // Indexed inside the bound the loop condition establishes; the local
+                // is what lets the compiler see that.
+                const candidate = next[index];
+                if (within(merged, candidate, distance)) {
+                    merged = union(merged, candidate);
+                    next.splice(index, 1);
+                    moved = true;
+                    // Not advancing: the widened box has to be retried against
+                    // everything already passed, because it now reaches further.
+                    index = 0;
+                    continue;
+                }
+                index += 1;
+            }
+            next.push(merged);
+        }
+        current = next;
+    }
+    return current;
+}
+/**
+ * Is this region a thin line — kept whatever its area?
+ *
+ * Exported because the filter is the row's whole point, and a test that
+ * asserted it only through the end-to-end result would pass just as well with
+ * the allowance deleted, so long as the fixture happened to be large.
+ */
+export function isThinLine(region) {
+    const thickness = Math.min(region.width, region.height);
+    const length = Math.max(region.width, region.height);
+    if (thickness > THIN_LINE_MAXIMUM_THICKNESS) {
+        return false;
+    }
+    return length >= thickness * THIN_LINE_ASPECT_RATIO;
+}
+/**
+ * Does this region survive the size filter?
+ *
+ * **Area, or the thin-line allowance. Never the shorter side.** The header of
+ * this file is the argument; this is the one line it is about.
+ */
+export function survivesSizeFilter(region, minimumArea) {
+    return region.width * region.height >= minimumArea || isThinLine(region);
+}
+/**
+ * Extract the changed regions from a mask.
+ *
+ * Ordered **largest first by area**, which is the order §1.9 promises and the
+ * order the region cap depends on: a truncated result drops the smallest ones,
+ * since the list is ordered largest first.
+ *
+ * The cap itself is deliberately **not** applied here. Truncation is a fact
+ * about what the caller was given, and it belongs beside the crops that were
+ * actually written — otherwise a region could be dropped here and the count
+ * reported downstream would describe a list nobody has.
+ */
+export function extractRegions(mask, options) {
+    const merged = merge(components(mask), options.mergeDistance);
+    const kept = merged.filter((region) => survivesSizeFilter(region, options.minimumArea));
+    return kept.sort((a, b) => {
+        const byArea = b.width * b.height - a.width * a.height;
+        // Ties broken by position, so the order is the same on two runs over the
+        // same mask. Without it the order is whatever the flood fill happened to
+        // produce, and a test asserting "the first region" would be flaky.
+        if (byArea !== 0)
+            return byArea;
+        if (a.y !== b.y)
+            return a.y - b.y;
+        return a.x - b.x;
+    });
+}