humanish 0.145.0 → 0.147.0

package/dist/analysis/image-tokens.js

@@ -1,3 +1,4 @@
+import { WEBP_HEADER_BYTES, webpHeaderDimensions } from "../evidence/webp.js";
 /** An input image the analysis providers accept; the groups are the image type and its base64 bytes. */
 export const INPUT_IMAGE_DATA_URL = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]+={0,2})$/;
 /**
@@ -36,8 +37,13 @@ const GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS = Object.freeze({
 /** The most one image can cost on `model`, whatever its size. */
 export const imageTokenCeiling = (model) => GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS[model] ?? HIGH_DETAIL_IMAGE_TOKEN_CEILING;
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-/** Width and height from a PNG data URL's IHDR chunk; undefined for anything else. */
-function pngDimensions(dataUrl) {
+/** Base64 characters that hold WEBP_HEADER_BYTES, rounded up to whole 3-byte groups. */
+const WEBP_HEADER_CHARS = Math.ceil(WEBP_HEADER_BYTES / 3) * 4;
+/** Width and height from a PNG data URL's IHDR chunk or a lossless WebP's VP8L header. */
+function imageDimensions(dataUrl) {
+    const webp = new RegExp(`^data:image/webp;base64,([A-Za-z0-9+/]{${WEBP_HEADER_CHARS}})`).exec(dataUrl);
+    if (webp)
+        return webpHeaderDimensions(Buffer.from(webp[1], "base64"));
     const match = /^data:image\/png;base64,([A-Za-z0-9+/]{32})/.exec(dataUrl);
     if (!match)
         return undefined;
@@ -53,7 +59,7 @@ export function highDetailImageTokens(model, dataUrl) {
     if (fixed !== undefined)
         return fixed;
     const sizing = HIGH_DETAIL_SIZING[model];
-    const size = sizing === undefined ? undefined : pngDimensions(dataUrl);
+    const size = sizing === undefined ? undefined : imageDimensions(dataUrl);
     if (sizing === undefined || size === undefined)
         return HIGH_DETAIL_IMAGE_TOKEN_CEILING;
     const patches = Math.ceil(size.width / 32) * Math.ceil(size.height / 32);

package/dist/analysis/output-limit.d.ts

@@ -0,0 +1,12 @@
+import type { AnalysisConfig } from "./types.js";
+/** The API output limit when a study omits maxOutputTokens, and the most it may ask for. Gemini 4
+ * returns at most 32,768 output tokens from one generateContent request. */
+export declare const DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS = 16384;
+export declare const MAX_ANALYSIS_OUTPUT_TOKENS = 32768;
+/**
+ * The output limit an analysis of `participants` asks for when its study declares none, or
+ * undefined for Codex, which takes no limit. A high-effort or Gemini analysis, and one analysed in
+ * cohorts, gets the most the analysts return: at those efforts one finished report of three
+ * participants used up to 26,439 tokens.
+ */
+export declare function defaultOutputTokens(config: AnalysisConfig, participants: number): number | undefined;

package/dist/analysis/output-limit.js

@@ -0,0 +1,34 @@
+// The output limit an API analysis asks for when its study declares none. A request that runs
+// away writes until it reaches the limit, so the limit is sized to what a finished report of the
+// packet needs, with room to spare.
+import { analysisCohortCount } from "./analysis-limits.js";
+import { analysisEffort } from "./models.js";
+/** The API output limit when a study omits maxOutputTokens, and the most it may ask for. Gemini 4
+ * returns at most 32,768 output tokens from one generateContent request. */
+export const DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS = 16_384;
+export const MAX_ANALYSIS_OUTPUT_TOKENS = 32_768;
+/**
+ * The limit of a low- or medium-effort OpenAI request: this many tokens, and this many more for
+ * each participant. On the 2026-10-22 and 2026-10-23 benchmark recordings the longest finished
+ * report at those efforts used 8,354 tokens for one participant and 11,313 for three (gpt-6-luna at
+ * medium; gpt-6.1-sol at medium used at most 5,659 and 9,000), so the limit is 1.7 and 1.6 times
+ * those. docs/contracts/study-analysis.md has the table.
+ */
+const LIMIT_BASE_TOKENS = 12_288;
+const LIMIT_TOKENS_PER_PARTICIPANT = 2_048;
+const SIZED_EFFORTS = new Set(["none", "low", "medium"]);
+/**
+ * The output limit an analysis of `participants` asks for when its study declares none, or
+ * undefined for Codex, which takes no limit. A high-effort or Gemini analysis, and one analysed in
+ * cohorts, gets the most the analysts return: at those efforts one finished report of three
+ * participants used up to 26,439 tokens.
+ */
+export function defaultOutputTokens(config, participants) {
+    if (config.provider === "codex")
+        return undefined;
+    if (config.provider === "gemini" ||
+        !SIZED_EFFORTS.has(analysisEffort(config)) ||
+        analysisCohortCount(participants) > 1)
+        return MAX_ANALYSIS_OUTPUT_TOKENS;
+    return Math.min(MAX_ANALYSIS_OUTPUT_TOKENS, LIMIT_BASE_TOKENS + LIMIT_TOKENS_PER_PARTICIPANT * participants);
+}

package/dist/analysis/output-retry.d.ts

@@ -0,0 +1,20 @@
+import type { RequestCost } from "./admission.js";
+import type { AnalysisProviderResult } from "./provider.js";
+import type { AnalysisConfig, AnalysisUsage } from "./types.js";
+export interface OutputRetries {
+    /**
+     * Whether to send request `index` again after `response`, given the attempt's usage with that
+     * response counted. Adds a warning that says what ran out and what humanish did.
+     */
+    retry(index: number, response: AnalysisProviderResult, usage: AnalysisUsage): boolean;
+    /** Request `index` has its final answer, so its cost is no longer held against the cap. */
+    settle(index: number): void;
+    /** The summed worst case of every request sent again, which admission did not price. */
+    worstCaseUsd(): number;
+}
+/**
+ * The retries of one attempt. `costs` are each request's costs from admission (the cohorts', then
+ * the merge request's), `describe` names request `index` at the start of a sentence, and warnings
+ * receive what happened.
+ */
+export declare function outputRetries(config: AnalysisConfig, costs: readonly RequestCost[], describe: (index: number) => string, warnings: string[] | undefined): OutputRetries;

package/dist/analysis/output-retry.js

@@ -0,0 +1,63 @@
+// One more request when an API analyst runs out of output before it finishes its report. The same
+// request is sent again, at most once, and only while the analysis's cost cap still admits it
+// after counting what every request so far cost. Codex account analysis has no dollar cap to
+// check, so it is never sent again.
+import { estimateActorCost } from "../run/pricing.js";
+const usd = (value) => `$${value.toFixed(2)}`;
+/**
+ * The retries of one attempt. `costs` are each request's costs from admission (the cohorts', then
+ * the merge request's), `describe` names request `index` at the start of a sentence, and warnings
+ * receive what happened.
+ */
+export function outputRetries(config, costs, describe, warnings) {
+    // What each request without a final answer may still cost: admission's figure for it.
+    const held = new Map(costs.map((cost, index) => [index, cost.admittedCostUsd]));
+    const retried = new Set();
+    let worstCase = 0;
+    const warn = (text) => {
+        warnings?.push(text);
+    };
+    return {
+        retry(index, response, usage) {
+            if (response.errorCode !== "output_incomplete" || config.maxCostUsd === null)
+                return false;
+            const which = describe(index);
+            if (retried.has(index)) {
+                warn(`${which} ran out of output again, so this attempt has no report.`);
+                return false;
+            }
+            const cap = config.maxCostUsd;
+            const tokens = response.usage;
+            const cost = tokens === null
+                ? null
+                : estimateActorCost({ ...tokens, turns: [tokens] }, config.model).estimatedCostUsd;
+            if (tokens === null ||
+                cost === null ||
+                !usage.usageComplete ||
+                usage.estimatedCostUsd === null) {
+                warn(`${which} ran out of output before it finished its report and did not report its usage, so humanish cannot tell whether a second request fits the $${cap} cap. It was not sent again.`);
+                return false;
+            }
+            const ranOut = `${which} ran out of output before it finished its report: ${tokens.output} of ${config.maxOutputTokens} output tokens, ${tokens.input} input tokens, ${usd(cost)}.`;
+            const again = costs[index];
+            let others = 0;
+            for (const [other, amount] of held)
+                if (other !== index)
+                    others += amount;
+            const total = usage.estimatedCostUsd + others + again.admittedCostUsd;
+            if (total > cap) {
+                const running = others > 0 ? `, the ${usd(others)} admission holds for requests still running,` : "";
+                warn(`${ranOut} humanish did not send it again: the ${usd(usage.estimatedCostUsd)} spent so far${running} plus ${usd(again.admittedCostUsd)} for one more request at admission's estimate is over the $${cap} cap. To retry, run the analysis again; a higher cost cap leaves room for a second request.`);
+                return false;
+            }
+            retried.add(index);
+            worstCase += again.worstCaseCostUsd;
+            warn(`${ranOut} humanish sent the same request once more; the attempt's usage counts both requests.`);
+            return true;
+        },
+        settle(index) {
+            held.delete(index);
+        },
+        worstCaseUsd: () => worstCase,
+    };
+}

package/dist/analysis/provider.d.ts

@@ -73,7 +73,7 @@ export interface AnalysisWire {
     body(request: AnalysisProviderRequest): unknown;
     parse(raw: unknown): AnalysisProviderResult;
 }
-/** One request to the vendor's fixed endpoint, never retried and never sent elsewhere. */
+/** One request to the vendor's fixed endpoint, sent once and never elsewhere. */
 export declare function createAnalysisProvider(options: {
     apiKey: string;
     /** Omitted is OpenAI, the analyst humanish has always called. */

package/dist/analysis/provider.js

@@ -1,8 +1,8 @@
 // The analysis provider seam and the HTTP transport its API adapters share. Each API vendor owns
 // only its wire format (gemini-wire.ts, openai-wire.ts): the endpoint, the request body, and how a
 // response becomes a result. The transport owns what must hold for every vendor: one fixed endpoint
-// per vendor, request and response byte caps, the caller's wall-clock deadline, no retry, and a
-// closed error vocabulary that never carries provider error prose. The Codex account analyst is
+// per vendor, request and response byte caps, the caller's wall-clock deadline, one send per call
+// (runAnalysis decides whether to call again, in output-retry.ts), and a closed error vocabulary that never carries provider error prose. The Codex account analyst is
 // the third adapter at the same seam (restricted-codex.ts).
 import { Agent, fetch as undiciFetch } from "undici";
 import { isRecord } from "../run/type-guards.js";
@@ -49,7 +49,7 @@ const WIRES = {
     openai: openaiWire,
     gemini: geminiWire,
 };
-/** One request to the vendor's fixed endpoint, never retried and never sent elsewhere. */
+/** One request to the vendor's fixed endpoint, sent once and never elsewhere. */
 export function createAnalysisProvider(options) {
     const fetchFn = options.fetchFn ?? undiciFetch;
     const wire = WIRES[options.vendor ?? "openai"];

package/dist/analysis/responses.js

@@ -202,7 +202,7 @@ export function httpStatusWarning(config, response) {
         return undefined;
     const api = config.provider === "gemini" ? "Gemini" : "OpenAI";
     const meaning = HTTP_STATUS_MEANINGS[response.httpStatus];
-    return `The ${api} API answered HTTP ${response.httpStatus}${meaning === undefined ? "" : ` (${meaning})`}. humanish does not retry an analysis request; run the command again to retry.`;
+    return `The ${api} API answered HTTP ${response.httpStatus}${meaning === undefined ? "" : ` (${meaning})`}. humanish sends a request again only when it ran out of output; run the command again to retry.`;
 }
 /** The warnings a Codex response carries about its CLI release and protocol. */
 export function codexWarnings(config, response) {

package/dist/analysis/service.js

@@ -17,7 +17,7 @@ import { withAnalysisLock } from "./analysis-lock.js";
 import { captureEvidence, EVIDENCE_LIMITS } from "./evidence.js";
 import { AnalysisSourceRefusedError, runFileTooLarge, throwAsAnalysisRefusal } from "./source.js";
 import { pathMissing, readBoundedFile, readBoundedFileResult } from "../run/evidence-files.js";
-import { estimateAnalysisAdmission, preferLargerAnalysisOutput, runAnalysis, ANALYSIS_PROMPT_VERSION, } from "./execute.js";
+import { estimateAnalysisAdmission, defaultAnalysisOutput, runAnalysis, ANALYSIS_PROMPT_VERSION, } from "./execute.js";
 import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalyses, writeAnalysis, } from "./store.js";
 import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
 import { keepRejectedAnalysisOutput } from "./diagnostics.js";
@@ -261,7 +261,7 @@ async function executeAnalysis(attempt) {
     if (input.evidence.length === 0)
         return fail(input.runId, dryRun, "ANALYSIS_NO_PARTICIPANTS");
     if (options.preferLargerOutput)
-        config = preferLargerAnalysisOutput(input, config);
+        config = defaultAnalysisOutput(input, config);
     const admission = estimateAnalysisAdmission(input, config);
     const base = {
         schema: ANALYZE_RESULT_SCHEMA,

package/dist/cli/commands/analyze.js

@@ -38,7 +38,7 @@ export function registerAnalyzeCommand(parent, io) {
         .option("--reasoning-effort <level>", `OpenAI reasoning.effort or Gemini thinking level, from none, minimal, low, medium, high, xhigh and max; each model takes only the levels its provider documents for it, and others are refused before any request. When omitted: ${DEFAULT_ANALYSIS_EFFORT} for the default OpenAI analyst, high with --model or --provider gemini. Unsupported for Codex.`)
         .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
         .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", String(DEFAULT_ANALYSIS_TIMEOUT_MS))
-        .option("--max-output-tokens <n>", "OpenAI or Gemini response-token limit including reasoning, 256–32768. Omit for admission-based sizing. Unsupported for Codex.")
+        .option("--max-output-tokens <n>", "OpenAI or Gemini response-token limit including reasoning, 256–32768. Omit for a limit sized to the participants and effort. Unsupported for Codex.")
         .option("--dry-run", "Capture and validate local input and estimate admission; no request or analysis artifact.")
         .option("--rerun", "Create a new immutable version even when the same input and configuration were analyzed.")
         .option("--json", JSON_OPTION_DESCRIPTION)

package/dist/cli/io.js

@@ -208,6 +208,8 @@ export function writeResult(command, io, result, formatHuman, analysisLines) {
                 io.writeOut(`analysis: refused before it started. ${refusal.text} ${refusal.command}\n`);
             else if (analysis)
                 io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
+            for (const warning of analysis?.result?.warnings ?? [])
+                io.writeOut(`analysis: ${warning}\n`);
             const rejected = analysis?.result?.rejectedOutputPath;
             if (rejected)
                 io.writeOut(`analysis: ${analysis.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}\n`);

package/dist/cli/run-findings.js

@@ -33,10 +33,12 @@ async function readRunReport(cwd, result, deps) {
     if (outcome === undefined || result.runId === undefined || result.runId === "not-created")
         return undefined;
     const outcomeLine = `analysis: ${analysisOutcomeText(outcome)}`;
+    // What the attempt warned about, such as a request sent again after it ran out of output.
+    const warningLines = (outcome.result?.warnings ?? []).map((warning) => `analysis: ${warning}`);
     const plain = {
         message: `The automatic analysis was ${analysisOutcomeText(outcome)}.`,
         nextCommand: null,
-        lines: [outcomeLine],
+        lines: [outcomeLine, ...warningLines],
     };
     // A dry run left no evidence, and its own output names the live run.
     if (outcome.reason === "AUTOMATIC_ANALYSIS_DRY_RUN")
@@ -61,7 +63,12 @@ async function readRunReport(cwd, result, deps) {
         return {
             message: view.message,
             nextCommand: review,
-            lines: [outcomeLine, ...rejectedLine, ...formatFindingsSummary(view, review)],
+            lines: [
+                outcomeLine,
+                ...warningLines,
+                ...rejectedLine,
+                ...formatFindingsSummary(view, review),
+            ],
             findings: findingsSummary(view, review, result.observer?.observerPath),
         };
     // The line reads "analysis: skipped because ...", as it does without the view.
@@ -71,6 +78,7 @@ async function readRunReport(cwd, result, deps) {
         nextCommand: view.next,
         lines: [
             `analysis: ${said}`,
+            ...warningLines,
             ...rejectedLine,
             ...(view.next === null ? [] : [`next: ${view.next}`]),
         ],

package/dist/evidence/image.d.ts

@@ -22,3 +22,5 @@ export declare function pngDecodeRefusal(bytes: Buffer): string | null;
 export declare function isRedactedFrameShape(bytes: Buffer): boolean;
 export declare function screenshotEvidenceError(relativePath: string, bytes: Buffer): Promise<string | null>;
 export declare function assertScreenshotEvidence(relativePath: string, bytes: Buffer): Promise<void>;
+/** Why an image of these dimensions is refused before any decode, or null. */
+export declare function imageDimensionsError(format: string, width: number, height: number): string | null;

package/dist/evidence/image.js

@@ -1,5 +1,6 @@
 import { crc32, createInflate } from "node:zlib";
 import { PNG } from "pngjs";
+import { webpStructure } from "./webp.js";
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const PNG_IHDR_LENGTH = 13;
 // The pixel cap pngDecodeRefusal applies before any decode, for verify and the redactor alike.
@@ -130,8 +131,10 @@ export function isRedactedFrameShape(bytes) {
 }
 export async function screenshotEvidenceError(relativePath, bytes) {
     const extension = relativePath.toLowerCase().split(".").pop() ?? "";
+    if (extension === "webp")
+        return webpEvidenceError(bytes);
     if (extension !== "png") {
-        return `unsupported screenshot extension .${extension || "unknown"}; only decoded PNG evidence is supported`;
+        return `unsupported screenshot extension .${extension || "unknown"}; screenshot evidence is PNG or lossless WebP`;
     }
     const refusal = pngDecodeRefusal(bytes);
     if (refusal)
@@ -150,6 +153,20 @@ export async function screenshotEvidenceError(relativePath, bytes) {
         ? "could not decode PNG evidence"
         : null;
 }
+/**
+ * Why a WebP frame is not screenshot evidence, read from its structure (webpStructure) without
+ * decoding it. A WebP frame is always raw evidence, which verify never grades share-ready, so a
+ * decode would add 17 to 20 ms a frame on the main thread and establish nothing more about bytes
+ * no one reviews.
+ */
+function webpEvidenceError(bytes) {
+    if (bytes.length > SCREENSHOT_MAX_BYTES)
+        return `WebP byte size exceeds ${SCREENSHOT_MAX_BYTES} byte limit`;
+    const structure = webpStructure(bytes);
+    if (structure.error !== null)
+        return structure.error;
+    return imageDimensionsError("WebP", structure.dimensions.width, structure.dimensions.height);
+}
 /** The bit depths PNG allows for each color type. */
 const PNG_BIT_DEPTHS = {
     0: [1, 2, 4, 8, 16],
@@ -254,11 +271,15 @@ export async function assertScreenshotEvidence(relativePath, bytes) {
     }
 }
 function pngDimensionsError(width, height) {
+    return imageDimensionsError("PNG", width, height);
+}
+/** Why an image of these dimensions is refused before any decode, or null. */
+export function imageDimensionsError(format, width, height) {
     if (width === 0 || height === 0) {
-        return "PNG dimensions must be greater than zero";
+        return `${format} dimensions must be greater than zero`;
     }
     if (width * height > SCREENSHOT_MAX_SOURCE_PIXELS) {
-        return `PNG pixel count exceeds ${SCREENSHOT_MAX_SOURCE_PIXELS} pixel limit`;
+        return `${format} pixel count exceeds ${SCREENSHOT_MAX_SOURCE_PIXELS} pixel limit`;
     }
     return null;
 }

package/dist/evidence/webp-encode-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/evidence/webp-encode-worker.js

@@ -0,0 +1,31 @@
+// The worker thread src/evidence/webp-transcoder.ts runs: PNG frames in, lossless WebP out, one at
+// a time. It imports packages only, so Node can run this file from source with its types stripped
+// as well as from dist.
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { parentPort } from "node:worker_threads";
+import encode, { init } from "@jsquash/webp/encode.js";
+import { PNG } from "pngjs";
+/**
+ * Lossless, and `exact` keeps the color under fully transparent pixels, so decoded pixels equal the
+ * PNG's. Method 1 at quality 50 measured 0.47 of the PNG bytes at about 330 ms for a 1440x950
+ * frame; higher efforts saved 2% more at twice the time.
+ */
+const OPTIONS = { lossless: 1, exact: 1, method: 1, quality: 50 };
+const port = parentPort;
+if (port === null)
+    throw new Error("webp-encode-worker runs only as a worker thread.");
+const ready = readFile(createRequire(import.meta.url).resolve("@jsquash/webp/codec/enc/webp_enc_simd.wasm"))
+    .then((wasm) => WebAssembly.compile(wasm))
+    .then(async (module) => void (await init(module)));
+ready.then(() => port.postMessage({ ready: true }), (error) => port.postMessage({ ready: false, error: String(error) }));
+port.on("message", (job) => {
+    void ready
+        .then(async () => {
+        const image = PNG.sync.read(Buffer.from(job.png.buffer, job.png.byteOffset, job.png.length));
+        const data = new Uint8ClampedArray(image.data.buffer, image.data.byteOffset, image.data.length);
+        const webp = await encode({ data, width: image.width, height: image.height, colorSpace: "srgb" }, OPTIONS);
+        port.postMessage({ id: job.id, webp: new Uint8Array(webp) }, [webp]);
+    })
+        .catch((error) => port.postMessage({ id: job.id, error: String(error) }));
+});

package/dist/evidence/webp-transcoder.d.ts

@@ -0,0 +1,15 @@
+export interface WebpTranscoder {
+    /**
+     * The frame's WebP bytes, or undefined when the queue is full or the encoder failed. `abandon`
+     * drops a frame no one waits for any more, so it no longer keeps the process alive.
+     */
+    transcode(png: Buffer): {
+        webp: Promise<Buffer>;
+        abandon: () => void;
+    } | undefined;
+}
+/**
+ * The process's transcoder, started on first use. From source the worker runs as TypeScript, which
+ * Node loads with its types stripped.
+ */
+export declare function webpTranscoder(): WebpTranscoder;

package/dist/evidence/webp-transcoder.js

@@ -0,0 +1,98 @@
+// Turns computer-use frames into lossless WebP in a worker thread, off the turn's path: a frame is
+// written and referenced as PNG first, and only a finished WebP replaces it (see
+// src/routes/computer-use/participant-frames.ts). The process shares one worker, so encoding uses
+// at most one core however many participants run.
+import { Worker } from "node:worker_threads";
+/**
+ * The PNG bytes that may wait for the worker at once. A frame past it stays PNG, so a busy runner
+ * keeps today's format for that frame instead of holding more frames in memory.
+ */
+const QUEUE_BYTE_BUDGET = 64 * 1024 * 1024;
+class WorkerTranscoder {
+    worker;
+    /**
+     * Every frame posted to the worker until it answers. An abandoned frame still holds its bytes
+     * there, so it counts against the budget, but it no longer keeps the process alive.
+     */
+    posted = new Map();
+    queuedBytes = 0;
+    wanted = 0;
+    nextId = 0;
+    failed = false;
+    constructor(entry) {
+        this.worker = new Worker(entry);
+        this.worker.on("message", (message) => {
+            if ("ready" in message) {
+                if (!message.ready)
+                    this.fail(new Error(message.error));
+                return;
+            }
+            const job = this.posted.get(message.id);
+            if (job === undefined)
+                return;
+            this.posted.delete(message.id);
+            this.queuedBytes -= job.size;
+            if (job.abandoned)
+                return;
+            this.release();
+            if ("error" in message)
+                job.reject(new Error(message.error));
+            else
+                job.resolve(Buffer.from(message.webp.buffer, message.webp.byteOffset, message.webp.length));
+        });
+        this.worker.on("error", (error) => this.fail(error));
+        this.worker.on("exit", (code) => this.fail(new Error(`The WebP worker exited with code ${code}.`)));
+        // An idle worker never keeps the process alive; a waiting frame does. Adding a message listener
+        // refs the worker, so this comes after the listeners.
+        this.worker.unref();
+    }
+    transcode(png) {
+        if (this.failed || this.queuedBytes + png.length > QUEUE_BYTE_BUDGET)
+            return undefined;
+        const id = this.nextId++;
+        if (this.wanted++ === 0)
+            this.worker.ref();
+        this.queuedBytes += png.length;
+        const webp = new Promise((resolve, reject) => {
+            this.posted.set(id, { size: png.length, abandoned: false, resolve, reject });
+            this.worker.postMessage({ id, png: new Uint8Array(png) });
+        });
+        return {
+            webp,
+            abandon: () => {
+                const job = this.posted.get(id);
+                if (job === undefined || job.abandoned)
+                    return;
+                job.abandoned = true;
+                this.release();
+                job.reject(new Error("The frame's WebP was abandoned."));
+            },
+        };
+    }
+    /** One frame fewer that someone waits for; with none left the worker stops holding the process. */
+    release() {
+        if (--this.wanted === 0)
+            this.worker.unref();
+    }
+    fail(error) {
+        if (this.failed)
+            return;
+        this.failed = true;
+        for (const job of this.posted.values())
+            if (!job.abandoned)
+                job.reject(error);
+        this.posted.clear();
+        this.queuedBytes = 0;
+        this.wanted = 0;
+        void this.worker.terminate();
+    }
+}
+let shared;
+/**
+ * The process's transcoder, started on first use. From source the worker runs as TypeScript, which
+ * Node loads with its types stripped.
+ */
+export function webpTranscoder() {
+    shared ??= new WorkerTranscoder(new URL(import.meta.url.endsWith(".ts") ? "./webp-encode-worker.ts" : "./webp-encode-worker.js", import.meta.url));
+    return shared;
+}

package/dist/evidence/webp.d.ts

@@ -0,0 +1,31 @@
+export interface WebpDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Why `bytes` is not a simple-format lossless WebP, or null with its dimensions when it is: RIFF
+ * and WEBP, then one VP8L chunk that ends the file (with its pad byte, zero, when its size is
+ * odd), whose header has the VP8L signature and version 0.
+ */
+export declare function webpStructure(bytes: Buffer): {
+    error: string;
+} | {
+    error: null;
+    dimensions: WebpDimensions;
+};
+/** The bytes webpHeaderDimensions reads: the RIFF header, the VP8L chunk header, the VP8L header. */
+export declare const WEBP_HEADER_BYTES: number;
+/**
+ * Width and height from the first WEBP_HEADER_BYTES of a simple-format lossless WebP: a VP8L
+ * signature and version 0. Undefined for anything else.
+ */
+export declare function webpHeaderDimensions(header: Buffer): WebpDimensions | undefined;
+/**
+ * The RGBA pixels of a WebP frame that webpStructure accepts, whose dimensions the caller has
+ * checked against its pixel cap; the decoder allocates from them.
+ */
+export declare function decodeWebp(bytes: Buffer): Promise<{
+    width: number;
+    height: number;
+    data: Buffer;
+}>;

package/dist/evidence/webp.js

@@ -0,0 +1,94 @@
+// Lossless WebP screenshots: the file shape verify accepts, and a bounded decode for the readers
+// that need pixels. Only the simple lossless form is accepted: a RIFF container holding one VP8L
+// chunk. The extended form (VP8X) is where EXIF, XMP, ICC and animation chunks live, so a frame
+// in the simple form carries image data only. The VP8L bitstream itself is not proven consumed,
+// so a WebP frame is never redacted evidence: a blurred frame is the PNG redactScreenshot writes.
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import decodeWebpImage, { init as initWebpDecoder } from "@jsquash/webp/decode.js";
+const RIFF_HEADER_BYTES = 12;
+const CHUNK_HEADER_BYTES = 8;
+const VP8L_SIGNATURE = 0x2f;
+/** The VP8L header: its signature byte, then 14-bit width and height, an alpha hint, a version. */
+const VP8L_HEADER_BYTES = 5;
+/**
+ * Why `bytes` is not a simple-format lossless WebP, or null with its dimensions when it is: RIFF
+ * and WEBP, then one VP8L chunk that ends the file (with its pad byte, zero, when its size is
+ * odd), whose header has the VP8L signature and version 0.
+ */
+export function webpStructure(bytes) {
+    const failed = (error) => ({ error });
+    if (bytes.length < RIFF_HEADER_BYTES + CHUNK_HEADER_BYTES + VP8L_HEADER_BYTES ||
+        bytes.toString("latin1", 0, 4) !== "RIFF" ||
+        bytes.toString("latin1", 8, 12) !== "WEBP")
+        return failed("expected a RIFF WEBP file");
+    if (bytes.readUInt32LE(4) !== bytes.length - 8)
+        return failed("the RIFF size does not match the file size");
+    const chunk = bytes.toString("latin1", 12, 16);
+    if (chunk !== "VP8L")
+        return failed(`WebP evidence must be one lossless VP8L chunk, not ${/^[A-Za-z0-9 ]{4}$/.test(chunk) ? chunk.trim() : "a malformed chunk"}`);
+    const size = bytes.readUInt32LE(16);
+    const start = RIFF_HEADER_BYTES + CHUNK_HEADER_BYTES;
+    const end = start + size + (size % 2);
+    if (end !== bytes.length || (size % 2 === 1 && bytes[end - 1] !== 0))
+        return failed("the VP8L chunk must end the file");
+    if (size < VP8L_HEADER_BYTES)
+        return failed("the VP8L chunk has no VP8L header");
+    const dimensions = webpHeaderDimensions(bytes);
+    if (dimensions === undefined)
+        return failed("the VP8L header is not one this reader knows");
+    return { error: null, dimensions };
+}
+/** The bytes webpHeaderDimensions reads: the RIFF header, the VP8L chunk header, the VP8L header. */
+export const WEBP_HEADER_BYTES = RIFF_HEADER_BYTES + CHUNK_HEADER_BYTES + VP8L_HEADER_BYTES;
+/**
+ * Width and height from the first WEBP_HEADER_BYTES of a simple-format lossless WebP: a VP8L
+ * signature and version 0. Undefined for anything else.
+ */
+export function webpHeaderDimensions(header) {
+    const start = RIFF_HEADER_BYTES + CHUNK_HEADER_BYTES;
+    if (header.length < WEBP_HEADER_BYTES ||
+        header.toString("latin1", 0, 4) !== "RIFF" ||
+        header.toString("latin1", 8, 16) !== "WEBPVP8L" ||
+        header[start] !== VP8L_SIGNATURE)
+        return undefined;
+    const bits = header.readUInt32LE(start + 1);
+    if (bits >>> 29 !== 0)
+        return undefined;
+    return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+}
+let decoderReady;
+/** Loads the decoder from the package's own wasm file: the codec's default fetches it by URL. */
+function readyDecoder() {
+    // The codec builds its result with ImageData, which Node does not define.
+    const scope = globalThis;
+    scope.ImageData ??= class {
+        data;
+        width;
+        height;
+        constructor(data, width, height) {
+            this.data = data;
+            this.width = width;
+            this.height = height;
+        }
+    };
+    decoderReady ??= readFile(createRequire(import.meta.url).resolve("@jsquash/webp/codec/dec/webp_dec.wasm"))
+        .then((wasm) => WebAssembly.compile(wasm))
+        .then((module) => initWebpDecoder(module));
+    return decoderReady;
+}
+/**
+ * The RGBA pixels of a WebP frame that webpStructure accepts, whose dimensions the caller has
+ * checked against its pixel cap; the decoder allocates from them.
+ */
+export async function decodeWebp(bytes) {
+    await readyDecoder();
+    const copy = new Uint8Array(bytes.length);
+    copy.set(bytes);
+    const image = await decodeWebpImage(copy.buffer);
+    return {
+        width: image.width,
+        height: image.height,
+        data: Buffer.from(image.data.buffer, image.data.byteOffset, image.data.byteLength),
+    };
+}

package/dist/feedback/derivative-text.d.ts

@@ -5,8 +5,13 @@ interface TextFile {
     bytes: Buffer;
 }
 export declare function jsonBytes(value: unknown): Buffer;
-export declare function transformText(file: TextFile, imagePaths: ReadonlySet<string>): Buffer;
+/**
+ * Each kept image's source path and the path the copy holds it at; they differ for a WebP frame,
+ * which the copy holds as a blurred PNG.
+ */
+type ImagePaths = ReadonlyMap<string, string>;
+export declare function transformText(file: TextFile, imagePaths: ImagePaths): Buffer;
 export declare function assertRewritableNumbers(json: string): void;
 /** The loaded source bundle as the copy records it: screenshots declared and labelled blurred. */
-export declare function derivedBundle(bundle: RunBundle, imagePaths: ReadonlySet<string>): RunBundle;
+export declare function derivedBundle(bundle: RunBundle, imagePaths: ImagePaths): RunBundle;
 export {};