@afixt/screenshot-utils 0.9.0 → 1.0.0

package/dist/types/errors/optional.d.ts

@@ -0,0 +1,23 @@
+/**
+ * An operation needs an optional peer dependency that isn't installed
+ * (e.g., calling `diff()` without `pixelmatch`). The error message MUST
+ * include the install command for the missing package.
+ *
+ * @public
+ */
+export class OptionalDependencyMissingError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     * @param {string} [options.packageName] The npm package the caller must install.
+     * @param {string} [options.installCommand] Suggested install command (default: derived).
+     */
+    constructor(message: string, options?: {
+        packageName?: string | undefined;
+        installCommand?: string | undefined;
+    });
+    packageName: string | undefined;
+    installCommand: string | undefined;
+}
+import { ScreenshotUtilsError } from "./base.js";
+//# sourceMappingURL=optional.d.ts.map

package/dist/types/errors/optional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional.d.ts","sourceRoot":"","sources":["../../../src/errors/optional.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH;IACI;;;;;OAKG;IACH,qBALW,MAAM,YAEd;QAAyB,WAAW;QACX,cAAc;KACzC,EAcA;IAPO,gCAA8B;IAG9B,mCAAoC;CAK/C"}

package/dist/types/errors/redaction.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Base for errors arising during redaction (blur / mask / pixelate, PII policies).
+ *
+ * @public
+ */
+export class RedactionError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * A PII policy object is malformed or references unknown rule keys.
+ *
+ * @public
+ */
+export class PolicyError extends RedactionError {
+}
+import { ScreenshotUtilsError } from "./base.js";
+//# sourceMappingURL=redaction.d.ts.map

package/dist/types/errors/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../../src/errors/redaction.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;CAUC"}

package/dist/types/errors/tile.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Base for errors arising during DZI tile generation.
+ *
+ * @public
+ */
+export class TileError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * `tileSize` is invalid (must be 256 or 512 per spec § 8.4.1).
+ *
+ * @public
+ */
+export class TileSizeError extends TileError {
+}
+/**
+ * Writing tiles to the output directory failed (only in `output: 'directory'` mode).
+ * Retriable because the underlying cause is usually transient (disk full, permissions race).
+ *
+ * @public
+ */
+export class TileWriteError extends TileError {
+}
+import { ScreenshotUtilsError } from "./base.js";
+//# sourceMappingURL=tile.d.ts.map

package/dist/types/errors/tile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tile.d.ts","sourceRoot":"","sources":["../../../src/errors/tile.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;CAUC;AAED;;;;;GAKG;AACH;CAUC"}

package/dist/types/errors/transform.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Base for errors arising during image-buffer transforms (crop, resize, convert, normalize).
+ *
+ * @public
+ */
+export class TransformError extends ScreenshotUtilsError {
+    /**
+     * @param {string} message
+     * @param {object} [options]
+     */
+    constructor(message: string, options?: object);
+}
+/**
+ * A rect is malformed or lies outside the source image bounds.
+ *
+ * @public
+ */
+export class InvalidRectError extends TransformError {
+}
+/**
+ * The requested output format is not supported (e.g., AVIF in v1.0).
+ *
+ * @public
+ */
+export class UnsupportedFormatError extends TransformError {
+}
+/**
+ * Sharp could not decode the input buffer (truncated, wrong format, corrupt).
+ *
+ * @public
+ */
+export class BufferCorruptError extends TransformError {
+}
+import { ScreenshotUtilsError } from "./base.js";
+//# sourceMappingURL=transform.d.ts.map

package/dist/types/errors/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../../src/errors/transform.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI;;;OAGG;IACH,qBAHW,MAAM,YACN,MAAM,EAMhB;CACJ;AAED;;;;GAIG;AACH;CAUC;AAED;;;;GAIG;AACH;CAUC;AAED;;;;GAIG;AACH;CAUC"}

package/dist/types/index.d.ts

