@rehearsal-labs/retest 0.1.0 → 0.2.0

package/dist/schemas/result-v1.schema.json

@@ -757,6 +757,10 @@
         "attempts"
       ]
     },
+    "baselinesWritten": {
+      "type": "integer",
+      "minimum": 1
+    },
     "files": {
       "type": "array",
       "items": {

package/dist/shared/image-diff.d.ts

@@ -0,0 +1,36 @@
+import type { RgbaImage } from './png.ts';
+/** The colour distance, from 0 to 1, above which a pixel counts as different, as Playwright's `toHaveScreenshot` sets it. */
+export declare const defaultThreshold = 0.2;
+/** How two pictures of one size differ: the pixels counted as different, and the pixels left out as anti-aliasing. */
+export type PixelDifference = {
+    readonly differentPixels: number;
+    readonly antiAliasedPixels: number;
+};
+/** The picture `differencePicture` draws, and the count it drew. */
+export type DrawnDifference = PixelDifference & {
+    readonly picture: RgbaImage;
+};
+/**
+ * Whether two pictures are the same size and the same in every byte of every pixel.
+ *
+ * @example samePixels(first, second) // true
+ */
+export declare function samePixels(first: RgbaImage, second: RgbaImage): boolean;
+/**
+ * Counts the pixels of two pictures of one size whose colours are further apart than `threshold`, from 0 to 1, leaving
+ * out those that are anti-aliasing in either picture. Throws `RangeError` for pictures of different sizes or a
+ * threshold outside 0 to 1.
+ *
+ * @example comparePixels(baseline, picture, 0.2).differentPixels // 0
+ */
+export declare function comparePixels(expected: RgbaImage, actual: RgbaImage, threshold?: number): PixelDifference;
+/**
+ * Draws where two pictures differ, on a canvas as large as the larger of the two each way: the actual picture faded
+ * to grey, and each differing pixel in red. A pixel that only one picture covers is red. Anti-aliased pixels stay
+ * faded. The counts are those of `comparePixels` when the sizes match, and count the uncovered pixels as different
+ * when they do not.
+ *
+ * @example differencePicture(baseline, picture, 0.2).picture.width // 1280
+ */
+export declare function differencePicture(expected: RgbaImage, actual: RgbaImage, threshold?: number): DrawnDifference;
+//# sourceMappingURL=image-diff.d.ts.map

package/dist/shared/image-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-diff.d.ts","sourceRoot":"","sources":["../../src/shared/image-diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AA0BzC,6HAA6H;AAC7H,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC,sHAAsH;AACtH,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtG,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAA;AAQ/E;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAGvE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAE,MAAyB,GAAG,eAAe,CAG3H;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAE,MAAyB,GAAG,eAAe,CAsB/H"}

package/dist/shared/image-diff.js

@@ -0,0 +1,242 @@
+// How two pictures differ, pixel by pixel, for a screenshot comparison. A pixel differs when the distance between its
+// two colours, in the YIQ space that weighs brightness the way eyes do, is above a threshold; a pixel that differs only
+// because an edge is anti-aliased a little differently is not counted.
+//
+// The colour distance and the anti-aliasing detector are adapted from pixelmatch 7.2.0 by Mapbox, read as published on
+// npm, and match the version Playwright 1.63.0 vendors, whose `toHaveScreenshot` counts pixels this way, so a threshold
+// means here what it means there. The distance follows Kotsarenko and Ramos, "Measuring perceived color difference using
+// YIQ NTSC transmission color space in mobile applications" (2010); the detector follows Vysniauskas, "Anti-aliased
+// pixel and intensity slope detector" (2009). Semi-transparent pixels are blended on white, as Playwright's copy does.
+// pixelmatch's licence:
+//
+//   ISC License
+//
+//   Copyright (c) 2025, Mapbox
+//
+//   Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby
+//   granted, provided that the above copyright notice and this permission notice appear in all copies.
+//
+//   THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING
+//   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL,
+//   DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+//   WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
+//   USE OR PERFORMANCE OF THIS SOFTWARE.
+/** The colour distance, from 0 to 1, above which a pixel counts as different, as Playwright's `toHaveScreenshot` sets it. */
+export const defaultThreshold = 0.2;
+// The largest squared distance two colours can have in YIQ, so a threshold of 1 lets every colour through.
+const maxSquaredDistance = 35215;
+// How much of the actual picture's brightness shows in the difference picture: faded, so the red stands out.
+const fade = 0.1;
+const differenceColour = [255, 0, 0];
+/**
+ * Whether two pictures are the same size and the same in every byte of every pixel.
+ *
+ * @example samePixels(first, second) // true
+ */
+export function samePixels(first, second) {
+    if (first.width !== second.width || first.height !== second.height || first.data.length !== second.data.length)
+        return false;
+    return Buffer.from(first.data.buffer, first.data.byteOffset, first.data.byteLength).equals(Buffer.from(second.data.buffer, second.data.byteOffset, second.data.byteLength));
+}
+/**
+ * Counts the pixels of two pictures of one size whose colours are further apart than `threshold`, from 0 to 1, leaving
+ * out those that are anti-aliasing in either picture. Throws `RangeError` for pictures of different sizes or a
+ * threshold outside 0 to 1.
+ *
+ * @example comparePixels(baseline, picture, 0.2).differentPixels // 0
+ */
+export function comparePixels(expected, actual, threshold = defaultThreshold) {
+    checkSizes(expected, actual);
+    return scan(expected, actual, threshold, undefined);
+}
+/**
+ * Draws where two pictures differ, on a canvas as large as the larger of the two each way: the actual picture faded
+ * to grey, and each differing pixel in red. A pixel that only one picture covers is red. Anti-aliased pixels stay
+ * faded. The counts are those of `comparePixels` when the sizes match, and count the uncovered pixels as different
+ * when they do not.
+ *
+ * @example differencePicture(baseline, picture, 0.2).picture.width // 1280
+ */
+export function differencePicture(expected, actual, threshold = defaultThreshold) {
+    checkThreshold(threshold);
+    const width = Math.max(expected.width, actual.width);
+    const height = Math.max(expected.height, actual.height);
+    const data = new Uint8Array(width * height * 4);
+    const canvas = { width, height, data };
+    if (expected.width === actual.width && expected.height === actual.height) {
+        const counted = scan(expected, actual, threshold, (index, different) => (different ? paint(data, index * 4) : fadeInto(data, index * 4, actual.data, index * 4)));
+        return { ...counted, picture: canvas };
+    }
+    let differentPixels = 0;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const at = (y * width + x) * 4;
+            if (x < actual.width && y < actual.height && x < expected.width && y < expected.height)
+                fadeInto(data, at, actual.data, (y * actual.width + x) * 4);
+            else {
+                paint(data, at);
+                differentPixels++;
+            }
+        }
+    }
+    return { differentPixels, antiAliasedPixels: 0, picture: canvas };
+}
+function checkSizes(expected, actual) {
+    if (expected.width !== actual.width || expected.height !== actual.height) {
+        throw new RangeError(`Pixels compare only between pictures of one size, not ${expected.width} by ${expected.height} and ${actual.width} by ${actual.height}.`);
+    }
+    for (const image of [expected, actual])
+        if (image.data.length !== image.width * image.height * 4)
+            throw new RangeError(`${image.width} by ${image.height} RGBA pixels take ${image.width * image.height * 4} bytes, not ${image.data.length}.`);
+}
+function checkThreshold(threshold) {
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1)
+        throw new RangeError(`A threshold is a colour distance from 0 to 1, not ${threshold}.`);
+}
+// Visits every pixel of two pictures of one size, counting those that differ, and tells `mark` of each, different or not.
+function scan(expected, actual, threshold, mark) {
+    checkThreshold(threshold);
+    const { width, height } = expected;
+    const first = expected.data;
+    const second = actual.data;
+    const limit = maxSquaredDistance * threshold * threshold;
+    let differentPixels = 0;
+    let antiAliasedPixels = 0;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const index = y * width + x;
+            const delta = colourDelta(first, second, index * 4, index * 4, false);
+            if (Math.abs(delta) <= limit) {
+                mark?.(index, false);
+                continue;
+            }
+            if (antiAliased(first, second, x, y, width, height) || antiAliased(second, first, x, y, width, height)) {
+                antiAliasedPixels++;
+                mark?.(index, false);
+                continue;
+            }
+            differentPixels++;
+            mark?.(index, true);
+        }
+    }
+    return { differentPixels, antiAliasedPixels };
+}
+/**
+ * Whether the pixel at `x`, `y` of `picture` looks like part of an anti-aliased edge: among its eight neighbours it has
+ * no more than two of its own brightness, at least one darker and one brighter, and the darkest or the brightest of
+ * them sits in a flat run of at least three equal neighbours in both pictures.
+ */
+function antiAliased(picture, other, x, y, width, height) {
+    const left = Math.max(x - 1, 0);
+    const top = Math.max(y - 1, 0);
+    const right = Math.min(x + 1, width - 1);
+    const bottom = Math.min(y + 1, height - 1);
+    const at = (y * width + x) * 4;
+    let equal = x === left || x === right || y === top || y === bottom ? 1 : 0;
+    let darkest = 0;
+    let brightest = 0;
+    let darkestAt;
+    let brightestAt;
+    for (let column = left; column <= right; column++) {
+        for (let row = top; row <= bottom; row++) {
+            if (column === x && row === y)
+                continue;
+            const delta = colourDelta(picture, picture, at, (row * width + column) * 4, true);
+            if (delta === 0) {
+                equal++;
+                if (equal > 2)
+                    return false;
+            }
+            else if (delta < darkest) {
+                darkest = delta;
+                darkestAt = [column, row];
+            }
+            else if (delta > brightest) {
+                brightest = delta;
+                brightestAt = [column, row];
+            }
+        }
+    }
+    if (darkestAt === undefined || brightestAt === undefined)
+        return false;
+    const flat = ([column, row]) => hasManySiblings(picture, column, row, width, height) && hasManySiblings(other, column, row, width, height);
+    return flat(darkestAt) || flat(brightestAt);
+}
+// Whether a pixel has at least three neighbours exactly like it, a pixel on the picture's edge counting the edge as one.
+function hasManySiblings(picture, x, y, width, height) {
+    const left = Math.max(x - 1, 0);
+    const top = Math.max(y - 1, 0);
+    const right = Math.min(x + 1, width - 1);
+    const bottom = Math.min(y + 1, height - 1);
+    const at = (y * width + x) * 4;
+    let equal = x === left || x === right || y === top || y === bottom ? 1 : 0;
+    for (let column = left; column <= right; column++) {
+        for (let row = top; row <= bottom; row++) {
+            if (column === x && row === y)
+                continue;
+            const other = (row * width + column) * 4;
+            if (picture[at] === picture[other] && picture[at + 1] === picture[other + 1] && picture[at + 2] === picture[other + 2] && picture[at + 3] === picture[other + 3])
+                equal++;
+            if (equal > 2)
+                return true;
+        }
+    }
+    return false;
+}
+// The squared YIQ distance between two pixels, negative when the first is the brighter; with `brightnessOnly`, the
+// difference in brightness alone, first less second.
+function colourDelta(first, second, at, other, brightnessOnly) {
+    const r1 = first[at] ?? 0;
+    const g1 = first[at + 1] ?? 0;
+    const b1 = first[at + 2] ?? 0;
+    const a1 = first[at + 3] ?? 0;
+    const r2 = second[other] ?? 0;
+    const g2 = second[other + 1] ?? 0;
+    const b2 = second[other + 2] ?? 0;
+    const a2 = second[other + 3] ?? 0;
+    if (r1 === r2 && g1 === g2 && b1 === b2 && a1 === a2)
+        return 0;
+    const [red1, green1, blue1] = onWhite(r1, g1, b1, a1);
+    const [red2, green2, blue2] = onWhite(r2, g2, b2, a2);
+    const brightness1 = luma(red1, green1, blue1);
+    const brightness2 = luma(red2, green2, blue2);
+    const y = brightness1 - brightness2;
+    if (brightnessOnly)
+        return y;
+    const i = inPhase(red1, green1, blue1) - inPhase(red2, green2, blue2);
+    const q = quadrature(red1, green1, blue1) - quadrature(red2, green2, blue2);
+    const delta = 0.5053 * y * y + 0.299 * i * i + 0.1957 * q * q;
+    return brightness1 > brightness2 ? -delta : delta;
+}
+function onWhite(red, green, blue, alpha) {
+    if (alpha === 255)
+        return [red, green, blue];
+    const opacity = alpha / 255;
+    return [blend(red, opacity), blend(green, opacity), blend(blue, opacity)];
+}
+function blend(channel, opacity) {
+    return 255 + (channel - 255) * opacity;
+}
+function luma(red, green, blue) {
+    return red * 0.29889531 + green * 0.58662247 + blue * 0.11448223;
+}
+function inPhase(red, green, blue) {
+    return red * 0.59597799 - green * 0.2741761 - blue * 0.32180189;
+}
+function quadrature(red, green, blue) {
+    return red * 0.21147017 - green * 0.52261711 + blue * 0.31114694;
+}
+function paint(data, at) {
+    data[at] = differenceColour[0];
+    data[at + 1] = differenceColour[1];
+    data[at + 2] = differenceColour[2];
+    data[at + 3] = 255;
+}
+function fadeInto(data, at, source, from) {
+    const opacity = (fade * (source[from + 3] ?? 0)) / 255;
+    const grey = blend(luma(source[from] ?? 0, source[from + 1] ?? 0, source[from + 2] ?? 0), opacity);
+    data[at] = grey;
+    data[at + 1] = grey;
+    data[at + 2] = grey;
+    data[at + 3] = 255;
+}

