@roku-sdk/device-test-client 0.0.0-stage → 2.18.0

package/src/errors.ts

@@ -0,0 +1,773 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import type {
+    ActiveAppInfo,
+    AppUiNode,
+    LogLine,
+    LogPosition,
+    MaskRegion,
+    NodePredicate,
+    SystemDialogNode
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// Unified error model (M10)
+//
+// Every error class in this file extends `DeviceTestError`, which adds:
+//   - `kind`: high-level reporter discriminator (precondition / log / deploy …)
+//   - `code`: stable string identifier for programmatic handling
+//             (logging filters, retry-policy lookup, telemetry)
+//   - `retryable`: hint to deploy/wait retry layers; defaults to `false`
+//                  because most domain errors are deterministic
+//                  (a baseline mismatch will not pass on retry).
+//   - `cause`: standard ES2022 `Error.cause` slot, populated via the
+//              `Error` constructor's `{ cause }` option (Node 20+).
+//
+// Concrete classes are kept (with their existing names, fields, and
+// `name`-property values) so:
+//   - `instanceof XError` checks in tests / call sites keep working
+//     (heavily relied upon — see `__tests__/expect-screenshot.test.ts`,
+//     `__tests__/log-assertions.test.ts`, etc.).
+//   - reporters that key off `error.name` keep working.
+//   - new code can branch on the more ergonomic `kind` / `code` /
+//     `retryable` triple instead of a deepening `instanceof` chain.
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union of error categories. Reporters branch on `kind`
+ * (cheap literal compare); programmatic retry policies branch on
+ * `code` and `retryable`.
+ */
+export type DeviceTestErrorKind = "precondition" | "log" | "deploy" | "device-health" | "dom" | "screenshot" | "client";
+
+/**
+ * Stable, machine-readable error code. New codes MUST be added to
+ * this union so the reporter / retry-policy switch stays exhaustive.
+ */
+export type DeviceTestErrorCode =
+    | "PRECONDITION_MISMATCH"
+    | "PRECONDITION_MISSING_DEVICE_INFO"
+    | "PRECONDITION_NOT_IMPLEMENTED"
+    | "LOG_STREAM_GAP"
+    | "LOG_WAIT_TIMEOUT"
+    | "LOG_UNEXPECTED"
+    | "LOG_SESSION_START"
+    | "LOG_BUFFER_OVERFLOW"
+    | "APP_CRASHED"
+    | "RK_CLIENT"
+    | "BUILD_FAILED"
+    | "DEPLOY_FAILED"
+    | "DEVICE_OFFLINE"
+    | "DEVICE_UNHEALTHY"
+    | "NODE_NOT_FOUND"
+    | "FOCUSED_NODE_MISMATCH"
+    | "WAIT_FOR_NODE_TIMEOUT"
+    | "BASELINE_MISSING"
+    | "BASELINE_RESOLUTION"
+    | "TREE_MISMATCH"
+    | "SCREENSHOT_NOT_STABLE"
+    | "SCREENSHOT_MISMATCH"
+    | "SCREENSHOT_BASELINE_MISSING"
+    | "SCREENSHOT_DIMENSIONS_MISMATCH"
+    | "SCREENSHOT_MASK"
+    | "SCREENSHOT_ALIGN_TOLERANCE";
+
+/**
+ * Shared base for every error type in this package. New code paths
+ * SHOULD prefer branching on `kind` + `code` over `instanceof` chains;
+ * the concrete classes below remain for back-compat with existing
+ * `instanceof` checks and reporters that read `error.name`.
+ *
+ * `cause` flows through the standard ES2022 `Error.cause` channel so
+ * `console.error(err)` and Node's default formatter render the chain
+ * automatically.
+ */
+export class DeviceTestError extends Error {
+    public readonly kind: DeviceTestErrorKind;
+    /**
+     * Stable identifier for programmatic handling. The canonical set
+     * is `DeviceTestErrorCode`; we widen the runtime type to `string`
+     * so back-compat callers (notably `RkClientError` consumers like
+     * `device-resolver-sync.test.ts`) can still surface their domain
+     * codes (e.g. `"RK_DEVICE_IP_UNRESOLVED"`) without us having to
+     * enumerate every legacy code in the union.
+     */
+    public readonly code: DeviceTestErrorCode | string;
+    public readonly retryable: boolean;
+
+    constructor(
+        message: string,
+        opts: {
+            kind: DeviceTestErrorKind;
+            code: DeviceTestErrorCode | string;
+            retryable?: boolean;
+            cause?: unknown;
+        }
+    ) {
+        // Forward `cause` through the standard `Error` ctor option so
+        // `Error.cause` is set canonically (and serialisers like
+        // `util.inspect` render the chain). Skip the option object
+        // entirely when no cause is supplied to avoid setting a
+        // `cause: undefined` slot, which some test matchers print.
+        if (opts.cause === undefined) {
+            super(message);
+        } else {
+            super(message, { cause: opts.cause });
+        }
+        this.name = "DeviceTestError";
+        this.kind = opts.kind;
+        this.code = opts.code;
+        this.retryable = opts.retryable ?? false;
+    }
+}
+
+/**
+ * Thrown by `requirePrecondition` when the device does not satisfy a
+ * test-declared precondition. `itOnDevice` / `describeOnDevice` convert
+ * this into a skip with a clear reason.
+ *
+ * `reason` discriminates: `"mismatch"` (field value failed),
+ * `"missing-device-info"` (cache empty), `"not-implemented"` (field
+ * has no ECP query path; see `PreconditionNotImplementedError`).
+ */
+export class PreconditionNotMetError extends DeviceTestError {
+    /** Precondition field name that failed (e.g. `"firmwareVersion"`). */
+    public readonly field: string;
+    /** Required value or range (e.g. `">=12.0"`). */
+    public readonly expected: string;
+    /** Observed value from `DeviceInfo` (e.g. `"11.5"`). */
+    public readonly actual: string;
+    /** Failure discriminator. See class docstring. */
+    public readonly reason: "mismatch" | "missing-device-info" | "not-implemented";
+
+    constructor(
+        message: string,
+        context: {
+            field: string;
+            expected: string;
+            actual: string;
+            reason?: "mismatch" | "missing-device-info" | "not-implemented";
+        }
+    ) {
+        const reason = context.reason ?? "mismatch";
+        super(message, {
+            kind: "precondition",
+            code:
+                reason === "mismatch"
+                    ? "PRECONDITION_MISMATCH"
+                    : reason === "missing-device-info"
+                      ? "PRECONDITION_MISSING_DEVICE_INFO"
+                      : "PRECONDITION_NOT_IMPLEMENTED"
+        });
+        this.name = "PreconditionNotMetError";
+        this.field = context.field;
+        this.expected = context.expected;
+        this.actual = context.actual;
+        this.reason = reason;
+    }
+}
+
+/**
+ * Thrown when a precondition targets a field with no ECP query path
+ * (currently: `library`). Extends `PreconditionNotMetError` so skip
+ * conversion treats it identically; reporters can still narrow via
+ * `instanceof` if they care about the distinction.
+ */
+export class PreconditionNotImplementedError extends PreconditionNotMetError {
+    /** The unimplemented feature identifier (e.g. `"library-version"`). */
+    public readonly feature: string;
+
+    constructor(message: string, context: { feature: string; field: string; expected: string; actual: string }) {
+        super(message, {
+            field: context.field,
+            expected: context.expected,
+            actual: context.actual,
+            reason: "not-implemented"
+        });
+        this.name = "PreconditionNotImplementedError";
+        this.feature = context.feature;
+    }
+}
+
+/**
+ * Thrown by `waitForLog` / `expectNoLog` when the log stream dropped
+ * and reconnected during the wait. `[gapStart, gapEnd)` is the
+ * half-open seq range of missing lines (decimal `LogPosition` strings).
+ *
+ * Marked `retryable: true` — the gap usually means rk-server briefly
+ * restarted; a re-issued wait against a fresh `since` typically succeeds.
+ */
+export class LogStreamGapError extends DeviceTestError {
+    /** Seq of the first missing line (inclusive), as a decimal string. */
+    public readonly gapStart: LogPosition;
+    /** Seq of the first line observed after reconnect (exclusive), as a decimal string. */
+    public readonly gapEnd: LogPosition;
+
+    constructor(message: string, context: { gapStart?: LogPosition; gapEnd?: LogPosition } = {}) {
+        super(message, { kind: "log", code: "LOG_STREAM_GAP", retryable: true });
+        this.name = "LogStreamGapError";
+        this.gapStart = context.gapStart ?? "";
+        this.gapEnd = context.gapEnd ?? "";
+    }
+}
+
+/**
+ * Thrown by `waitForLog` on timeout. Carries pattern, `since`, timeout,
+ * and the last 20 observed lines for diagnostics.
+ */
+export class WaitForLogTimeoutError extends DeviceTestError {
+    public readonly pattern: string;
+    public readonly since: LogPosition;
+    public readonly timeoutMs: number;
+    public readonly linesChecked: number;
+    public readonly recentLines: LogLine[];
+
+    constructor(
+        message: string,
+        context: {
+            pattern: string;
+            since: LogPosition;
+            timeoutMs: number;
+            linesChecked: number;
+            recentLines: LogLine[];
+        }
+    ) {
+        super(message, { kind: "log", code: "LOG_WAIT_TIMEOUT" });
+        this.name = "WaitForLogTimeoutError";
+        this.pattern = context.pattern;
+        this.since = context.since;
+        this.timeoutMs = context.timeoutMs;
+        this.linesChecked = context.linesChecked;
+        this.recentLines = context.recentLines;
+    }
+}
+
+/**
+ * Thrown by `expectNoLog` when the forbidden pattern matched a line
+ * within the window. `matchedLine` carries the offending text.
+ */
+export class UnexpectedLogError extends DeviceTestError {
+    public readonly pattern: string;
+    public readonly matchedLine: LogLine;
+    public readonly since: LogPosition;
+
+    constructor(message: string, context: { pattern: string; matchedLine: LogLine; since: LogPosition }) {
+        super(message, { kind: "log", code: "LOG_UNEXPECTED" });
+        this.name = "UnexpectedLogError";
+        this.pattern = context.pattern;
+        this.matchedLine = context.matchedLine;
+        this.since = context.since;
+    }
+}
+
+/**
+ * Thrown by `LogSession.ensureStarted` on unrecoverable POST `/logs/start`
+ * errors. 400 "already active" is NOT a failure — the session attaches
+ * to the existing server-side session.
+ */
+export class LogSessionStartError extends DeviceTestError {
+    public readonly serverUrl: string;
+    public readonly statusCode?: number;
+    public readonly detail?: string;
+
+    constructor(message: string, context: { serverUrl: string; statusCode?: number; detail?: string }) {
+        super(message, { kind: "log", code: "LOG_SESSION_START" });
+        this.name = "LogSessionStartError";
+        this.serverUrl = context.serverUrl;
+        this.statusCode = context.statusCode;
+        this.detail = context.detail;
+    }
+}
+
+/**
+ * Thrown when `pos` references a seq below the buffer's minimum
+ * retained seq (eviction dropped the lines the caller asked about).
+ * Distinct from `LogStreamGapError` — overflow is a host-side retention
+ * issue, not a device→host stream loss.
+ */
+export class LogBufferOverflowError extends DeviceTestError {
+    public readonly requested: LogPosition;
+    public readonly minAvailable: LogPosition;
+
+    constructor(message: string, context: { requested: LogPosition; minAvailable: LogPosition }) {
+        super(message, { kind: "log", code: "LOG_BUFFER_OVERFLOW" });
+        this.name = "LogBufferOverflowError";
+        this.requested = context.requested;
+        this.minAvailable = context.minAvailable;
+    }
+}
+
+/**
+ * Thrown when `/query/active-app` shows the app returned to the home
+ * screen mid-test (a proxy for a crash). `activeApp` carries the
+ * observed `ActiveAppInfo` snapshot.
+ */
+export class AppCrashedError extends DeviceTestError {
+    constructor(
+        message: string,
+        /** Active-app identity observed at the time of the crash check. */
+        public readonly activeApp: ActiveAppInfo,
+        /** Optional polling context (predicate, last tree, etc.). */
+        public readonly context?: unknown
+    ) {
+        super(message, { kind: "deploy", code: "APP_CRASHED" });
+        this.name = "AppCrashedError";
+    }
+}
+
+/**
+ * Framework-internal errors (invalid key, missing device IP, etc.).
+ * Wire errors surface as `ToolingError` and propagate as-is.
+ *
+ * `code` is caller-supplied (e.g. `"RK_DEVICE_IP_UNRESOLVED"`,
+ * `"PRECONDITION_NO_DEVICE_INFO"`); when omitted it defaults to the
+ * generic `"RK_CLIENT"`. Reporters should treat any RkClientError
+ * with `kind === "client"` as a client-side framework bug and surface
+ * the more specific `code` for actionable telemetry.
+ */
+export class RkClientError extends DeviceTestError {
+    constructor(
+        message: string,
+        /** Stable error code for programmatic handling. */
+        code?: string
+    ) {
+        super(message, { kind: "client", code: code ?? "RK_CLIENT" });
+        this.name = "RkClientError";
+    }
+}
+
+/**
+ * Thrown by `buildAndDeploy` when the host-side build step fails.
+ * Device is NOT marked unhealthy — a code fix may resolve it without
+ * any device intervention.
+ */
+export class BuildFailedError extends DeviceTestError {
+    constructor(
+        message: string,
+        /** Absolute path to the app directory that failed to build. */
+        public readonly appPath: string,
+        /**
+         * Underlying error, if any — typically a `BuildError` from
+         * tooling. Forwarded into `Error.cause` (the standard ES2022
+         * slot) so `err.cause` still reads as expected for callers
+         * that used the pre-M10 public field.
+         */
+        cause?: unknown
+    ) {
+        super(message, { kind: "deploy", code: "BUILD_FAILED", cause });
+        this.name = "BuildFailedError";
+    }
+}
+
+/**
+ * Thrown by `buildAndDeploy` / `launch` on device-side failure
+ * (sideload rejected, unreachable, readiness timeout, system dialog).
+ * Always paired with `markDeviceUnhealthy(...)` so subsequent tests
+ * fail fast via the per-worker skip-hook.
+ */
+export class DeployFailedError extends DeviceTestError {
+    constructor(
+        message: string,
+        /**
+         * Structured context for post-mortem reporting. Contents vary by
+         * failure mode; all fields are optional so the reporter can
+         * render what is available.
+         */
+        public readonly context: {
+            appPath?: string;
+            deviceIp?: string;
+            /** Formatted output of `runSideloadDiagnostics` when sideload failed. */
+            diagnostics?: string;
+            /** Last tree observed before timeout (readiness failure). */
+            lastTree?: AppUiNode;
+            /** Last active-app observed before timeout (readiness failure). */
+            lastActiveApp?: ActiveAppInfo;
+            /** Dialog node seen on post-deploy tree inspection. */
+            dialog?: SystemDialogNode;
+            /** Which deploy sub-phase produced the failure (launch / readiness / etc.). */
+            phase?: "launch" | "readiness" | "sideload" | "config";
+            /** Channel id that was the launch target, if applicable. */
+            expectedChannelId?: string;
+            /** Specific failure reason tag (e.g. `"never-left-home"`, `"readiness-timeout"`). */
+            reason?: string;
+            /** Underlying error, if any (e.g. ToolingError). */
+            cause?: unknown;
+        } = {}
+    ) {
+        super(message, { kind: "deploy", code: "DEPLOY_FAILED", cause: context.cause });
+        this.name = "DeployFailedError";
+    }
+}
+
+/**
+ * Thrown by `waitForDeviceOnline` when no `/query/device-info` probe
+ * succeeds within the budget. Distinct from `DeployFailedError` so
+ * retry/skip logic can tell "device absent" from "deploy failed".
+ *
+ * Marked `retryable: true` — device-online failures are usually
+ * transient (network flake, just-rebooting device).
+ */
+export class DeviceOfflineError extends DeviceTestError {
+    constructor(
+        message: string,
+        public readonly context: {
+            /** Target device IP the probe was issued against. */
+            deviceIp: string;
+            /** Total time budget the probe was allowed to spend, in ms. */
+            timeoutMs: number;
+            /** Number of probes attempted inside the budget. */
+            attempts: number;
+            /** Last error observed from `/query/device-info`, if any. */
+            lastError?: unknown;
+            /**
+             * Which liveness arm exhausted its budget. `"ecp"` (default)
+             * for `/query/device-info` failures via `waitForDeviceOnline`;
+             * `"installer"` when the ECP arm passed but the sideload
+             * installer (port 80) never accepted a TCP connection.
+             * Reporters and `installDeployGuard` retry policy can branch
+             * on this without parsing the message string.
+             */
+            reason?: "ecp" | "installer";
+            /**
+             * Status reported by the last `tcpProbe` against the
+             * installer port, when `reason === "installer"`.
+             */
+            tcpStatus?: string;
+        }
+    ) {
+        super(message, {
+            kind: "device-health",
+            code: "DEVICE_OFFLINE",
+            retryable: true,
+            cause: context.lastError
+        });
+        this.name = "DeviceOfflineError";
+    }
+}
+
+/**
+ * Thrown by `installDeviceTestHooks`' `beforeEach` when the device was
+ * marked unhealthy by an earlier test. Throws (not `test.skip`) since
+ * Jest can't produce a `skipped` status from `beforeEach` without a
+ * custom reporter; failing fast still avoids cascading failures.
+ */
+export class DeviceUnhealthyError extends DeviceTestError {
+    constructor(
+        message: string,
+        /** The original reason passed to `markDeviceUnhealthy`. */
+        public readonly reason: string
+    ) {
+        super(message, { kind: "device-health", code: "DEVICE_UNHEALTHY" });
+        this.name = "DeviceUnhealthyError";
+    }
+}
+
+// ---------------------------------------------------------------------------
+// DOM-assertion errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by `findNode` / `findFocusedNode` when the predicate matches
+ * nothing. `findAllNodes` does NOT throw — empty results are legitimate.
+ */
+export class NodeNotFoundError extends DeviceTestError {
+    constructor(
+        message: string,
+        /** The predicate that matched nothing. */
+        public readonly predicate: NodePredicate,
+        /** Truncated tree-summary snapshot for diagnostics. */
+        public readonly treeSummary: string
+    ) {
+        super(message, { kind: "dom", code: "NODE_NOT_FOUND" });
+        this.name = "NodeNotFoundError";
+    }
+}
+
+/**
+ * Thrown by `expectFocused` when the focused node does not match the
+ * predicate (a focused node exists, but it's the wrong one).
+ */
+export class FocusedNodeMismatchError extends DeviceTestError {
+    constructor(
+        message: string,
+        /** Predicate the focused node was expected to satisfy. */
+        public readonly expectedPredicate: NodePredicate,
+        /**
+         * Summary of the focused node observed on the tree. Intentionally
+         * a summary (not the full `AppUiNode`) so the error payload is
+         * bounded — the whole tree is already in the enclosing test's
+         * artifacts bundle.
+         */
+        public readonly actualFocusedNode: string
+    ) {
+        super(message, { kind: "dom", code: "FOCUSED_NODE_MISMATCH" });
+        this.name = "FocusedNodeMismatchError";
+    }
+}
+
+/**
+ * Thrown by `waitForNode` on timeout. `lastTree` is the final snapshot
+ * observed (`null` if the first `queryAppUi` rejected before producing one).
+ */
+export class WaitForNodeTimeoutError extends DeviceTestError {
+    public readonly context: {
+        predicate: NodePredicate;
+        timeoutMs: number;
+        lastTree: AppUiNode | null;
+    };
+
+    constructor(message: string, context: { predicate: NodePredicate; timeoutMs: number; lastTree: AppUiNode | null }) {
+        super(message, { kind: "dom", code: "WAIT_FOR_NODE_TIMEOUT" });
+        this.name = "WaitForNodeTimeoutError";
+        this.context = context;
+    }
+}
+
+/**
+ * Thrown by `expectTree(...).toMatchBaseline(path)` when the baseline
+ * file is absent and `UPDATE_BASELINES=1` is unset.
+ */
+export class BaselineMissingError extends DeviceTestError {
+    constructor(
+        message: string,
+        /** Absolute file path that was attempted. */
+        public readonly path: string,
+        /** Resolution subdir (`"hd"` or `"fhd"`) chosen for this run. */
+        public readonly resolution: string,
+        /** Original `DeviceInfo.videoMode` the resolution was derived from, if any. */
+        public readonly videoMode: string | undefined
+    ) {
+        super(message, { kind: "dom", code: "BASELINE_MISSING" });
+        this.name = "BaselineMissingError";
+    }
+}
+
+/**
+ * Thrown by `resolveResolution()` when the `hd`/`fhd` subdir cannot be
+ * determined. When the active client reports an unsupported videoMode
+ * we fail rather than fall back to the env override (a recognised
+ * videoMode is authoritative; mismatch means operator config is wrong).
+ *
+ * `reason`: `"unsupported-videoMode"`, `"no-active-client-and-no-env"`,
+ * or `"invalid-env-value"`.
+ */
+export class BaselineResolutionError extends DeviceTestError {
+    constructor(
+        message: string,
+        public readonly context: {
+            videoMode?: string;
+            reason: "unsupported-videoMode" | "no-active-client-and-no-env" | "invalid-env-value";
+        }
+    ) {
+        super(message, { kind: "dom", code: "BASELINE_RESOLUTION" });
+        this.name = "BaselineResolutionError";
+    }
+}
+
+/**
+ * Thrown by `expectTree(...).toMatchBaseline(path)` on tree mismatch.
+ * `firstDiff` is a JSONPath-ish key; `expected/actualSnippet` are
+ * truncated for bounded payload size.
+ */
+export class TreeMismatchError extends DeviceTestError {
+    constructor(
+        message: string,
+        public readonly context: {
+            /** Absolute baseline path on disk. */
+            baselinePath: string;
+            /** JSONPath of the first differing key (e.g. `$.children[0].attrs.opacity`). */
+            firstDiff: string;
+            /** Truncated serialization of the baseline value at `firstDiff`. */
+            expectedSnippet: string;
+            /** Truncated serialization of the actual value at `firstDiff`. */
+            actualSnippet: string;
+        }
+    ) {
+        super(message, { kind: "dom", code: "TREE_MISMATCH" });
+        this.name = "TreeMismatchError";
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Screenshot-assertion errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by `captureStableScreenshot` on convergence timeout.
+ * `lastPng` is excluded from `toJSON()` to keep `JSON.stringify(err)`
+ * small; reporters that need the bytes read it directly.
+ * `lastDiffCount` + `firstDiffPoint` + `maskedRegions` together
+ * disambiguate "wrong mask" from "app still animating".
+ */
+export class ScreenshotNotStableError extends DeviceTestError {
+    public readonly timeoutMs: number;
+    public readonly iterations: number;
+    public readonly lastDiffCount: number;
+    public readonly maskedRegions: MaskRegion[];
+    public readonly firstDiffPoint?: { x: number; y: number };
+    public readonly lastPng?: Buffer;
+
+    constructor(
+        message: string,
+        context: {
+            timeoutMs: number;
+            iterations: number;
+            lastDiffCount: number;
+            maskedRegions: MaskRegion[];
+            firstDiffPoint?: { x: number; y: number };
+            lastPng?: Buffer;
+        }
+    ) {
+        super(message, { kind: "screenshot", code: "SCREENSHOT_NOT_STABLE" });
+        this.name = "ScreenshotNotStableError";
+        this.timeoutMs = context.timeoutMs;
+        this.iterations = context.iterations;
+        this.lastDiffCount = context.lastDiffCount;
+        this.maskedRegions = context.maskedRegions;
+        this.firstDiffPoint = context.firstDiffPoint;
+        this.lastPng = context.lastPng;
+    }
+
+    /** JSON projection that OMITS `lastPng` to keep payloads small. */
+    toJSON(): Record<string, unknown> {
+        return {
+            name: this.name,
+            message: this.message,
+            timeoutMs: this.timeoutMs,
+            iterations: this.iterations,
+            lastDiffCount: this.lastDiffCount,
+            maskedRegions: this.maskedRegions,
+            firstDiffPoint: this.firstDiffPoint
+        };
+    }
+}
+
+interface ScreenshotMismatchContext {
+    baselinePath: string;
+    resolution: "hd" | "fhd";
+    actual: { w: number; h: number };
+    mismatchedPixels: number;
+    totalPixels: number;
+    ratio: number;
+    threshold: number;
+    diffPath: string;
+    /**
+     * Translation applied to the capture before scoring, when
+     * `alignTolerance` was set and the untranslated comparison failed.
+     * Absent when no alignment search ran. A non-zero value that still
+     * failed means the surface moved AND changed.
+     */
+    alignment?: { dx: number; dy: number };
+}
+
+/**
+ * Thrown when the mismatched-pixel ratio (outside masks) exceeds the
+ * caller's `threshold`. The diff PNG is always written to disk first;
+ * `diffPath` is its absolute location.
+ */
+export class ScreenshotMismatchError extends DeviceTestError {
+    public readonly context: ScreenshotMismatchContext;
+
+    constructor(message: string, context: ScreenshotMismatchContext) {
+        super(message, { kind: "screenshot", code: "SCREENSHOT_MISMATCH" });
+        this.name = "ScreenshotMismatchError";
+        this.context = context;
+    }
+}
+
+/**
+ * Thrown when the baseline PNG is absent and `UPDATE_BASELINES=1` is
+ * unset. Distinct from `BaselineMissingError` (DOM baselines).
+ */
+export class ScreenshotBaselineMissingError extends DeviceTestError {
+    constructor(
+        message: string,
+        public readonly baselinePath: string,
+        public readonly resolution: "hd" | "fhd"
+    ) {
+        super(message, { kind: "screenshot", code: "SCREENSHOT_BASELINE_MISSING" });
+        this.name = "ScreenshotBaselineMissingError";
+    }
+}
+
+/**
+ * Thrown when baseline and capture have different dimensions. We
+ * refuse to run `pixelmatch` at mismatched sizes (every pixel would
+ * miss; diff would be useless) and write no diff file.
+ */
+export class ScreenshotDimensionsMismatchError extends DeviceTestError {
+    public readonly context: {
+        baselinePath: string;
+        resolution: "hd" | "fhd";
+        baseline: { w: number; h: number };
+        actual: { w: number; h: number };
+    };
+
+    constructor(
+        message: string,
+        context: {
+            baselinePath: string;
+            resolution: "hd" | "fhd";
+            baseline: { w: number; h: number };
+            actual: { w: number; h: number };
+        }
+    ) {
+        super(message, { kind: "screenshot", code: "SCREENSHOT_DIMENSIONS_MISMATCH" });
+        this.name = "ScreenshotDimensionsMismatchError";
+        this.context = context;
+    }
+}
+
+/**
+ * Thrown by `validateMasks` for `zero-area` or `out-of-bounds` regions.
+ * Partial overlap is NOT an error — such regions are clamped, letting
+ * an FHD mask survive on an HD device.
+ */
+export class ScreenshotMaskError extends DeviceTestError {
+    public readonly context: {
+        region: MaskRegion;
+        canvas: { w: number; h: number };
+        reason: "out-of-bounds" | "zero-area";
+    };
+
+    constructor(
+        message: string,
+        context: {
+            region: MaskRegion;
+            canvas: { w: number; h: number };
+            reason: "out-of-bounds" | "zero-area";
+        }
+    ) {
+        super(message, { kind: "screenshot", code: "SCREENSHOT_MASK" });
+        this.name = "ScreenshotMaskError";
+        this.context = context;
+    }
+}
+
+/**
+ * Thrown by `validateAlignTolerance` for a non-integer, negative, or
+ * over-cap `alignTolerance` axis. Always a caller bug, so it is loud
+ * rather than clamped.
+ */
+export class ScreenshotAlignToleranceError extends DeviceTestError {
+    public readonly context: {
+        axis: "x" | "y";
+        value: number;
+        max: number;
+        reason: "not-an-integer" | "negative" | "over-cap";
+    };
+
+    constructor(
+        message: string,
+        context: {
+            axis: "x" | "y";
+            value: number;
+            max: number;
+            reason: "not-an-integer" | "negative" | "over-cap";
+        }
+    ) {
+        super(message, { kind: "screenshot", code: "SCREENSHOT_ALIGN_TOLERANCE" });
+        this.name = "ScreenshotAlignToleranceError";
+        this.context = context;
+    }
+}