@@ -0,0 +1,58 @@
+declare const _exports: {
+    annotate: typeof compose.annotate;
+    defaultTheme: Readonly<import("./types/index.d.ts").AnnotationTheme>;
+    diff: typeof compose.diff;
+    heatmap: typeof compose.heatmap;
+    tileDzi: typeof tile.tileDzi;
+    crop: typeof transform.crop;
+    cropMany: typeof transform.cropMany;
+    convert: typeof transform.convert;
+    resize: typeof transform.resize;
+    normalize: typeof transform.normalize;
+    capturePage: typeof capture.capturePage;
+    waitForStable: typeof capture.waitForStable;
+    captureLongPage: typeof capture.captureLongPage;
+    captureElement: typeof capture.captureElement;
+    captureViewport: typeof capture.captureViewport;
+    captureResponsive: typeof capture.captureResponsive;
+    fromPuppeteerPage: typeof adapters.fromPuppeteerPage;
+    fromPlaywrightPage: typeof adapters.fromPlaywrightPage;
+    fromCDPSession: typeof adapters.fromCDPSession;
+    ScreenshotUtilsError: typeof errors.ScreenshotUtilsError;
+    CaptureError: typeof errors.CaptureError;
+    BrowserUnavailableError: typeof errors.BrowserUnavailableError;
+    PageTooTallError: typeof errors.PageTooTallError;
+    ElementNotFoundError: typeof errors.ElementNotFoundError;
+    ElementNotVisibleError: typeof errors.ElementNotVisibleError;
+    ElementMismatchError: typeof errors.ElementMismatchError;
+    ElementTooLargeError: typeof errors.ElementTooLargeError;
+    StabilityTimeoutError: typeof errors.StabilityTimeoutError;
+    CaptureTimeoutError: typeof errors.CaptureTimeoutError;
+    TransformError: typeof errors.TransformError;
+    InvalidRectError: typeof errors.InvalidRectError;
+    UnsupportedFormatError: typeof errors.UnsupportedFormatError;
+    BufferCorruptError: typeof errors.BufferCorruptError;
+    ComposeError: typeof errors.ComposeError;
+    DimensionMismatchError: typeof errors.DimensionMismatchError;
+    ThemeError: typeof errors.ThemeError;
+    HeatmapPointError: typeof errors.HeatmapPointError;
+    TileError: typeof errors.TileError;
+    TileSizeError: typeof errors.TileSizeError;
+    TileWriteError: typeof errors.TileWriteError;
+    RedactionError: typeof errors.RedactionError;
+    PolicyError: typeof errors.PolicyError;
+    AdapterError: typeof errors.AdapterError;
+    AdapterContractError: typeof errors.AdapterContractError;
+    BrowserApiError: typeof errors.BrowserApiError;
+    OptionalDependencyMissingError: typeof errors.OptionalDependencyMissingError;
+    defaults: Readonly<import("./types/index.d.ts").ScreenshotUtilsDefaults>;
+    version: string;
+};
+export = _exports;
+import compose = require("./compose/index.js");
+import tile = require("./tile/index.js");
+import transform = require("./transform/index.js");
+import capture = require("./capture/index.js");
+import adapters = require("./adapters/index.js");
+import errors = require("./errors/index.js");
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.js"],"names":[],"mappings":""}

package/dist/types/redact/index.d.ts

@@ -0,0 +1,5 @@
+import { redact } from "./redact.js";
+import { applyPiiPolicy } from "./policy.js";
+import { defaultPiiPolicy } from "./policy.js";
+export { redact, applyPiiPolicy, defaultPiiPolicy };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/redact/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/redact/index.js"],"names":[],"mappings":""}

package/dist/types/redact/policy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Apply a PII policy to a screenshot using a pre-collected list of element
+ * rects + classification metadata.
+ *
+ * Implements `spec.md` § 8.5.2. The function does NOT inspect a DOM
+ * directly — callers run a page-context evaluator that produces the
+ * `regions` array (an array of `{ rect, classification? }` objects) and
+ * pass it here. This keeps the package DOM-agnostic.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<{rect: import('../types/index.d.ts').Rect, classification?: string}>} regions
+ * @param {import('../types/index.d.ts').PiiPolicy} [policy]
+ * @returns {Promise<Buffer>}
+ */
+export function applyPiiPolicy(input: Buffer, regions: Array<{
+    rect: import("../types/index.d.ts").Rect;
+    classification?: string;
+}>, policy?: import("../types/index.d.ts").PiiPolicy): Promise<Buffer>;
+/**
+ * Default PII policy bundled with the package. Consumers tighten it per
+ * their privacy posture; this is the conservative starting point per
+ * `spec.md` § 8.5.2.
+ *
+ * @public
+ * @type {Readonly<import('../types/index.d.ts').PiiPolicy>}
+ */
+export const defaultPiiPolicy: Readonly<import("../types/index.d.ts").PiiPolicy>;
+//# sourceMappingURL=policy.d.ts.map