package/dist/shared/metadata-process.d.ts

@@ -36,13 +36,16 @@ export declare const metadataPending: number;
 export declare const metadataRunning: number;
 export declare const metadataComplete: number;
 export declare const metadataAbandoned: number;
+/** The worker was ended for another query before it answered this one, which is asked again of a fresh worker. */
+export declare const metadataWorkerEnded: number;
 export declare const metadataSuccess: number;
 export declare const metadataFailure: number;
 /**
  * A synchronous bridge for fresh ownership readings, including exit hooks. The worker uses an asynchronous child
  * and bounds its output and time itself, so Node's synchronous-child timeout never kills an unrecorded process.
  * A query the worker failed to answer fails alone: that worker is ended and the next query starts a fresh one, so one
- * stall under load never leaves a long-lived host without readings, and so without the right to signal anything.
+ * stall under load never leaves a long-lived host without readings, and so without the right to signal anything. A
+ * query the ended worker still held is asked again of the fresh one, within its own caller's deadline.
  */
 export declare function readMetadataProcess(options: MetadataProcessOptions): string;
 /**

package/dist/shared/metadata-process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-process.d.ts","sourceRoot":"","sources":["../../src/shared/metadata-process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAIvD,sFAAsF;AACtF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IACxC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CACnC,CAAA;AAED,eAAO,MAAM,mBAAmB,EAAE,MAAwB,CAAA;AAC1D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAyB,CAAA;AAC/D,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AACxC,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AACxC,eAAO,MAAM,gBAAgB,EAAE,MAAU,CAAA;AACzC,eAAO,MAAM,iBAAiB,EAAE,MAAU,CAAA;AAC1C,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AACxC,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AAUxC;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAiB3E;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB/F;AAqED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,IAAI,CAQ7D"}
+{"version":3,"file":"metadata-process.d.ts","sourceRoot":"","sources":["../../src/shared/metadata-process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAIvD,sFAAsF;AACtF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IACxC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CACnC,CAAA;AAED,eAAO,MAAM,mBAAmB,EAAE,MAAwB,CAAA;AAC1D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAyB,CAAA;AAC/D,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AACxC,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AACxC,eAAO,MAAM,gBAAgB,EAAE,MAAU,CAAA;AACzC,eAAO,MAAM,iBAAiB,EAAE,MAAU,CAAA;AAC1C,kHAAkH;AAClH,eAAO,MAAM,mBAAmB,EAAE,MAAU,CAAA;AAC5C,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AACxC,eAAO,MAAM,eAAe,EAAE,MAAU,CAAA;AAaxC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAsB3E;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/F;AAuFD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,IAAI,CAQ7D"}

package/dist/shared/metadata-process.js

@@ -12,6 +12,8 @@ export const metadataPending = 0;
 export const metadataRunning = 1;
 export const metadataComplete = 2;
 export const metadataAbandoned = 3;
+/** The worker was ended for another query before it answered this one, which is asked again of a fresh worker. */
+export const metadataWorkerEnded = 4;
 export const metadataSuccess = 0;
 export const metadataFailure = 1;
 const queryLimitMs = 5000;
