harnery 0.38.0 → 0.40.0

package/dist/lib/browser/qa-snapshot.js

@@ -12,9 +12,12 @@
 // Storage is content-under-a-key, like visual-diff baselines: a directory per
 // target, a subdirectory per context, atomic writes (tmp + rename) so a
 // crashed writer never leaves a half-baseline the next run would trust.
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { PAGE_REVIEW_DECISIONS_SCHEMA, } from "./page-review-contracts.js";
+import { machineFindingKey, validateNativeEvidence } from "./page-review-evidence.js";
 import { fnv1a32 } from "./qa-plan.js";
 const SNAPSHOT_DIR = resolve(homedir(), ".cache", "harnery", "qa-snapshots");
 /** Filesystem-safe key for a target URL/file + render context. The digest
@@ -47,72 +50,280 @@ function contextDirName(context) {
 function snapshotDir(target, context, opts) {
     return resolve(opts.root ?? SNAPSHOT_DIR, qaSnapshotKey(target), contextDirName(context));
 }
+/** Serialize both owned slots across processes. A stuck writer fails closed. */
+function withStoreLock(dir, operation) {
+    mkdirSync(dir, { recursive: true });
+    const lock = resolve(dir, ".write-lock");
+    const deadline = Date.now() + 5_000;
+    while (true) {
+        try {
+            mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error(`Snapshot writer lock busy: ${dir}`);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    try {
+        return operation();
+    }
+    finally {
+        rmSync(lock, { recursive: true, force: true });
+    }
+}
+function validateDecisionSlot(target, context, slot) {
+    const only = (value, keys) => Object.keys(value).every((key) => keys.includes(key));
+    if (slot.schema !== PAGE_REVIEW_DECISIONS_SCHEMA ||
+        slot.complete !== true ||
+        slot.target !== target ||
+        slot.context.viewport !== context.viewport ||
+        slot.context.theme !== context.theme ||
+        slot.context.state !== context.state ||
+        slot.context.critique_contract_version !== 2 ||
+        ![slot.context.viewport_width, slot.context.viewport_height, slot.context.dpr].every((n) => Number.isFinite(n) && n > 0) ||
+        !/^[a-f0-9]{64}$/.test(slot.context.rubric_digest) ||
+        !slot.context.recipe_version ||
+        !only(slot, [
+            "schema",
+            "complete",
+            "target",
+            "context",
+            "source_run",
+            "source_revision",
+            "reviewer",
+            "reviewed_at",
+            "decisions",
+        ]) ||
+        !only(slot.context, [
+            "viewport",
+            "viewport_width",
+            "viewport_height",
+            "theme",
+            "state",
+            "dpr",
+            "recipe_version",
+            "rubric_digest",
+            "critique_contract_version",
+        ]) ||
+        !slot.reviewer?.trim() ||
+        !Number.isFinite(Date.parse(slot.reviewed_at)) ||
+        !slot.source_run ||
+        !Array.isArray(slot.decisions))
+        throw new Error("Invalid durable review decision slot");
+    const keys = new Set();
+    for (const decision of slot.decisions) {
+        if (!decision.reviewer?.trim() ||
+            !Number.isFinite(Date.parse(decision.at)) ||
+            keys.has(decision.finding_key) ||
+            !/^[a-f0-9]{64}$/.test(decision.tile_pixel_digest) ||
+            !only(decision, [
+                "finding_key",
+                "tile_pixel_digest",
+                "rect",
+                "finding",
+                "disposition",
+                "reviewer",
+                "at",
+                "note",
+            ]) ||
+            !only(decision.finding, ["severity", "category", "description"]) ||
+            !only(decision.rect, ["x", "y", "width", "height"]) ||
+            ![decision.rect.x, decision.rect.y, decision.rect.width, decision.rect.height].every(Number.isInteger) ||
+            decision.rect.x < 0 ||
+            decision.rect.y < 0 ||
+            decision.rect.width < 1 ||
+            decision.rect.height < 1 ||
+            !["artifact", "not-a-defect", "confirmed", "duplicate-of-gate"].includes(decision.disposition) ||
+            decision.finding.category === "provider-error" ||
+            machineFindingKey(slot.context, { rect: decision.rect, pixel_digest: decision.tile_pixel_digest }, decision.finding) !== decision.finding_key) {
+            throw new Error("Invalid durable review finding identity");
+        }
+        keys.add(decision.finding_key);
+    }
+}
+export function loadReviewDecisions(target, context, opts = {}) {
+    const dir = snapshotDir(target, context, opts);
+    if (!existsSync(dir))
+        return null;
+    try {
+        return withStoreLock(dir, () => {
+            const slot = JSON.parse(readFileSync(resolve(dir, "review-decisions.json"), "utf8"));
+            validateDecisionSlot(target, context, slot);
+            return slot;
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** Decisions contain text and digests only; replacing a baseline cannot touch this slot. */
+export function saveReviewDecisions(target, context, slot, opts = {}) {
+    validateDecisionSlot(target, context, slot);
+    const dir = snapshotDir(target, context, opts);
+    withStoreLock(dir, () => {
+        const path = resolve(dir, "review-decisions.json");
+        const temp = `${path}.tmp-${randomUUID()}`;
+        try {
+            writeFileSync(temp, `${JSON.stringify(slot)}\n`);
+            renameSync(temp, path);
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    });
+}
 /**
  * Persist a QA snapshot atomically. The whole context directory is staged as
  * `<dir>.tmp-<pid>` and renamed into place, replacing any prior snapshot for
  * the same target + context — a reader never observes a partial write.
  */
 export function saveQaSnapshot(target, context, content, opts = {}) {
-    const dir = snapshotDir(target, context, opts);
-    const staging = `${dir}.tmp-${process.pid}`;
-    rmSync(staging, { recursive: true, force: true });
-    mkdirSync(staging, { recursive: true });
-    writeFileSync(resolve(staging, "signature.json"), `${JSON.stringify(content.signature)}\n`);
-    if (content.domHtml !== undefined) {
-        writeFileSync(resolve(staging, "dom.html"), content.domHtml);
-    }
-    if (content.screenshotPng !== undefined) {
-        writeFileSync(resolve(staging, "screenshot.png"), content.screenshotPng);
-    }
-    if (content.critique !== undefined) {
-        writeFileSync(resolve(staging, "critique.json"), `${JSON.stringify(content.critique)}\n`);
-    }
-    rmSync(dir, { recursive: true, force: true });
-    renameSync(staging, dir);
-    return {
-        signature: content.signature,
-        path: dir,
-        ...(content.domHtml !== undefined ? { domHtmlPath: resolve(dir, "dom.html") } : {}),
-        ...(content.screenshotPng !== undefined
-            ? { screenshotPath: resolve(dir, "screenshot.png") }
-            : {}),
-    };
+    const container = snapshotDir(target, context, opts);
+    return withStoreLock(container, () => {
+        const dir = resolve(container, "baseline");
+        const staging = `${dir}.tmp-${randomUUID()}`;
+        const previous = `${dir}.previous`;
+        if (content.tileEvidence && content.screenshotPng)
+            throw new Error("A pack native-tile baseline must not retain a full-page image");
+        if (content.tileEvidence && !validateNativeEvidence(content.tileEvidence))
+            throw new Error("Invalid native tile baseline evidence");
+        mkdirSync(staging, { recursive: true });
+        try {
+            writeFileSync(resolve(staging, "signature.json"), `${JSON.stringify(content.signature)}\n`);
+            if (content.domHtml !== undefined) {
+                writeFileSync(resolve(staging, "dom.html"), content.domHtml);
+            }
+            if (content.screenshotPng !== undefined) {
+                writeFileSync(resolve(staging, "screenshot.png"), content.screenshotPng);
+            }
+            if (content.critique !== undefined) {
+                writeFileSync(resolve(staging, "critique.json"), `${JSON.stringify(content.critique)}\n`);
+            }
+            if (content.tileEvidence) {
+                const tiles = content.tileEvidence.tiles.map(({ png, ...tile }, i) => {
+                    const file = `tile-${i}.png`;
+                    writeFileSync(resolve(staging, file), png);
+                    return { ...tile, file };
+                });
+                writeFileSync(resolve(staging, "native-evidence.json"), JSON.stringify({ ...content.tileEvidence, tiles }));
+            }
+            // Recovery of a writer interrupted after moving its old baseline.
+            if (!existsSync(dir) && existsSync(previous))
+                renameSync(previous, dir);
+            rmSync(previous, { recursive: true, force: true });
+            if (existsSync(dir))
+                renameSync(dir, previous);
+            try {
+                renameSync(staging, dir);
+            }
+            catch (error) {
+                if (existsSync(previous))
+                    renameSync(previous, dir);
+                throw error;
+            }
+            rmSync(previous, { recursive: true, force: true });
+            // Remove superseded legacy baseline files, never the independent decision slot.
+            for (const name of [
+                "signature.json",
+                "dom.html",
+                "screenshot.png",
+                "critique.json",
+                "native-evidence.json",
+            ]) {
+                rmSync(resolve(container, name), { force: true });
+            }
+            return {
+                signature: content.signature,
+                path: dir,
+                ...(content.domHtml !== undefined ? { domHtmlPath: resolve(dir, "dom.html") } : {}),
+                ...(content.screenshotPng !== undefined
+                    ? { screenshotPath: resolve(dir, "screenshot.png") }
+                    : {}),
+                ...(content.critique ? { critique: content.critique } : {}),
+                ...(content.tileEvidence ? { tileEvidence: content.tileEvidence } : {}),
+            };
+        }
+        finally {
+            rmSync(staging, { recursive: true, force: true });
+        }
+    });
 }
 /** Load the persisted snapshot for a target + context, or null. A corrupt
  * signature file returns null (and the caller re-acquires a baseline) rather
  * than throwing — a bad cache entry must never block QA. */
 export function loadQaSnapshot(target, context, opts = {}) {
-    const dir = snapshotDir(target, context, opts);
-    const sigPath = resolve(dir, "signature.json");
-    if (!existsSync(sigPath))
+    const container = snapshotDir(target, context, opts);
+    if (!existsSync(container))
         return null;
     try {
-        const signature = JSON.parse(readFileSync(sigPath, "utf8"));
-        if (!signature || !Array.isArray(signature.nodes) || !Array.isArray(signature.stylesheets)) {
-            return null;
-        }
-        const domHtmlPath = resolve(dir, "dom.html");
-        const screenshotPath = resolve(dir, "screenshot.png");
-        const critiquePath = resolve(dir, "critique.json");
-        let critique;
-        if (existsSync(critiquePath)) {
+        return withStoreLock(container, () => {
+            const baseline = resolve(container, "baseline");
+            const dir = existsSync(baseline)
+                ? baseline
+                : existsSync(`${baseline}.previous`)
+                    ? `${baseline}.previous`
+                    : container;
+            const sigPath = resolve(dir, "signature.json");
+            if (!existsSync(sigPath))
+                return null;
             try {
-                const parsed = JSON.parse(readFileSync(critiquePath, "utf8"));
-                if (parsed && typeof parsed.contract_version === "number" && Array.isArray(parsed.tiles)) {
-                    critique = parsed;
+                const signature = JSON.parse(readFileSync(sigPath, "utf8"));
+                if (!signature ||
+                    !Array.isArray(signature.nodes) ||
+                    !Array.isArray(signature.stylesheets)) {
+                    return null;
+                }
+                const domHtmlPath = resolve(dir, "dom.html");
+                const screenshotPath = resolve(dir, "screenshot.png");
+                const critiquePath = resolve(dir, "critique.json");
+                let critique;
+                let tileEvidence;
+                try {
+                    const raw = JSON.parse(readFileSync(resolve(dir, "native-evidence.json"), "utf8"));
+                    const candidate = {
+                        ...raw,
+                        tiles: raw.tiles.map((tile) => {
+                            if (!/^tile-\d+\.png$/.test(tile.file))
+                                throw new Error("Invalid native tile path");
+                            return { ...tile, png: readFileSync(resolve(dir, tile.file)) };
+                        }),
+                    };
+                    if (validateNativeEvidence(candidate))
+                        tileEvidence = candidate;
+                }
+                catch {
+                    /* Missing or corrupt evidence is a cache miss. */
                 }
+                if (existsSync(critiquePath)) {
+                    try {
+                        const parsed = JSON.parse(readFileSync(critiquePath, "utf8"));
+                        if (parsed &&
+                            typeof parsed.contract_version === "number" &&
+                            Array.isArray(parsed.tiles)) {
+                            critique = parsed;
+                        }
+                    }
+                    catch {
+                        // corrupt critique.json degrades to a reuse miss, never an error
+                    }
+                }
+                return {
+                    signature,
+                    path: dir,
+                    ...(existsSync(domHtmlPath) ? { domHtmlPath } : {}),
+                    ...(existsSync(screenshotPath) ? { screenshotPath } : {}),
+                    ...(critique ? { critique } : {}),
+                    ...(tileEvidence ? { tileEvidence } : {}),
+                };
             }
             catch {
-                // corrupt critique.json degrades to a reuse miss, never an error
+                return null;
             }
-        }
-        return {
-            signature,
-            path: dir,
-            ...(existsSync(domHtmlPath) ? { domHtmlPath } : {}),
-            ...(existsSync(screenshotPath) ? { screenshotPath } : {}),
-            ...(critique ? { critique } : {}),
-        };
+        });
     }
     catch {
         return null;

package/dist/lib/browser/review-capture-transaction.d.ts

@@ -0,0 +1,13 @@
+import type { PageReviewCapturePlan, PageReviewContextAllocation } from "./page-review-contracts.js";
+/** Publish a complete context atomically; failed writes stay outside discoverable contexts. */
+export declare function writeCaptureTransaction<T>(packDir: string, contextId: string, write: (stage: string) => T): T;
+/** A preliminary allocation reserves pixels; it never supplies current source evidence. */
+export declare function allocateCaptureReservation(reservation: PageReviewContextAllocation, current: PageReviewCapturePlan): PageReviewContextAllocation;
+export declare class CaptureSourceChanged extends Error {
+    constructor(message?: string);
+}
+/** Gate-hit annotations may change, but source and every native rectangle must stay fixed. */
+export declare function assertGatePlanStable(before: PageReviewCapturePlan, after: PageReviewCapturePlan): void;
+/** One retry recollects every gate and allocation; no previous green result survives. */
+export declare function runCaptureTransaction<T>(collectAndAllocate: (attempt: number) => Promise<void>, capture: () => Promise<T>, recordFailure: (attempt: number, error: unknown) => void): Promise<T>;
+//# sourceMappingURL=review-capture-transaction.d.ts.map

package/dist/lib/browser/review-capture-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-capture-transaction.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/review-capture-transaction.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,qBAAqB,EACrB,2BAA2B,EAC5B,MAAM,4BAA4B,CAAC;AAGpC,+FAA+F;AAC/F,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,GAC1B,CAAC,CAgBH;AAED,2FAA2F;AAC3F,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,2BAA2B,EACxC,OAAO,EAAE,qBAAqB,GAC7B,2BAA2B,CA6B7B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,SAAiE;CAIrF;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,qBAAqB,GAC3B,IAAI,CAKN;AAED,yFAAyF;AACzF,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EACtD,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GACvD,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/lib/browser/review-capture-transaction.js

@@ -0,0 +1,79 @@
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { allocateTileBudget, capturePlanDigest, validatePageReviewAllocation, } from "./page-review-budget.js";
+import { packPaths } from "./page-review-pack.js";
+/** Publish a complete context atomically; failed writes stay outside discoverable contexts. */
+export function writeCaptureTransaction(packDir, contextId, write) {
+    mkdirSync(packDir, { recursive: true, mode: 0o700 });
+    const stage = mkdtempSync(join(packDir, ".pending-capture-"));
+    try {
+        const result = write(stage);
+        const destination = packPaths(packDir).contextDir(contextId);
+        mkdirSync(dirname(destination), { recursive: true });
+        if (existsSync(destination))
+            throw new Error("Capture context already exists; refusing to replace prior evidence.");
+        renameSync(packPaths(stage).contextDir(contextId), destination);
+        rmSync(stage, { recursive: true });
+        return result;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            error.message += ` Incomplete capture retained at ${stage}.`;
+        throw error;
+    }
+}
+/** A preliminary allocation reserves pixels; it never supplies current source evidence. */
+export function allocateCaptureReservation(reservation, current) {
+    validatePageReviewAllocation(reservation, reservation.plan);
+    for (const key of [
+        "context_id",
+        "viewport",
+        "viewport_width",
+        "viewport_height",
+        "theme",
+        "state",
+        "dpr",
+        "recipe_version",
+    ]) {
+        if (reservation.plan[key] !== current[key])
+            throw new Error(`Capture reservation changed ${key}.`);
+    }
+    if (reservation.plan.required_scopes.some((scope) => !current.required_scopes.includes(scope)))
+        throw new Error("Capture reservation lost a required scope.");
+    // Reservations sum to the original global allocation, even when its per-context
+    // ceiling was higher than the number of tiles actually assigned to that context.
+    const ceiling = reservation.selected_ids.length;
+    const allocation = allocateTileBudget([current], ceiling, { [current.context_id]: ceiling })
+        .contexts[0];
+    if (allocation.coverage.capped ||
+        allocation.coverage.omitted_scopes.length ||
+        allocation.coverage.uncovered_intervals.length)
+        throw new Error("Fresh native capture coverage exceeds the reserved tile budget.");
+    return validatePageReviewAllocation(allocation, current);
+}
+export class CaptureSourceChanged extends Error {
+    constructor(message = "Page source changed during the gate and capture transaction.") {
+        super(message);
+        this.name = "CaptureSourceChanged";
+    }
+}
+/** Gate-hit annotations may change, but source and every native rectangle must stay fixed. */
+export function assertGatePlanStable(before, after) {
+    if (capturePlanDigest(before) !== capturePlanDigest(after))
+        throw new CaptureSourceChanged("Page source or geometry changed while deterministic gates were running.");
+}
+/** One retry recollects every gate and allocation; no previous green result survives. */
+export async function runCaptureTransaction(collectAndAllocate, capture, recordFailure) {
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        try {
+            await collectAndAllocate(attempt);
+            return await capture();
+        }
+        catch (error) {
+            recordFailure(attempt, error);
+            if (!(error instanceof CaptureSourceChanged) || attempt === 2)
+                throw error;
+        }
+    }
+    throw new Error("Capture transaction did not complete.");
+}

package/dist/lib/browser/standalone-html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"standalone-html.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/standalone-html.ts"],"names":[],"mappings":"AAmBA,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD,iEAAiE;AACjE,eAAO,MAAM,gCAAgC,QAAkB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,yBAAyB,IAAI,CAC3C,IAAI,EAAE,qBAAqB,KACxB,OAAO,CAAC,oBAAoB,CAAC,CAuQjC"}
+{"version":3,"file":"standalone-html.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/standalone-html.ts"],"names":[],"mappings":"AAmBA,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD,iEAAiE;AACjE,eAAO,MAAM,gCAAgC,QAAkB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,yBAAyB,IAAI,CAC3C,IAAI,EAAE,qBAAqB,KACxB,OAAO,CAAC,oBAAoB,CAAC,CAyQjC"}

package/dist/lib/browser/standalone-html.js

@@ -45,7 +45,9 @@ export function buildStandaloneHtmlScript() {
                 return cached;
             let result = null;
             try {
-                const res = await fetch(url, { credentials: "include" });
+                // Retain access to authenticated same-origin assets without imposing
+                // credentialed CORS on public assets served by another origin.
+                const res = await fetch(url, { credentials: "same-origin" });
                 if (res.ok) {
                     const buf = await res.arrayBuffer();
                     const fits = buf.byteLength <= maxResourceBytes &&
@@ -137,7 +139,7 @@ export function buildStandaloneHtmlScript() {
             }
             let css = null;
             try {
-                const res = await fetch(url, { credentials: "include" });
+                const res = await fetch(url, { credentials: "same-origin" });
                 if (res.ok)
                     css = await res.text();
             }

package/dist/lib/browser/thumbnail-association.d.ts

@@ -0,0 +1,34 @@
+export interface CaptureFingerprint {
+    version: string;
+    sha256: string;
+}
+export interface CaptureThumbnailAssociation {
+    schema_version: 2;
+    producer: "browser-standalone-capture";
+    source: CaptureFingerprint & {
+        path: string;
+    };
+    preview: CaptureFingerprint & {
+        path: string;
+    };
+}
+/** Take immediately after the screenshot writer completes, before asynchronous
+ * HTML serialization. A later writer cannot silently substitute its PNG. */
+export declare function captureThumbnailFingerprint(pngPath: string): CaptureFingerprint | null;
+/** Associate only the full-document, standalone HTML and exact PNG produced by
+ * this capture operation. No basename inference and no reads of source pages.
+ * A linked asset, selector fragment, changed output, oversize file or output
+ * outside a managed artifact workspace safely skips registration.
+ * The hidden sidecar binds canonical repository paths, checked file versions
+ * and SHA256 receipts. Web readers also require an empty local asset graph;
+ * manual registrations bind their own complete dependency graph instead. */
+export declare function registerCaptureThumbnail(input: {
+    htmlPath: string;
+    pngPath: string;
+    html: string;
+    preview: CaptureFingerprint;
+    fullDocument: boolean;
+    stylesheetsLinked: number;
+    resourcesLinked: number;
+}): string | null;
+//# sourceMappingURL=thumbnail-association.d.ts.map

package/dist/lib/browser/thumbnail-association.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-association.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/thumbnail-association.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,2BAA2B;IAC1C,cAAc,EAAE,CAAC,CAAC;IAClB,QAAQ,EAAE,4BAA4B,CAAC;IACvC,MAAM,EAAE,kBAAkB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,OAAO,EAAE,kBAAkB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AA8BD;4EAC4E;AAC5E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAMtF;AAwBD;;;;;;4EAM4E;AAC5E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,kBAAkB,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,GAAG,IAAI,CAsFhB"}

package/dist/lib/browser/thumbnail-association.js

@@ -0,0 +1,158 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import path from "node:path";
+const MAX_HTML = 2 * 1024 * 1024;
+const MAX_PNG = 32 * 1024 * 1024;
+function version(fd) {
+    const s = fstatSync(fd);
+    return `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`;
+}
+function fingerprint(filename, maxBytes) {
+    const canonical = realpathSync(filename);
+    const before = statSync(canonical);
+    if (!before.isFile() || before.size > maxBytes)
+        return null;
+    const fd = openSync(canonical, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino)
+            return null;
+        const initial = version(fd);
+        const hash = createHash("sha256");
+        const bytes = Buffer.alloc(64 * 1024);
+        let offset = 0;
+        while (offset < before.size) {
+            const count = readSync(fd, bytes, 0, Math.min(bytes.length, before.size - offset), offset);
+            if (!count)
+                return null;
+            hash.update(bytes.subarray(0, count));
+            offset += count;
+        }
+        if (version(fd) !== initial || realpathSync(filename) !== canonical)
+            return null;
+        return { version: initial, sha256: hash.digest("hex") };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Take immediately after the screenshot writer completes, before asynchronous
+ * HTML serialization. A later writer cannot silently substitute its PNG. */
+export function captureThumbnailFingerprint(pngPath) {
+    try {
+        return fingerprint(pngPath, MAX_PNG);
+    }
+    catch {
+        return null;
+    }
+}
+function workspaceFor(filename) {
+    for (let current = path.dirname(filename); path.dirname(current) !== current; current = path.dirname(current)) {
+        const artifacts = path.dirname(current);
+        const state = path.dirname(artifacts);
+        if (path.basename(artifacts) === "artifacts" && path.basename(state) === ".harnery")
+            return { root: path.dirname(state), workspace: current };
+    }
+    return null;
+}
+function inside(root, filename) {
+    const relative = path.relative(root, filename);
+    return (relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+/** Associate only the full-document, standalone HTML and exact PNG produced by
+ * this capture operation. No basename inference and no reads of source pages.
+ * A linked asset, selector fragment, changed output, oversize file or output
+ * outside a managed artifact workspace safely skips registration.
+ * The hidden sidecar binds canonical repository paths, checked file versions
+ * and SHA256 receipts. Web readers also require an empty local asset graph;
+ * manual registrations bind their own complete dependency graph instead. */
+export function registerCaptureThumbnail(input) {
+    if (!input.fullDocument || input.stylesheetsLinked !== 0 || input.resourcesLinked !== 0)
+        return null;
+    try {
+        const htmlPath = realpathSync(input.htmlPath);
+        const pngPath = realpathSync(input.pngPath);
+        if (!/\.html?$/i.test(htmlPath) || !/\.png$/i.test(pngPath))
+            return null;
+        const owner = workspaceFor(htmlPath);
+        if (!owner || !inside(owner.workspace, pngPath))
+            return null;
+        const source = fingerprint(htmlPath, MAX_HTML);
+        const preview = fingerprint(pngPath, MAX_PNG);
+        if (!source ||
+            !preview ||
+            source.sha256 !== createHash("sha256").update(input.html).digest("hex") ||
+            preview.version !== input.preview.version ||
+            preview.sha256 !== input.preview.sha256)
+            return null;
+        const sourceRelative = path.relative(owner.root, htmlPath).split(path.sep).join("/");
+        const previewRelative = path.relative(owner.root, pngPath).split(path.sep).join("/");
+        const association = {
+            schema_version: 2,
+            producer: "browser-standalone-capture",
+            source: { path: sourceRelative, ...source },
+            preview: { path: previewRelative, ...preview },
+        };
+        const name = `.thumbnail-preview-${createHash("sha256").update(sourceRelative).digest("hex").slice(0, 24)}.json`;
+        const directoryFd = openSync(owner.workspace, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            let anchor;
+            for (const prefix of ["/proc/self/fd", "/dev/fd"]) {
+                const candidate = `${prefix}/${directoryFd}`;
+                try {
+                    if (realpathSync(candidate) === owner.workspace) {
+                        anchor = candidate;
+                        break;
+                    }
+                }
+                catch {
+                    /* unsupported descriptor namespace */
+                }
+            }
+            if (!anchor)
+                return null;
+            const target = path.join(anchor, name);
+            const temporary = `${target}.${randomUUID()}.tmp`;
+            const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                const bytes = Buffer.from(`${JSON.stringify(association)}\n`);
+                if (bytes.length > 16 * 1024)
+                    return null;
+                let offset = 0;
+                while (offset < bytes.length)
+                    offset += writeSync(fd, bytes, offset, bytes.length - offset);
+                if (realpathSync(anchor) !== owner.workspace ||
+                    realpathSync(owner.workspace) !== owner.workspace)
+                    return null;
+                // Stat again after the write, without reading another potentially large
+                // image. ctime detects same-size edits with a restored mtime.
+                const matches = (filename, expected) => {
+                    const s = statSync(filename);
+                    return `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}` === expected;
+                };
+                if (!matches(htmlPath, source.version) || !matches(pngPath, preview.version))
+                    return null;
+                renameSync(temporary, target);
+            }
+            finally {
+                closeSync(fd);
+                try {
+                    unlinkSync(temporary);
+                }
+                catch {
+                    /* renamed */
+                }
+            }
+        }
+        finally {
+            closeSync(directoryFd);
+        }
+        return path.relative(owner.root, path.join(owner.workspace, name)).split(path.sep).join("/");
+    }
+    catch {
+        return null;
+    }
+}