package/dist/types/redact/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/redact/policy.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;GAcG;AACH,sCALW,MAAM,WACN,KAAK,CAAC;IAAC,IAAI,EAAE,OAAO,qBAAqB,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,WAC1E,OAAO,qBAAqB,EAAE,SAAS,GACrC,OAAO,CAAC,MAAM,CAAC,CA+B3B;AA3DD;;;;;;;GAOG;AACH,+BAFU,QAAQ,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,CAOxD"}

package/dist/types/redact/redact.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Apply one of three redaction modes to specified regions of an image.
+ *
+ * Implements `spec.md` § 8.5.1.
+ *
+ * - `mode: 'blur'` — Gaussian blur with the given `radius`.
+ * - `mode: 'mask'` — solid-color fill (`color`, default `#000`).
+ * - `mode: 'pixelate'` — downscale-then-upscale with the given `cellSize`.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<import('../types/index.d.ts').RedactRegion>} regions
+ * @param {import('../types/index.d.ts').RedactOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+export function redact(input: Buffer, regions: Array<import("../types/index.d.ts").RedactRegion>, options?: import("../types/index.d.ts").RedactOptions): Promise<Buffer>;
+/**
+ * Parse a CSS color string (`#rgb`, `#rrggbb`, `#rrggbbaa`, or named black).
+ *
+ * @param {string} color
+ * @returns {{r: number, g: number, b: number, alpha: number}}
+ */
+export function parseColor(color: string): {
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+};
+//# sourceMappingURL=redact.d.ts.map

package/dist/types/redact/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/redact/redact.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,8BALW,MAAM,WACN,KAAK,CAAC,OAAO,qBAAqB,EAAE,YAAY,CAAC,YACjD,OAAO,qBAAqB,EAAE,aAAa,GACzC,OAAO,CAAC,MAAM,CAAC,CA6C3B;AA4ID;;;;;GAKG;AACH,kCAHW,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAgC5D"}

package/dist/types/tile/dzi.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Generate a Deep Zoom Image pyramid from a source buffer using
+ * `sharp().tile({ layout: 'dz' })`.
+ *
+ * Implements `spec.md` § 8.4.1. Three output modes:
+ * - `'buffers'` (default): returns tile bytes in memory, cleans up the temp dir.
+ * - `'directory'`: returns the path to the temp dir; the caller is responsible
+ *   for moving / uploading / deleting it.
+ * - `'stream'`: NOT IMPLEMENTED in v1.0 (per spec § 22 — deferred to v1.1).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').TileDziOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').DziResult>}
+ */
+export function tileDzi(input: Buffer, options?: import("../types/index.d.ts").TileDziOptions): Promise<import("../types/index.d.ts").DziResult>;
+export const MAX_TILES: 10000;
+//# sourceMappingURL=dzi.d.ts.map

package/dist/types/tile/dzi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dzi.d.ts","sourceRoot":"","sources":["../../../src/tile/dzi.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH,+BAJW,MAAM,YACN,OAAO,qBAAqB,EAAE,cAAc,GAC1C,OAAO,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,CA6F5D;AA5GD,wBAAkB,KAAM,CAAC"}

package/dist/types/tile/index.d.ts

@@ -0,0 +1,3 @@
+export { tileDzi };
+import { tileDzi } from "./dzi.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/tile/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tile/index.js"],"names":[],"mappings":""}