@@ -19,22 +21,31 @@ const workerAllowanceMs = 1000;
 // One spare of each production capacity. Only a completed query can return its buffer: an abandoned worker may
 // still be writing, and a concurrent query must hold a different buffer until its completion signal is consumed.
 const spareOutputs = new Map();
+// Queries posted and not yet settled. A worker ended for one query fails the others it holds at once, rather than
+// leaving each to wait out its whole bound for an answer that cannot come.
+const inFlight = new Set();
 let bridge;
 let workerModule = new URL(import.meta.url.endsWith('.ts') ? './metadata-process-worker.ts' : './metadata-process-worker.js', import.meta.url);
 /**
  * A synchronous bridge for fresh ownership readings, including exit hooks. The worker uses an asynchronous child
  * and bounds its output and time itself, so Node's synchronous-child timeout never kills an unrecorded process.
  * A query the worker failed to answer fails alone: that worker is ended and the next query starts a fresh one, so one
- * stall under load never leaves a long-lived host without readings, and so without the right to signal anything.
+ * stall under load never leaves a long-lived host without readings, and so without the right to signal anything. A
+ * query the ended worker still held is asked again of the fresh one, within its own caller's deadline.
  */
 export function readMetadataProcess(options) {
-    const query = submit(options);
+    let query = submit(options);
     try {
         for (;;) {
             checkCaller(query, options.deadline);
             const state = Atomics.load(query.control, 0);
             if (state === metadataComplete)
                 return answer(query);
+            if (state === metadataWorkerEnded) {
+                settle(query);
+                query = submit(options);
+                continue;
+            }
             const remaining = query.deadline - performance.now();
             if (remaining <= 0) {
                 if (abandoned(query))
@@ -45,7 +56,7 @@ export function readMetadataProcess(options) {
         }
     }
     finally {
-        releaseOutput(query);
+        settle(query);
     }
 }
 /**
@@ -56,7 +67,7 @@ export function readMetadataProcess(options) {
  * @example const text = await readMetadataProcessAsync({ command: '/bin/ps', args: ['-axo', 'pid='], environment: { PATH: '/usr/bin:/bin' } })
  */
 export async function readMetadataProcessAsync(options) {
-    const query = submit(options);
+    let query = submit(options);
     const wake = () => { Atomics.notify(query.control, 0); };
     // Neither the unreferenced worker nor an Atomics wait keeps Node alive. Keep this bounded query awaited even when
     // it is the host's last work, including when a failed worker can no longer notify it.
@@ -68,6 +79,11 @@ export async function readMetadataProcessAsync(options) {
             const state = Atomics.load(query.control, 0);
             if (state === metadataComplete)
                 return answer(query);
+            if (state === metadataWorkerEnded) {
+                settle(query);
+                query = submit(options);
+                continue;
+            }
             const remaining = query.deadline - performance.now();
             if (remaining <= 0) {
                 if (abandoned(query))
@@ -80,7 +96,7 @@ export async function readMetadataProcessAsync(options) {
         }
     }
     finally {
-        releaseOutput(query);
+        settle(query);
         clearInterval(pending);
         options.deadline?.signal?.removeEventListener('abort', wake);
     }
@@ -118,7 +134,25 @@ function submit(options) {
         discardWorker(worker);
         throw new Error('The metadata worker could not receive the query.');
     }
-    return { worker, control, output, deadline: Math.min(performance.now() + timeoutMs + workerAllowanceMs, request.deadline === undefined ? Infinity : request.deadline - performance.timeOrigin) };
+    const query = { worker, control, output, deadline: Math.min(performance.now() + timeoutMs + workerAllowanceMs, request.deadline === undefined ? Infinity : request.deadline - performance.timeOrigin) };
+    inFlight.add(query);
+    return query;
+}
+function settle(query) {
+    inFlight.delete(query);
+    releaseOutput(query);
+}
+// Fails a query its worker can no longer answer, unless the answer came first, and wakes whoever waits on it.
+function endedWorker(query) {
+    for (;;) {
+        const latest = Atomics.load(query.control, 0);
+        if (latest === metadataComplete || latest === metadataAbandoned || latest === metadataWorkerEnded)
+            return;
+        if (Atomics.compareExchange(query.control, 0, latest, metadataWorkerEnded) !== latest)
+            continue;
+        Atomics.notify(query.control, 0);
+        return;
+    }
 }
 // A reply completing at the deadline may be consumed; an abandoned queued request must never start later. True once the
 // query is abandoned and its worker ended, false when the reply came first.
@@ -189,16 +223,24 @@ function metadataWorker() {
         throw new Error('The metadata worker could not start.');
     }
     worker.on('error', () => { discardWorker(worker); });
-    worker.on('exit', () => { if (bridge === worker)
-        bridge = undefined; });
+    worker.on('exit', () => {
+        if (bridge === worker)
+            bridge = undefined;
+        for (const query of inFlight)
+            if (query.worker === worker)
+                endedWorker(query);
+    });
     worker.unref();
     bridge = worker;
     return worker;
 }
-// The query that met the failure reports it; the next one starts a fresh worker.
+// The query that met the failure reports it; the next one starts a fresh worker, and the others it held are asked again.
 function discardWorker(worker) {
     if (bridge === worker)
         bridge = undefined;
+    for (const query of inFlight)
+        if (query.worker === worker)
+            endedWorker(query);
     // Ending a failed worker thread closes its pipes; its detached child is never sent a process signal.
     void worker.terminate().catch(() => { });
 }

package/dist/shared/png.d.ts

@@ -0,0 +1,35 @@
+/** A picture as Retest compares it: `width` by `height` pixels, four bytes each, red, green, blue and alpha, row by row. */
+export type RgbaImage = {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array;
+};
+/** A PNG as `readPng` reads it: its pixels as RGBA, and the text of its `tEXt` chunks by keyword. */
+export type PngPicture = RgbaImage & {
+    readonly text: Readonly<Record<string, string>>;
+};
+/** What `writePng` adds to the pixels: `tEXt` chunks, by keyword, each keyword 1 to 79 Latin-1 letters. */
+export type PngWriteOptions = {
+    readonly text?: Readonly<Record<string, string>>;
+};
+/** Thrown for bytes that are not a PNG Retest reads. The message says what the bytes were. */
+export declare class PngError extends Error {
+    readonly name = "PngError";
+}
+/** The most bytes a decoded picture may take, filter bytes included, so a damaged file cannot ask for all memory. */
+export declare const maxPictureBytes: number;
+/**
+ * Decodes a PNG into RGBA pixels: 8-bit RGB or RGBA, not interlaced, its rows filtered with any of the five filters.
+ * Every chunk's checksum is checked. RGB pixels get an alpha of 255. Throws `PngError` for anything else.
+ *
+ * @example readPng(bytes).width // 1280
+ */
+export declare function readPng(bytes: Uint8Array): PngPicture;
+/**
+ * Encodes RGBA pixels as a PNG: RGB when every pixel is opaque, RGBA otherwise, each row with the filter that leaves the
+ * smallest sum, as libpng chooses, and any `tEXt` chunks the options name.
+ *
+ * @example writePng({ width: 1, height: 1, data: Uint8Array.of(255, 0, 0, 255) }, { text: { 'retest:scale': '2' } })
+ */
+export declare function writePng(image: RgbaImage, options?: PngWriteOptions): Uint8Array;
+//# sourceMappingURL=png.d.ts.map

package/dist/shared/png.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png.d.ts","sourceRoot":"","sources":["../../src/shared/png.ts"],"names":[],"mappings":"AAOA,4HAA4H;AAC5H,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAA;AAEtG,qGAAqG;AACrG,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAA;AAExF,2GAA2G;AAC3G,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAA;AAElF,8FAA8F;AAC9F,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAkB,IAAI,cAAa;CACpC;AAED,qHAAqH;AACrH,eAAO,MAAM,eAAe,EAAE,MAA0B,CAAA;AAQxD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CA0CrD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,UAAU,CAepF"}