@afixt/screenshot-utils 0.9.0 → 1.1.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.1.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.9.0"
     },
     "keywords": [
         "screenshot",
@@ -101,7 +101,7 @@
         "revenant"
     ],
     "dependencies": {
-        "sharp": "0.34.5"
+        "sharp": "^0.35.3"
     },
     "peerDependencies": {
         "@napi-rs/canvas": "^0.1.0",
@@ -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

@@ -1,6 +1,7 @@
 'use strict';
 
 const { CaptureTimeoutError } = require('../errors/index.js');
+const { waitForStable } = require('./settle.js');
 
 /**
  * Capture a single element by selector or xpath.
@@ -31,6 +32,7 @@ async function captureElement(adapter, options = {}) {
         timeout = 5000,
         format = 'png',
         quality = 90,
+        waitForStable: settleOpts = false,
         events = null,
     } = options;
 
@@ -77,6 +79,7 @@ async function captureElement(adapter, options = {}) {
     }
 
     let viewportRect = lookup.viewportRect;
+    let documentRect = lookup.documentRect;
     if (scrollIntoView) {
         await adapter.scrollTo({
             x: 0,
@@ -93,6 +96,17 @@ async function captureElement(adapter, options = {}) {
         }
     }
 
+    // Optional render-stability wait. Critically, we re-read the element rect
+    // *after* settling: late reflow (lazy images, web fonts, JS layout) is the
+    // cause of blank/wrong-region element crops, so coordinates captured before
+    // settle cannot be trusted for the clip.
+    const settled = await settleAndReread(adapter, { selector, xpath, timeout, settleOpts });
+    const settleMs = settled.settleMs;
+    if (settled.rect) {
+        viewportRect = settled.rect.viewportRect;
+        documentRect = settled.rect.documentRect;
+    }
+
     const clip = {
         x: Math.max(0, Math.round(viewportRect.x - padding)),
         y: Math.max(0, Math.round(viewportRect.y - padding)),
@@ -117,12 +131,12 @@ async function captureElement(adapter, options = {}) {
         format,
         bytes,
         page: metrics,
-        timing: { settleMs: 0, captureMs, encodeMs: 0, totalMs },
+        timing: { settleMs, captureMs, encodeMs: 0, totalMs },
         warnings: [],
         element: {
             selector: selector ?? '',
             xpath: xpath ?? '',
-            documentRect: lookup.documentRect,
+            documentRect,
             viewportRect,
             verified: Boolean(snippet),
         },
@@ -131,6 +145,35 @@ async function captureElement(adapter, options = {}) {
     return result;
 }
 
+/**
+ * Run waitForStable (when requested) and re-read the element rect afterwards.
+ * Kept out of `captureElement` so the main flow stays flat.
+ *
+ * @param {import('../types/index.d.ts').PageAdapter} adapter
+ * @param {{selector?: string, xpath?: string, timeout: number, settleOpts: import('../types/index.d.ts').WaitForStableOptions|boolean}} ctx
+ * @returns {Promise<{settleMs: number, rect: {viewportRect: import('../types/index.d.ts').Rect, documentRect: import('../types/index.d.ts').Rect}|null}>}
+ */
+async function settleAndReread(adapter, { selector, xpath, timeout, settleOpts }) {
+    if (!settleOpts) {
+        return { settleMs: 0, rect: null };
+    }
+    const settleStart = nowMs();
+    await waitForStable(adapter, settleOpts === true ? {} : settleOpts);
+    const settleMs = nowMs() - settleStart;
+    const reread = await withTimeout(
+        adapter.evaluate(findElementInPage, { selector, xpath }),
+        timeout,
+        { operation: 'adapter.evaluate(findElement after settle)' }
+    );
+    if (reread && reread.found) {
+        return {
+            settleMs,
+            rect: { viewportRect: reread.viewportRect, documentRect: reread.documentRect },
+        };
+    }
+    return { settleMs, rect: null };
+}
+
 /**
  * Page-context element lookup. Shipped to the browser via adapter.evaluate.
  * Coverage suppressed for the same reason as `settle.js#runInPage` —
@@ -139,9 +182,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 +227,6 @@ function findElementInPage(args) {
         },
     };
 }
-/* v8 ignore stop */
 
 /**
  * Build a failure-shaped ElementCaptureResult that preserves the engine's

package/src/capture/page.js

@@ -33,20 +33,12 @@ async function capturePage(adapter, options = {}) {
     emit(events, 'capture:start', { format, fullPage });
 
     let settleMs = 0;
-    const warnings = [];
+    let warnings = [];
     if (settleOpts) {
         const settleStart = nowMs();
         const report = await waitForStable(adapter, settleOpts === true ? {} : settleOpts);
         settleMs = nowMs() - settleStart;
-        if (report.fonts === 'timeout') {
-            warnings.push('fonts did not settle within maxWait');
-        }
-        if (report.animations === 'timeout') {
-            warnings.push('animations did not settle within maxWait');
-        }
-        if (report.images.failed > 0) {
-            warnings.push(`${report.images.failed} image(s) failed to load`);
-        }
+        warnings = settleWarnings(report);
     }
 
     const metrics = await adapter.getMetrics();
@@ -97,6 +89,35 @@ async function capturePage(adapter, options = {}) {
     return result;
 }
 
+/**
+ * Translate a StabilityReport into non-fatal warning strings.
+ *
+ * @param {import('../types/index.d.ts').StabilityReport} report
+ * @returns {string[]}
+ */
+function settleWarnings(report) {
+    const warnings = [];
+    if (report.fonts === 'timeout') {
+        warnings.push('fonts did not settle within maxWait');
+    }
+    if (report.animations === 'timeout') {
+        warnings.push('animations did not settle within maxWait');
+    }
+    if (report.images.failed > 0) {
+        warnings.push(`${report.images.failed} image(s) failed to load`);
+    }
+    if (report.backgroundImages && report.backgroundImages.failed > 0) {
+        warnings.push(`${report.backgroundImages.failed} background image(s) failed to load`);
+    }
+    if (report.network === 'timeout') {
+        warnings.push('network did not reach idle within maxWait');
+    }
+    if (report.layoutStable === 'timeout') {
+        warnings.push('layout did not stabilize within maxWait');
+    }
+    return warnings;
+}
+
 /**
  * Map the user's desired output format to the format the browser should
  * produce. Returns either the same format (no re-encode) or 'png' (when