package/dist/types/transform/convert.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Re-encode a buffer to a different image format.
+ *
+ * Implements `spec.md` § 8.2.4. Thin wrapper over `sharp(buf).toFormat()`
+ * with safer defaults and the package's error contract.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').ConvertOptions} options
+ * @returns {Promise<Buffer>}
+ */
+export function convert(input: Buffer, options: import("../types/index.d.ts").ConvertOptions): Promise<Buffer>;
+//# sourceMappingURL=convert.d.ts.map

package/dist/types/transform/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/transform/convert.js"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,+BAJW,MAAM,WACN,OAAO,qBAAqB,EAAE,cAAc,GAC1C,OAAO,CAAC,MAAM,CAAC,CA8B3B"}

package/dist/types/transform/crop.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Extract a single rectangle from a source image buffer.
+ *
+ * Implements `spec.md` § 8.2.1. All coordinates are CSS pixels. Padding
+ * expands the rect in all four directions and is then clamped to the
+ * image bounds (we never error on padding causing under/overflow — the
+ * caller asked for slack, not arithmetic).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').Rect} rect
+ * @param {import('../types/index.d.ts').CropOptions} [options]
+ * @returns {Promise<Buffer>}
+ */
+export function crop(input: Buffer, rect: import("../types/index.d.ts").Rect, options?: import("../types/index.d.ts").CropOptions): Promise<Buffer>;
+/**
+ * Extract many rectangles in parallel from one source. Used by the engine's
+ * `_captureIssueScreenshots` migration path (one full-page capture + many
+ * crops beats N per-element captures by ~20×).
+ *
+ * Implements `spec.md` § 8.2.2.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {Array<{ id: string, rect: import('../types/index.d.ts').Rect }>} entries
+ * @param {import('../types/index.d.ts').CropManyOptions} [options]
+ * @returns {Promise<Map<string, Buffer>>}
+ */
+export function cropMany(input: Buffer, entries: Array<{
+    id: string;
+    rect: import("../types/index.d.ts").Rect;
+}>, options?: import("../types/index.d.ts").CropManyOptions): Promise<Map<string, Buffer>>;
+//# sourceMappingURL=crop.d.ts.map

package/dist/types/transform/crop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crop.d.ts","sourceRoot":"","sources":["../../../src/transform/crop.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,4BALW,MAAM,QACN,OAAO,qBAAqB,EAAE,IAAI,YAClC,OAAO,qBAAqB,EAAE,WAAW,GACvC,OAAO,CAAC,MAAM,CAAC,CAoB3B;AAED;;;;;;;;;;;;GAYG;AACH,gCALW,MAAM,WACN,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,qBAAqB,EAAE,IAAI,CAAA;CAAE,CAAC,YAC/D,OAAO,qBAAqB,EAAE,eAAe,GAC3C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAoDxC"}

package/dist/types/transform/index.d.ts

@@ -0,0 +1,7 @@
+import { crop } from "./crop.js";
+import { cropMany } from "./crop.js";
+import { convert } from "./convert.js";
+import { resize } from "./resize.js";
+import { normalize } from "./normalize.js";
+export { crop, cropMany, convert, resize, normalize };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/transform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transform/index.js"],"names":[],"mappings":""}

package/dist/types/transform/normalize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize an image buffer to a target device-pixel ratio so its coordinate
+ * space is CSS pixels regardless of the source DPR.
+ *
+ * Implements `spec.md` § 8.2.5. Default behavior preserves the image's
+ * intrinsic DPR (caller opts in to normalization for cross-DPR comparison).
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').NormalizeOptions} [options]
+ * @returns {Promise<import('../types/index.d.ts').NormalizeResult>}
+ */
+export function normalize(input: Buffer, options?: import("../types/index.d.ts").NormalizeOptions): Promise<import("../types/index.d.ts").NormalizeResult>;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/types/transform/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/transform/normalize.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,iCAJW,MAAM,YACN,OAAO,qBAAqB,EAAE,gBAAgB,GAC5C,OAAO,CAAC,OAAO,qBAAqB,EAAE,eAAe,CAAC,CAiClE"}

package/dist/types/transform/resize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resize an image buffer with sharp-native semantics.
+ *
+ * Implements `spec.md` § 8.2.3. Honors `width`, `height`, `fit`, `position`,
+ * `kernel`, and `withoutEnlargement`. At least one of `width` or `height`
+ * must be supplied.
+ *
+ * @public
+ * @param {Buffer} input
+ * @param {import('../types/index.d.ts').ResizeOptions} options
+ * @returns {Promise<Buffer>}
+ */
+export function resize(input: Buffer, options: import("../types/index.d.ts").ResizeOptions): Promise<Buffer>;
+//# sourceMappingURL=resize.d.ts.map

package/dist/types/transform/resize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize.d.ts","sourceRoot":"","sources":["../../../src/transform/resize.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,8BAJW,MAAM,WACN,OAAO,qBAAqB,EAAE,aAAa,GACzC,OAAO,CAAC,MAAM,CAAC,CA0E3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/screenshot-utils",
-    "version": "0.9.0",
+    "version": "1.0.0",
     "description": "Screenshot capture, transform, compose, tile, and redact utilities for the AFixt/Revenant accessibility platform",
     "type": "commonjs",
     "main": "./dist/index.js",
@@ -83,7 +83,7 @@
         "access": "restricted"
     },
     "engines": {
-        "node": ">=22.22.1"
+        "node": ">=20.0.0"
     },
     "keywords": [
         "screenshot",
@@ -132,7 +132,7 @@
         "@commitlint/config-conventional": "20.5.3",
         "@eslint/js": "10.0.1",
         "@types/node": "22.19.19",
-        "@vitest/coverage-v8": "4.1.5",
+        "@vitest/coverage-istanbul": "4.1.5",
         "clean-jsdoc-theme": "4.3.2",
         "eslint": "10.3.0",
         "eslint-plugin-import-x": "4.16.2",
@@ -151,6 +151,7 @@
         "lint-staged": "17.0.2",
         "markdownlint-cli": "0.48.0",
         "npm-run-all2": "8.0.4",
+        "openseadragon": "6.0.2",
         "pixelmatch": "7.1.0",
         "playwright": "1.60.0",
         "pngjs": "7.0.0",

package/src/capture/element.js

@@ -139,9 +139,9 @@ async function captureElement(adapter, options = {}) {
  * @param {{selector?: string, xpath?: string}} args
  * @returns {{found: false} | {found: true, outerHTML: string, documentRect: import('../types/index.d.ts').Rect, viewportRect: import('../types/index.d.ts').Rect}}
  */
-/* v8 ignore start -- runs in the browser via adapter.evaluate(); not
-   instrumentable by Node-side coverage. Exercised by the puppeteer/playwright
-   element-capture integration tests. */
+/* istanbul ignore next -- runs in the browser via adapter.evaluate(); must NOT
+   be instrumented (injected counters don't exist in the page context) and is
+   exercised by the puppeteer/playwright element-capture integration tests. */
 function findElementInPage(args) {
     const doc = globalThis.document;
     let element;
@@ -184,7 +184,6 @@ function findElementInPage(args) {
         },
     };
 }
-/* v8 ignore stop */
 
 /**
  * Build a failure-shaped ElementCaptureResult that preserves the engine's

package/src/capture/settle.js

@@ -42,8 +42,9 @@ async function waitForStable(adapter, options = {}) {
  * @param {{fonts: boolean, images: boolean, animations: 'reduce'|'wait'|'ignore', maxWait: number, idleMs: number}} opts
  * @returns {Promise<Omit<import('../types/index.d.ts').StabilityReport, 'totalMs'>>}
  */
-/* v8 ignore start -- runs in the browser via adapter.evaluate(); not
-   instrumentable by Node-side coverage. Exercised by settle-integration.test.js. */
+/* istanbul ignore next -- runs in the browser via adapter.evaluate(); must NOT
+   be instrumented (injected counters don't exist in the page context) and is
+   exercised by settle-integration.test.js. */
 async function runInPage(opts) {
     const doc = globalThis.document;
     /** @type {Omit<import('../types/index.d.ts').StabilityReport, 'totalMs'>} */
@@ -173,7 +174,6 @@ async function runInPage(opts) {
 
     return report;
 }
-/* v8 ignore stop */
 
 function nowMs() {
     return Number(process.hrtime.bigint() / 1_000_000n);