snapdrift 0.8.2 → 0.10.0

package/lib/snap-provider.mjs

@@ -10,7 +10,15 @@ import path from 'node:path';
 
 import { makeMarkdown, buildReportCommentBody } from '@snapdrift/adapter-report-md';
 import { loadSnapdriftConfig, runBaselineCapture } from '@snapdrift/adapter-fs';
-import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_PRESETS, viewportHash } from '@snapdrift/manifest';
+import {
+  selectConfiguredRoutes,
+  splitCommaList,
+  determineDriftStatus,
+  VIEWPORT_PRESETS,
+  viewportHash,
+  assertUniqueRouteIdFilenames,
+  sanitizeRouteId
+} from '@snapdrift/manifest';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -23,16 +31,22 @@ import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_
 /** @typedef {import('../types/visual-diff-types').ProviderBaselineData} BaselineData */
 /** @typedef {import('../types/visual-diff-types').SnapConfig} SnapConfig */
 /** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
+/** @typedef {import('../types/visual-diff-types').ComparisonPolicy} ComparisonPolicy */
+/** @typedef {import('../types/visual-diff-types').ComparisonMetadata} ComparisonMetadata */
 /** @typedef {import('../types/visual-diff-types').JsonObject} JsonObject */
+/** @typedef {{ deadline: number, label: string }} OperationDeadline */
 
 const DEFAULT_API_URL = 'https://snap.i2dev.com';
 const MAX_RETRIES = 3;
 const INITIAL_RETRY_DELAY_MS = 1000;
 const RETRY_MULTIPLIER = 2;
-const MAX_RETRY_TOTAL_MS = 30000;
+const RETRY_DELAY_CAP_MS = 30000;
+const JSON_REQUEST_TIMEOUT_MS = 30 * 1000;
+const BINARY_REQUEST_TIMEOUT_MS = 120 * 1000;
 const POLL_INTERVAL_MS = 2000;
-const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
+const MAX_OPERATION_DURATION_MS = 10 * 60 * 1000;
 const MAX_STABLE_INCOMPLETE_POLLS = 30;
+const MAX_COMPARISON_PIXELS = 32 * 1024 * 1024;
 const BASELINE_RUN_SUCCESS_STATUS = 'new';
 const BASELINE_CAPTURE_SUCCESS_STATUS = 'new';
 const TERMINAL_CAPTURE_STATUSES = new Set(['new', 'diffed', 'error']);
@@ -43,19 +57,201 @@ const TERMINAL_CAPTURE_STATUSES = new Set(['new', 'diffed', 'error']);
 // client must stop polling on it just like pass/fail/error.
 const TERMINAL_RUN_STATUSES = new Set(['pass', 'fail', 'error', 'new']);
 
+/** @param {number} milliseconds @returns {string} */
+function formatDuration(milliseconds) {
+  const seconds = Math.round(milliseconds / 1000);
+  if (seconds % 60 === 0) return `${seconds / 60} minutes`;
+  return `${seconds} seconds`;
+}
+
+const OPERATION_LIMIT_TEXT = formatDuration(MAX_OPERATION_DURATION_MS);
+
+/** @returns {number} A monotonic timestamp in milliseconds. */
+function monotonicNow() {
+  return typeof globalThis.performance?.now === 'function' ? globalThis.performance.now() : Date.now();
+}
+
+/**
+ * Run an asynchronous operation with a timer that also settles when the
+ * underlying promise ignores cancellation. The promise remains observed after
+ * the timeout, so a late rejection cannot become an unhandled rejection.
+ *
+ * @template T
+ * @param {() => Promise<T> | T} task
+ * @param {number} timeoutMs
+ * @param {() => void} onTimeout
+ * @param {() => Error} timeoutError
+ * @returns {Promise<T>}
+ */
+function runWithTimeout(task, timeoutMs, onTimeout, timeoutError) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let taskPromise;
+    try {
+      taskPromise = Promise.resolve(task());
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    const timer = setTimeout(
+      () => {
+        if (settled) return;
+        settled = true;
+        try {
+          onTimeout();
+        } catch {
+          // Abort/cancel is best effort; the timeout still settles the caller.
+        }
+        reject(timeoutError());
+      },
+      Math.max(0, timeoutMs)
+    );
+
+    taskPromise.then(
+      (value) => {
+        if (settled) {
+          if (value && typeof value === 'object') cancelResponseBody(value);
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+/** @param {any} response */
+function cancelResponseBody(response) {
+  const body = response && typeof response === 'object' ? response.body : undefined;
+  if (body && typeof body.cancel === 'function') {
+    Promise.resolve(body.cancel()).catch(() => {});
+  }
+}
+
 /** @param {string} detail @returns {Error} */
 function completeBaselineError(detail) {
   return new Error(`Cannot publish a complete Snap baseline: ${detail}`);
 }
 
+/** @param {string} detail @returns {Error} */
+function hostedDiffError(detail) {
+  return new Error(`Cannot compare a Snap visual diff: ${detail}`);
+}
+
+/** @param {unknown} value @returns {value is ComparisonPolicy} */
+function isComparisonPolicy(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const policy = /** @type {Record<string, any>} */ (value);
+  return policy.version === 1 && typeof policy.threshold === 'number' && Number.isFinite(policy.threshold) && policy.threshold >= 0 && policy.threshold <= 1;
+}
+
+/** @param {unknown} value @returns {value is ComparisonMetadata} */
+function isComparisonMetadata(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const comparison = /** @type {Record<string, any>} */ (value);
+  const dimensions = [comparison.baseline, comparison.current, comparison.canvas];
+  if (
+    dimensions.some(
+      (dimension) =>
+        !dimension ||
+        typeof dimension !== 'object' ||
+        !Number.isInteger(dimension.width) ||
+        dimension.width < 0 ||
+        !Number.isInteger(dimension.height) ||
+        dimension.height < 0
+    )
+  ) {
+    return false;
+  }
+  const [baseline, current, canvas] = dimensions;
+  return (
+    typeof comparison.dimensionsChanged === 'boolean' &&
+    comparison.dimensionsChanged === (baseline.width !== current.width || baseline.height !== current.height) &&
+    canvas.width === Math.max(baseline.width, current.width) &&
+    canvas.height === Math.max(baseline.height, current.height) &&
+    Number.isInteger(comparison.totalPixels) &&
+    comparison.totalPixels >= 0 &&
+    comparison.totalPixels <= canvas.width * canvas.height &&
+    canvas.width * canvas.height <= MAX_COMPARISON_PIXELS
+  );
+}
+
+/**
+ * @param {any} capture
+ * @param {ComparisonMetadata} comparison
+ * @param {number} expectedThreshold
+ * @returns {boolean}
+ */
+function hasCompleteComparisonResult(capture, comparison, expectedThreshold) {
+  if (
+    !Number.isFinite(capture.diffPct) ||
+    capture.diffPct < 0 ||
+    capture.diffPct > 1 ||
+    !Number.isInteger(capture.diffPixels) ||
+    capture.diffPixels < 0 ||
+    capture.diffPixels > comparison.totalPixels ||
+    typeof capture.diffObjectKey !== 'string' ||
+    capture.diffObjectKey.trim().length === 0 ||
+    capture.thresholdUsed !== expectedThreshold
+  ) {
+    return false;
+  }
+
+  const expectedRatio = comparison.totalPixels === 0 ? 0 : capture.diffPixels / comparison.totalPixels;
+  return Math.abs(capture.diffPct - expectedRatio) <= 1e-12;
+}
+
+/** @param {any} capture @returns {ComparisonMetadata | undefined} */
+function comparisonFromCapture(capture) {
+  const candidate =
+    capture?.comparison ??
+    (() => {
+      if (typeof capture?.comparisonJson !== 'string') return undefined;
+      try {
+        return JSON.parse(capture.comparisonJson);
+      } catch {
+        return undefined;
+      }
+    })();
+  return isComparisonMetadata(candidate) ? candidate : undefined;
+}
+
+/** @param {unknown} actual @param {ComparisonPolicy} expected @param {string} context */
+function assertComparisonPolicyAcknowledged(actual, expected, context) {
+  if (!isComparisonPolicy(actual) || actual.threshold !== expected.threshold) {
+    throw new SnapUpgradeRequiredError(
+      `${context} did not acknowledge comparisonPolicy v1 with threshold ${expected.threshold}. ` +
+        'Upgrade the Snap server before enabling unequal-dimension comparisons.'
+    );
+  }
+}
+
+/**
+ * Updated SnapDrift clients explicitly opt into the union-canvas comparison.
+ * Keep the config override for callers that want the policy visible in their
+ * config, but derive it from the existing diff threshold by default so a
+ * normal v1 client does not need to repeat that value.
+ *
+ * @param {VisualRegressionConfig} config
+ * @returns {ComparisonPolicy}
+ */
+function resolveComparisonPolicy(config) {
+  return config.diff.comparisonPolicy ? { ...config.diff.comparisonPolicy } : { version: 1, threshold: config.diff.threshold };
+}
+
 /**
  * @param {import('../types/visual-diff-types').VisualViewport} viewport
  * @returns {{ width: number, height: number, deviceScaleFactor?: number, isMobile?: boolean, hasTouch?: boolean }}
  */
 function resolveViewportDescriptor(viewport) {
-  return typeof viewport === 'string'
-    ? (VIEWPORT_PRESETS[viewport] ?? { width: 1280, height: 720 })
-    : viewport;
+  return typeof viewport === 'string' ? (VIEWPORT_PRESETS[viewport] ?? { width: 1280, height: 720 }) : viewport;
 }
 
 /** @param {VisualRegressionConfig['routes'][number]} route */
@@ -67,43 +263,140 @@ function expectedCaptureIdentity(route) {
   };
 }
 
-/** @param {unknown} value @param {string} context @returns {string} */
-function normalizeViewportDescriptor(value, context) {
+/**
+ * @param {unknown} value
+ * @param {string} context
+ * @param {(detail: string) => Error} errorFactory
+ * @returns {string}
+ */
+function normalizeViewportDescriptor(value, context, errorFactory) {
   let descriptor;
   try {
     descriptor = typeof value === 'string' ? JSON.parse(value) : value;
   } catch {
-    throw completeBaselineError(`${context} has malformed viewportDescriptorJson.`);
+    throw errorFactory(`${context} has malformed viewportDescriptorJson.`);
   }
-  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor) ||
-      !Number.isFinite(descriptor.width) || !Number.isFinite(descriptor.height)) {
-    throw completeBaselineError(`${context} has an invalid viewport descriptor.`);
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor) || !Number.isFinite(descriptor.width) || !Number.isFinite(descriptor.height)) {
+    throw errorFactory(`${context} has an invalid viewport descriptor.`);
   }
-  return JSON.stringify(Object.fromEntries(
-    Object.entries(descriptor).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
-  ));
+  return JSON.stringify(Object.fromEntries(Object.entries(descriptor).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))));
 }
 
-/** @param {{ routeId?: unknown, viewportDescriptorJson?: unknown }} capture @param {string} context */
-function captureIdentityKey(capture, context) {
+/**
+ * @param {{ routeId?: unknown, viewportDescriptorJson?: unknown }} capture
+ * @param {string} context
+ * @param {(detail: string) => Error} errorFactory
+ */
+function captureIdentityKey(capture, context, errorFactory) {
   if (typeof capture.routeId !== 'string' || !capture.routeId) {
-    throw completeBaselineError(`${context} has no routeId.`);
+    throw errorFactory(`${context} has no routeId.`);
   }
-  return `${capture.routeId}\u0000${normalizeViewportDescriptor(capture.viewportDescriptorJson, context)}`;
+  return `${capture.routeId}\u0000${normalizeViewportDescriptor(capture.viewportDescriptorJson, context, errorFactory)}`;
 }
 
-/** @param {unknown} value @param {string} field @returns {Set<string>} */
-function uniqueRouteIdSet(value, field) {
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @param {(detail: string) => Error} errorFactory
+ * @returns {Set<string>}
+ */
+function uniqueRouteIdSet(value, field, errorFactory) {
   if (!Array.isArray(value) || value.some((id) => typeof id !== 'string' || !id)) {
-    throw completeBaselineError(`results metadata has no valid ${field}; capture again with SnapDrift 0.8.2 or newer.`);
+    throw errorFactory(`results metadata has no valid ${field}; capture again with SnapDrift 0.8.2 or newer.`);
   }
   const ids = new Set(value);
   if (ids.size !== value.length) {
-    throw completeBaselineError(`results metadata ${field} contains duplicate route ids.`);
+    throw errorFactory(`results metadata ${field} contains duplicate route ids.`);
   }
   return ids;
 }
 
+/**
+ * Validate the immutable capture plan written by SnapProvider.capture().
+ *
+ * Diff runs are allowed to be scoped, so this deliberately validates the
+ * expected set against selectedRouteIds rather than requiring every configured
+ * route as hosted baseline publication does.
+ *
+ * @param {JsonObject} metadata
+ * @param {string} projectId
+ * @returns {{
+ *   runId: string,
+ *   selectedRouteIds: string[],
+ *   expectedCaptures: Array<{ routeId: string, routePath: string, viewportDescriptorJson: string, viewport: import('../types/visual-diff-types').VisualViewport }>,
+ *   expectedByIdentity: Map<string, { routeId: string, routePath: string, viewportDescriptorJson: string, viewport: import('../types/visual-diff-types').VisualViewport }>,
+ *   expectedByRouteId: Map<string, { routeId: string, routePath: string, viewportDescriptorJson: string, viewport: import('../types/visual-diff-types').VisualViewport }>
+ * }}
+ */
+function validateHostedDiffMetadata(metadata, projectId) {
+  if (!metadata || typeof metadata !== 'object') {
+    throw hostedDiffError('capture results metadata is not an object; capture again with SnapDrift 0.8.2 or newer.');
+  }
+  if (typeof metadata.runId !== 'string' || !metadata.runId.trim()) {
+    throw hostedDiffError('capture results metadata has no run id; capture again with SnapDrift 0.8.2 or newer.');
+  }
+  if (metadata.projectId !== projectId) {
+    throw hostedDiffError(`capture results belong to project "${metadata.projectId || 'unknown'}", not "${projectId}".`);
+  }
+
+  if (!Array.isArray(metadata.expectedCaptures) || metadata.expectedCaptures.length === 0) {
+    throw hostedDiffError('capture results have no expected capture identities; recapture with SnapDrift 0.8.2 or newer.');
+  }
+  if (metadata.purpose !== 'diff') {
+    throw hostedDiffError(`capture results have purpose "${metadata.purpose || 'unknown'}", not "diff"; ` + 'recapture with SnapDrift 0.8.2 or newer.');
+  }
+  const selected = uniqueRouteIdSet(metadata.selectedRouteIds, 'selectedRouteIds', hostedDiffError);
+  if (selected.size === 0) {
+    throw hostedDiffError('capture results selected no routes.');
+  }
+  if (metadata.expectedCaptures.length !== selected.size) {
+    throw hostedDiffError(`capture results describe ${metadata.expectedCaptures.length} expected capture(s) for ${selected.size} selected route(s).`);
+  }
+
+  const expectedRouteIds = new Set();
+  const expectedByIdentity = new Map();
+  const expectedByRouteId = new Map();
+  for (const [index, expected] of metadata.expectedCaptures.entries()) {
+    if (
+      !expected ||
+      typeof expected !== 'object' ||
+      typeof expected.routeId !== 'string' ||
+      !expected.routeId ||
+      typeof expected.routePath !== 'string' ||
+      !expected.routePath ||
+      !selected.has(expected.routeId)
+    ) {
+      throw hostedDiffError(`expected capture metadata at index ${index} is invalid or not selected.`);
+    }
+    if (expectedRouteIds.has(expected.routeId)) {
+      throw hostedDiffError(`expected capture metadata contains duplicate route "${expected.routeId}".`);
+    }
+    expectedRouteIds.add(expected.routeId);
+    const viewportDescriptorJson = normalizeViewportDescriptor(expected.viewportDescriptorJson, `expected capture "${expected.routeId}"`, hostedDiffError);
+    const viewportDescriptor = JSON.parse(viewportDescriptorJson);
+    const expectedCapture = {
+      routeId: expected.routeId,
+      routePath: expected.routePath,
+      viewportDescriptorJson,
+      viewport: { width: viewportDescriptor.width, height: viewportDescriptor.height }
+    };
+    const identity = captureIdentityKey(expectedCapture, `expected capture "${expected.routeId}"`, hostedDiffError);
+    if (expectedByIdentity.has(identity)) {
+      throw hostedDiffError(`expected capture metadata contains duplicate route/viewport identity for "${expected.routeId}".`);
+    }
+    expectedByIdentity.set(identity, expectedCapture);
+    expectedByRouteId.set(expected.routeId, expectedCapture);
+  }
+
+  return {
+    runId: metadata.runId,
+    selectedRouteIds: [...selected],
+    expectedCaptures: [...expectedByIdentity.values()],
+    expectedByIdentity,
+    expectedByRouteId
+  };
+}
+
 /** @param {string[]} configuredRouteIds @param {string[]} selectedRouteIds */
 function assertCompleteHostedBaselineSelection(configuredRouteIds, selectedRouteIds) {
   const selected = new Set(selectedRouteIds);
@@ -111,9 +404,9 @@ function assertCompleteHostedBaselineSelection(configuredRouteIds, selectedRoute
   if (missing.length === 0 && selected.size === configuredRouteIds.length) return;
   throw new Error(
     `Hosted Snap baseline publication requires all ${configuredRouteIds.length} configured route(s), ` +
-    `but only ${selected.size} were selected. Remove route-ids/--routes scoping ` +
-    `(missing: ${missing.join(', ') || 'unknown'}). Scoped runs remain supported for PR diffs ` +
-    'and local-provider baselines.'
+      `but only ${selected.size} were selected. Remove route-ids/--routes scoping ` +
+      `(missing: ${missing.join(', ') || 'unknown'}). Scoped runs remain supported for PR diffs ` +
+      'and local-provider baselines.'
   );
 }
 
@@ -129,27 +422,18 @@ function validateCompleteBaselineRun(metadata, run, projectId) {
   if (metadata.purpose !== 'baseline') {
     throw completeBaselineError('source results were not recorded as a baseline capture.');
   }
-  if (typeof metadata.refBranch !== 'string' || !metadata.refBranch ||
-      typeof metadata.refSha !== 'string' || !metadata.refSha) {
+  if (typeof metadata.refBranch !== 'string' || !metadata.refBranch || typeof metadata.refSha !== 'string' || !metadata.refSha) {
     throw completeBaselineError('source results have no resolved ref; capture again with SnapDrift 0.8.2 or newer.');
   }
-  if (
-    typeof metadata.publicationSequence !== 'number' ||
-    !Number.isSafeInteger(metadata.publicationSequence) ||
-    metadata.publicationSequence <= 0
-  ) {
-    throw completeBaselineError(
-      'source results have no valid publication sequence; capture again with SnapDrift 0.8.2 or newer.'
-    );
+  if (typeof metadata.publicationSequence !== 'number' || !Number.isSafeInteger(metadata.publicationSequence) || metadata.publicationSequence <= 0) {
+    throw completeBaselineError('source results have no valid publication sequence; capture again with SnapDrift 0.8.2 or newer.');
   }
   if (typeof metadata.publicationWorkflowRef !== 'string' || !metadata.publicationWorkflowRef.trim()) {
-    throw completeBaselineError(
-      'source results have no publication workflow identity; capture again with SnapDrift 0.8.2 or newer.'
-    );
+    throw completeBaselineError('source results have no publication workflow identity; capture again with SnapDrift 0.8.2 or newer.');
   }
 
-  const configured = uniqueRouteIdSet(metadata.configuredRouteIds, 'configuredRouteIds');
-  const selected = uniqueRouteIdSet(metadata.selectedRouteIds, 'selectedRouteIds');
+  const configured = uniqueRouteIdSet(metadata.configuredRouteIds, 'configuredRouteIds', completeBaselineError);
+  const selected = uniqueRouteIdSet(metadata.selectedRouteIds, 'selectedRouteIds', completeBaselineError);
   assertCompleteHostedBaselineSelection([...configured], [...selected]);
   if (!Array.isArray(metadata.expectedCaptures) || metadata.expectedCaptures.length !== configured.size) {
     throw completeBaselineError(`expected capture metadata does not match ${configured.size} configured route(s).`);
@@ -158,15 +442,17 @@ function validateCompleteBaselineRun(metadata, run, projectId) {
   const expectedRoutes = new Set();
   const expectedByIdentity = new Map();
   for (const expected of metadata.expectedCaptures) {
-    if (!expected || typeof expected !== 'object' || typeof expected.routePath !== 'string' ||
-        !configured.has(expected.routeId) || expectedRoutes.has(expected.routeId)) {
+    if (
+      !expected ||
+      typeof expected !== 'object' ||
+      typeof expected.routePath !== 'string' ||
+      !configured.has(expected.routeId) ||
+      expectedRoutes.has(expected.routeId)
+    ) {
       throw completeBaselineError(`expected capture metadata has duplicate or extra route "${expected?.routeId || 'unknown'}".`);
     }
     expectedRoutes.add(expected.routeId);
-    expectedByIdentity.set(
-      captureIdentityKey(expected, `expected capture "${expected.routeId}"`),
-      expected
-    );
+    expectedByIdentity.set(captureIdentityKey(expected, `expected capture "${expected.routeId}"`, completeBaselineError), expected);
   }
 
   if (!Array.isArray(run.captures)) throw completeBaselineError('source run has no captures array.');
@@ -179,7 +465,7 @@ function validateCompleteBaselineRun(metadata, run, projectId) {
     if (!capture || typeof capture !== 'object') {
       throw completeBaselineError('source run contains a malformed capture.');
     }
-    const identity = captureIdentityKey(capture, `source capture "${capture.routeId || capture.id || 'unknown'}"`);
+    const identity = captureIdentityKey(capture, `source capture "${capture.routeId || capture.id || 'unknown'}"`, completeBaselineError);
     if (seen.has(identity)) {
       throw completeBaselineError(`duplicate source route/viewport identity for "${capture.routeId}".`);
     }
@@ -206,8 +492,8 @@ function validateCompleteBaselineRun(metadata, run, projectId) {
   });
 
   return routes.sort((left, right) => {
-    const leftKey = captureIdentityKey(left, `route "${left.routeId}"`);
-    const rightKey = captureIdentityKey(right, `route "${right.routeId}"`);
+    const leftKey = captureIdentityKey(left, `route "${left.routeId}"`, completeBaselineError);
+    const rightKey = captureIdentityKey(right, `route "${right.routeId}"`, completeBaselineError);
     return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
   });
 }
@@ -283,11 +569,7 @@ function gitOutput(args) {
 export function resolveGitRef() {
   const branch = gitOutput(['rev-parse', '--abbrev-ref', 'HEAD']);
   return {
-    refBranch:
-      process.env.GITHUB_REF_NAME ||
-      process.env.GITHUB_HEAD_REF ||
-      (branch && branch !== 'HEAD' ? branch : undefined) ||
-      'main',
+    refBranch: process.env.GITHUB_REF_NAME || process.env.GITHUB_HEAD_REF || (branch && branch !== 'HEAD' ? branch : undefined) || 'main',
     refSha: process.env.GITHUB_SHA || gitOutput(['rev-parse', 'HEAD']) || 'unknown'
   };
 }
@@ -296,8 +578,7 @@ function resolveHostedBaselinePublicationRef() {
   const gitRef = resolveGitRef();
   const refBranch = process.env.GITHUB_REF_NAME || gitRef.refBranch;
   const refSha = process.env.GITHUB_SHA || gitRef.refSha;
-  const publicationWorkflowRef =
-    process.env.SNAPDRIFT_PUBLICATION_WORKFLOW_REF || process.env.GITHUB_WORKFLOW_REF;
+  const publicationWorkflowRef = process.env.SNAPDRIFT_PUBLICATION_WORKFLOW_REF || process.env.GITHUB_WORKFLOW_REF;
   const sequenceValue = process.env.SNAPDRIFT_PUBLICATION_SEQUENCE || process.env.GITHUB_RUN_NUMBER;
   const publicationSequence = Number(sequenceValue);
   if (
@@ -310,10 +591,10 @@ function resolveHostedBaselinePublicationRef() {
   ) {
     throw new Error(
       'Hosted Snap baseline publication requires a branch, a resolved 40-character commit SHA, ' +
-      'a publication workflow identity, and a positive publication sequence. GitHub Actions ' +
-      'provides these as GITHUB_REF_NAME/GITHUB_SHA/GITHUB_WORKFLOW_REF/GITHUB_RUN_NUMBER; ' +
-      'other CI systems may use SNAPDRIFT_PUBLICATION_WORKFLOW_REF and ' +
-      'SNAPDRIFT_PUBLICATION_SEQUENCE.'
+        'a publication workflow identity, and a positive publication sequence. GitHub Actions ' +
+        'provides these as GITHUB_REF_NAME/GITHUB_SHA/GITHUB_WORKFLOW_REF/GITHUB_RUN_NUMBER; ' +
+        'other CI systems may use SNAPDRIFT_PUBLICATION_WORKFLOW_REF and ' +
+        'SNAPDRIFT_PUBLICATION_SEQUENCE.'
     );
   }
   return { refBranch, refSha, publicationWorkflowRef, publicationSequence };
@@ -336,23 +617,6 @@ function getPackageVersion() {
 const TAR_BLOCK_SIZE = 512;
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
-/**
- * Strips characters that could cause path traversal or produce invalid
- * filenames when a route id is used as a screenshot filename. Mirrors the
- * sanitisation applied by `@snapdrift/adapter-fs` during local capture so
- * imported baselines land on the same filenames a local capture would produce.
- *
- * @param {string} id
- * @returns {string}
- */
-function sanitizeRouteId(id) {
-  return id
-    .replace(/\.\./g, '_')
-    .replace(/[/\\]/g, '_')
-    // eslint-disable-next-line no-control-regex
-    .replace(/[\x00-\x1f\x7f]/g, '');
-}
-
 /**
  * Parse a plain ustar-style tar archive (512-byte headers, bodies padded to
  * 512-byte blocks, terminated by zero blocks) into a map of entry name →
@@ -457,22 +721,6 @@ function resolveExportEngine(captureProfile) {
   return { name: 'snap-hosted', version: 'unknown' };
 }
 
-/**
- * Extract a human-readable detail string from a Snap API error response.
- *
- * @param {{ text: () => Promise<string> }} response
- * @returns {Promise<string>}
- */
-async function readErrorDetail(response) {
-  const errorBody = await response.text().catch(() => '');
-  try {
-    const parsed = JSON.parse(errorBody);
-    return parsed.error || parsed.message || '';
-  } catch {
-    return '';
-  }
-}
-
 /**
  * SnapProvider — VisualProvider that delegates capture + diff to Snap's
  * hosted /v1/visual/* API.
@@ -484,8 +732,10 @@ export class SnapProvider {
   #snapConfig;
   /** @type {typeof globalThis.fetch} */
   #fetchFn;
-  /** @type {(ms: number) => Promise<void>} */
+  /** @type {(ms: number, signal?: AbortSignal) => Promise<void>} */
   #sleepFn;
+  /** @type {() => number} */
+  #nowFn;
   /** @type {(options?: { configPath?: string, routeIds?: Iterable<string>, outDir?: string }) => Promise<CaptureResult>} */
   #localCaptureFn;
   /** @type {string} */
@@ -499,14 +749,30 @@ export class SnapProvider {
    * @param {SnapConfig} snapConfig — validated snap section from config
    * @param {{
    *   fetchFn?: typeof globalThis.fetch,
-   *   sleepFn?: (ms: number) => Promise<void>,
+   *   sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>,
+   *   nowFn?: () => number,
    *   localCaptureFn?: (options?: { configPath?: string, routeIds?: Iterable<string>, outDir?: string }) => Promise<CaptureResult>
    * }} [options]
    */
   constructor(snapConfig, options = {}) {
     this.#snapConfig = snapConfig;
     this.#fetchFn = options.fetchFn ?? globalThis.fetch;
-    this.#sleepFn = options.sleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.#sleepFn =
+      options.sleepFn ??
+      ((ms, signal) =>
+        new Promise((resolve, reject) => {
+          const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+          }, ms);
+          const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(signal?.reason ?? new Error('Sleep aborted.'));
+          };
+          signal?.addEventListener('abort', onAbort, { once: true });
+        }));
+    this.#nowFn = options.nowFn ?? monotonicNow;
     this.#localCaptureFn = options.localCaptureFn ?? runBaselineCapture;
     this.#apiUrl = (snapConfig.apiUrl || DEFAULT_API_URL).replace(/\/+$/, '');
     this.#apiKey = this.#resolveApiKey(snapConfig);
@@ -529,9 +795,7 @@ export class SnapProvider {
    */
   async capture(options) {
     const { config } = await loadSnapdriftConfig(options.configPath);
-    const requestedRouteIds = options.routeIds
-      ? [...options.routeIds]
-      : splitCommaList(process.env.SNAPDRIFT_ROUTE_IDS);
+    const requestedRouteIds = options.routeIds ? [...options.routeIds] : splitCommaList(process.env.SNAPDRIFT_ROUTE_IDS);
     const { routes, selectedRouteIds } = selectConfiguredRoutes(config, requestedRouteIds);
     const purpose = options.purpose ?? 'diff';
     const configuredRouteIds = config.routes.map((route) => route.id);
@@ -542,9 +806,7 @@ export class SnapProvider {
     }
 
     const baselineRef = purpose === 'baseline' ? resolveHostedBaselinePublicationRef() : undefined;
-    const runContext = baselineRef
-      ? { branch: baselineRef.refBranch, prHeadSha: baselineRef.refSha }
-      : this.#gitRunContext();
+    const runContext = baselineRef ? { branch: baselineRef.refBranch, prHeadSha: baselineRef.refSha } : this.#gitRunContext();
 
     if (isLocalBaseUrl(config.baseUrl)) {
       return this.#captureLocalAndUpload({
@@ -558,12 +820,14 @@ export class SnapProvider {
         configuredRouteIds,
         expectedCaptures,
         runContext,
-        baselineRef
+        baselineRef,
+        comparisonPolicy: resolveComparisonPolicy(config)
       });
     }
 
     const idempotencyKey = this.#generateIdempotencyKey();
     const runId = `run_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+    const operation = this.#createOperationDeadline('capture');
 
     // For a diff run, resolve the latest accepted baseline so the Snap backend
     // can attach it to this run's captures. Without a baselineId the server has
@@ -575,7 +839,7 @@ export class SnapProvider {
     // Attaching one would make the backend diff the fresh captures against the
     // prior baseline — wasteful at best, and on a dimension mismatch it errors
     // the run and fails the publish.
-    const baselineId = purpose === 'diff' ? await this.#resolveLatestBaselineId() : null;
+    const baselineId = purpose === 'diff' ? await this.#resolveLatestBaselineId(operation) : null;
 
     // We intentionally do NOT send captureProfileJson on run creation. SnapDrift
     // submits routes for server-side rendering, so the render environment
@@ -586,46 +850,61 @@ export class SnapProvider {
     // profile does not populate — which crashes the server with a 500. The
     // render worker already defaults locale/timezone/viewport when no profile
     // is present, so omitting it here is behaviour-preserving.
-    await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
-      id: runId,
-      baseUrl: config.baseUrl,
-      trigger: 'ci',
-      ...(baselineId ? { baselineId } : {}),
-      // A baseline run must not be diffed. Suppress the server's
-      // auto-resolve-by-branch so no prior baseline is attached.
-      ...(purpose !== 'diff' ? { skipBaselineResolution: true } : {}),
-      capturePlan: {
-        purpose: purpose === 'baseline' ? 'baseline' : 'diff',
-        ...(baselineRef
-          ? {
-              publicationWorkflowRef: baselineRef.publicationWorkflowRef,
-              publicationSequence: baselineRef.publicationSequence
-            }
-          : {}),
-        configuredRouteIds,
-        selectedRouteIds,
-        expectedCaptures
+    const comparisonPolicy = resolveComparisonPolicy(config);
+    const runResponse = await this.#request(
+      'POST',
+      `/v1/visual/projects/${this.#projectId}/runs`,
+      {
+        id: runId,
+        baseUrl: config.baseUrl,
+        trigger: 'ci',
+        ...(baselineId ? { baselineId } : {}),
+        // A baseline run must not be diffed. Suppress the server's
+        // auto-resolve-by-branch so no prior baseline is attached.
+        ...(purpose !== 'diff' ? { skipBaselineResolution: true } : {}),
+        capturePlan: {
+          purpose: purpose === 'baseline' ? 'baseline' : 'diff',
+          ...(baselineRef
+            ? {
+                publicationWorkflowRef: baselineRef.publicationWorkflowRef,
+                publicationSequence: baselineRef.publicationSequence
+              }
+            : {}),
+          configuredRouteIds,
+          selectedRouteIds,
+          expectedCaptures
+        },
+        ...runContext,
+        ...(comparisonPolicy ? { comparisonPolicy } : {})
       },
-      ...runContext,
-    }, idempotencyKey);
+      idempotencyKey,
+      operation
+    );
+    if (comparisonPolicy) {
+      assertComparisonPolicyAcknowledged(runResponse?.comparisonPolicy, comparisonPolicy, 'Snap run creation');
+    }
 
     // Submit each route as a capture with its own idempotency key
     for (const route of routes) {
       const captureKey = this.#generateIdempotencyKey();
       const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
       const viewportDescriptor = resolveViewportDescriptor(route.viewport);
-      await this.#request('POST', `/v1/visual/runs/${runId}/captures`, {
-        id: captureId,
-        routeId: route.id,
-        routePath: route.path,
-        viewportDescriptorJson: JSON.stringify(viewportDescriptor),
-      }, captureKey);
+      await this.#request(
+        'POST',
+        `/v1/visual/runs/${runId}/captures`,
+        {
+          id: captureId,
+          routeId: route.id,
+          routePath: route.path,
+          viewportDescriptorJson: JSON.stringify(viewportDescriptor)
+        },
+        captureKey,
+        operation
+      );
     }
 
     // Write run metadata to a temp file so diff() can thread the run_id
-    const outDir = options.outDir
-      ? path.resolve(options.outDir)
-      : await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-'));
+    const outDir = options.outDir ? path.resolve(options.outDir) : await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-'));
 
     await fs.mkdir(outDir, { recursive: true });
 
@@ -637,6 +916,7 @@ export class SnapProvider {
       runId,
       projectId: this.#projectId,
       purpose,
+      ...(comparisonPolicy ? { comparisonPolicy } : {}),
       ...(baselineRef ? baselineRef : {}),
       startedAt: new Date().toISOString(),
       configuredRouteIds,
@@ -645,18 +925,25 @@ export class SnapProvider {
     };
     await Promise.all([
       fs.writeFile(resultsPath, JSON.stringify(runMetadata, null, 2)),
-      fs.writeFile(manifestPath, JSON.stringify({
-        generatedAt: new Date().toISOString(),
-        baseUrl: config.baseUrl,
-        screenshots: routes.map((r) => ({
-          id: r.id,
-          path: r.path,
-          viewport: r.viewport,
-          imagePath: `screenshots/${r.id}.png`,
-          width: 0,
-          height: 0
-        }))
-      }, null, 2))
+      fs.writeFile(
+        manifestPath,
+        JSON.stringify(
+          {
+            generatedAt: new Date().toISOString(),
+            baseUrl: config.baseUrl,
+            screenshots: routes.map((r) => ({
+              id: r.id,
+              path: r.path,
+              viewport: r.viewport,
+              imagePath: `screenshots/${sanitizeRouteId(r.id)}.png`,
+              width: 0,
+              height: 0
+            }))
+          },
+          null,
+          2
+        )
+      )
     ]);
 
     return {
@@ -680,14 +967,45 @@ export class SnapProvider {
       throw new Error('SnapProvider.diff requires currentResultsPath from a prior capture() call.');
     }
 
-    const metadata = JSON.parse(await fs.readFile(currentResultsPath, 'utf-8'));
-    const runId = metadata.runId;
+    let metadata;
+    let metadataSource;
+    try {
+      metadataSource = await fs.readFile(currentResultsPath, 'utf-8');
+    } catch (error) {
+      throw hostedDiffError(
+        `could not read capture results metadata at "${currentResultsPath}". ` + `${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    try {
+      metadata = JSON.parse(metadataSource);
+    } catch (error) {
+      throw hostedDiffError(
+        `capture results metadata is not valid JSON; recapture with SnapDrift 0.8.2 or newer. ` + `${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    const { config } = await loadSnapdriftConfig(options.configPath);
+    const diffPlan = validateHostedDiffMetadata(metadata, this.#projectId);
+    /** @type {ComparisonPolicy | undefined} */
+    let comparisonPolicy;
+    if (metadata.comparisonPolicy !== undefined) {
+      if (!isComparisonPolicy(metadata.comparisonPolicy)) {
+        throw hostedDiffError('capture results metadata has an invalid comparison policy; recapture with the updated SnapDrift client.');
+      }
+      comparisonPolicy = { ...metadata.comparisonPolicy };
+    }
 
     // Poll until the run reaches a terminal state
-    const run = await this.#pollRun(runId);
+    const operation = this.#createOperationDeadline('diff');
+    const run = await this.#pollRun(diffPlan.runId, diffPlan.expectedCaptures.length, hostedDiffError, operation);
+    if (!run || typeof run !== 'object' || run.id !== diffPlan.runId) {
+      throw hostedDiffError(`Snap returned run "${run?.id || 'unknown'}" for requested run "${diffPlan.runId}".`);
+    }
 
-    const { config } = await loadSnapdriftConfig(options.configPath);
-    const summary = this.#mapRunToSummary(run, config);
+    if (comparisonPolicy) {
+      assertComparisonPolicyAcknowledged(run.comparisonPolicy, comparisonPolicy, 'Snap run retrieval');
+    }
+
+    const summary = this.#mapRunToSummary(run, config, diffPlan, comparisonPolicy);
 
     return {
       summary,
@@ -707,8 +1025,7 @@ export class SnapProvider {
    * @returns {Promise<PublishBaselineResult>}
    */
   async publishBaseline(options) {
-    const resultsPath = options.resultsPath
-      ?? (options.bundleDir ? path.join(path.resolve(options.bundleDir), 'results.json') : undefined);
+    const resultsPath = options.resultsPath ?? (options.bundleDir ? path.join(path.resolve(options.bundleDir), 'results.json') : undefined);
 
     // Snap-native baseline: poll the run that capture() submitted, then
     // create a baseline from the rendered S3 keys.
@@ -732,31 +1049,28 @@ export class SnapProvider {
         // and surfacing its body-shape error. See #109.
         throw new Error(
           `Cannot publish a Snap baseline: no run id found in ${resultsPath}. ` +
-          'A baseline is created from the object keys of a completed Snap run, so the capture step ' +
-          'must have recorded one. Run `snapdrift baseline` (or actions/baseline) with ' +
-          `provider "snap".${readError ? ` Could not read that file: ${readError instanceof Error ? readError.message : String(readError)}` : ''}`
+            'A baseline is created from the object keys of a completed Snap run, so the capture step ' +
+            'must have recorded one. Run `snapdrift baseline` (or actions/baseline) with ' +
+            `provider "snap".${readError ? ` Could not read that file: ${readError instanceof Error ? readError.message : String(readError)}` : ''}`
         );
       }
 
       {
         const { runId } = metadata;
         const idempotencyKey = `baseline-${runId}`;
+        const operation = this.#createOperationDeadline('baseline publication');
 
         if (!Array.isArray(metadata.expectedCaptures) || metadata.expectedCaptures.length === 0) {
-          throw completeBaselineError(
-            'results metadata has no expected captures; capture again with SnapDrift 0.8.2 or newer.'
-          );
+          throw completeBaselineError('results metadata has no expected captures; capture again with SnapDrift 0.8.2 or newer.');
         }
 
         // Older Snap servers could mark a baseline run terminal after the first
         // submitted capture. Keep polling until the complete planned capture set
         // is present and terminal so a mixed-version rollout remains fail-closed.
-        const run = await this.#pollRun(runId, metadata.expectedCaptures.length);
+        const run = await this.#pollRun(runId, metadata.expectedCaptures.length, undefined, operation);
 
         if (run.id && run.id !== runId) {
-          throw new Error(
-            `Cannot publish a complete Snap baseline: requested source run ${runId}, but Snap returned ${run.id}.`
-          );
+          throw new Error(`Cannot publish a complete Snap baseline: requested source run ${runId}, but Snap returned ${run.id}.`);
         }
 
         // Hosted baseline runs intentionally use `new` because they omit a
@@ -767,8 +1081,8 @@ export class SnapProvider {
         if (run.status !== BASELINE_RUN_SUCCESS_STATUS) {
           throw new Error(
             `Snap baseline run ${runId} ended with status "${run.status || 'unknown'}"; ` +
-            `complete baseline publication requires "${BASELINE_RUN_SUCCESS_STATUS}". ` +
-            'Check the Snap dashboard for capture error details.'
+              `complete baseline publication requires "${BASELINE_RUN_SUCCESS_STATUS}". ` +
+              'Check the Snap dashboard for capture error details.'
           );
         }
 
@@ -794,7 +1108,8 @@ export class SnapProvider {
             manifestJson,
             captureProfileJson: JSON.stringify(this.#buildCaptureProfile())
           },
-          idempotencyKey
+          idempotencyKey,
+          operation
         );
 
         const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-baseline-'));
@@ -805,8 +1120,8 @@ export class SnapProvider {
     // No resultsPath and no bundleDir: there is no run to build a baseline from.
     throw new Error(
       'Cannot publish a Snap baseline: neither resultsPath nor bundleDir was provided, so there ' +
-      'is no Snap run to harvest object keys from. Run `snapdrift baseline` (or actions/baseline) ' +
-      'with provider "snap", which captures first and passes the run results through.'
+        'is no Snap run to harvest object keys from. Run `snapdrift baseline` (or actions/baseline) ' +
+        'with provider "snap", which captures first and passes the run results through.'
     );
   }
 
@@ -817,8 +1132,9 @@ export class SnapProvider {
    * @returns {Promise<BaselineData | null>}
    */
   async fetchLatestBaseline(_options) {
+    const operation = this.#createOperationDeadline('baseline lookup');
     try {
-      const baseline = await this.#request('GET', `/v1/visual/projects/${this.#projectId}/baselines/latest`);
+      const baseline = await this.#request('GET', `/v1/visual/projects/${this.#projectId}/baselines/latest`, undefined, undefined, operation);
 
       const runDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-baseline-'));
       const resultsPath = path.join(runDir, 'results.json');
@@ -855,7 +1171,7 @@ export class SnapProvider {
    * Build a PR comment body from a diff summary.
    * SnapProvider includes the dashboard URL from the summary when available.
    *
-   * @param {Record<string, unknown>} summary
+   * @param {import('@snapdrift/manifest').VisualReportSummary} summary
    * @param {import('../types/visual-diff-types').ProviderCommentMeta} [meta]
    * @returns {string}
    */
@@ -875,8 +1191,15 @@ export class SnapProvider {
    * @returns {Promise<object | null>} Baseline data if found, null on 404
    */
   async checkBaselineExists(headSha) {
+    const operation = this.#createOperationDeadline('baseline existence check');
     try {
-      const baseline = await this.#request('GET', `/v1/visual/projects/${this.#projectId}/baselines/latest?sha=${encodeURIComponent(headSha)}`);
+      const baseline = await this.#request(
+        'GET',
+        `/v1/visual/projects/${this.#projectId}/baselines/latest?sha=${encodeURIComponent(headSha)}`,
+        undefined,
+        undefined,
+        operation
+      );
       return baseline;
     } catch (error) {
       if (error instanceof SnapApiError && error.status === 404) {
@@ -919,29 +1242,30 @@ export class SnapProvider {
    */
   async exportBaselines(_options) {
     const exportPath = `/v1/visual/projects/${this.#projectId}/export`;
+    const operation = this.#createOperationDeadline('baseline export');
     let archive;
     try {
-      archive = await this.#requestBinary('GET', exportPath);
+      archive = await this.#requestBinary('GET', exportPath, operation);
     } catch (error) {
       if (error instanceof SnapApiError) {
         if (error.status === 403) {
           throw new Error(
             `Snap refused the export (403): the API key does not have the "visual:export" scope. ` +
-            `Issue a key with visual:export access for project "${this.#projectId}" and retry.`,
+              `Issue a key with visual:export access for project "${this.#projectId}" and retry.`,
             { cause: error }
           );
         }
         if (error.status === 404) {
           throw new Error(
             `Snap project "${this.#projectId}" was not found (404). ` +
-            `Check snap.projectId in snapdrift.json (or GITHUB_REPOSITORY when projectId is "auto").`,
+              `Check snap.projectId in snapdrift.json (or GITHUB_REPOSITORY when projectId is "auto").`,
             { cause: error }
           );
         }
         if (error.status === 413) {
           throw new Error(
             `Snap export for project "${this.#projectId}" is too large (413): ${error.message}. ` +
-            `The export endpoint caps the number of accepted baselines and total archive bytes.`,
+              `The export endpoint caps the number of accepted baselines and total archive bytes.`,
             { cause: error }
           );
         }
@@ -958,8 +1282,7 @@ export class SnapProvider {
     const baselines = Array.isArray(exportManifest.baselines) ? exportManifest.baselines : [];
     if (baselines.length === 0) {
       throw new Error(
-        `Snap project "${this.#projectId}" has no accepted baselines to export. ` +
-        `Publish a baseline first (snapdrift baseline with provider: "snap").`
+        `Snap project "${this.#projectId}" has no accepted baselines to export. ` + `Publish a baseline first (snapdrift baseline with provider: "snap").`
       );
     }
 
@@ -975,21 +1298,30 @@ export class SnapProvider {
     if (!baseline.sourceManifest) {
       throw new Error(
         `Snap baseline "${baseline.id}" predates manifest tracking (no source manifest was recorded ` +
-        `at publish time) and cannot be migrated. Publish a fresh baseline with a current SnapDrift ` +
-        `version, then re-run the migration.`
+          `at publish time) and cannot be migrated. Publish a fresh baseline with a current SnapDrift ` +
+          `version, then re-run the migration.`
       );
     }
     const routes = Array.isArray(baseline.sourceManifest.routes) ? baseline.sourceManifest.routes : null;
     if (!routes) {
-      throw new Error(
-        `Snap baseline "${baseline.id}" has an unrecognised source manifest format ` +
-        `(expected a "routes" array) and cannot be migrated.`
-      );
+      throw new Error(`Snap baseline "${baseline.id}" has an unrecognised source manifest format ` + `(expected a "routes" array) and cannot be migrated.`);
     }
 
-    const archivePathByKey = new Map(
-      (baseline.objects || []).map((object) => [object.sourceKey, object.archivePath])
-    );
+    const archivePathByKey = new Map((baseline.objects || []).map((object) => [object.sourceKey, object.archivePath]));
+
+    const sourceLabel = `Snap baseline "${baseline.id}" source manifest`;
+    /** @type {Map<string, unknown[]>} */
+    const routeIdsByExtension = new Map();
+    for (const route of routes) {
+      const archivePath = route && route.objectKey ? archivePathByKey.get(route.objectKey) : undefined;
+      const extension = typeof archivePath === 'string' ? path.extname(archivePath) || '.png' : '.png';
+      const routeIds = routeIdsByExtension.get(extension) || [];
+      routeIds.push(route?.routeId);
+      routeIdsByExtension.set(extension, routeIds);
+    }
+    for (const [extension, routeIds] of routeIdsByExtension) {
+      assertUniqueRouteIdFilenames(routeIds, sourceLabel, extension);
+    }
 
     /** @type {Array<{ filename: string, data: Buffer }>} */
     const screenshots = [];
@@ -1001,8 +1333,7 @@ export class SnapProvider {
       const bytes = archivePath ? entries.get(archivePath) : undefined;
       if (!bytes) {
         process.stderr.write(
-          `[SnapDrift] Warning: Snap export has no image for route "${route.routeId}" ` +
-          `in baseline ${baseline.id}. Skipping the route.\n`
+          `[SnapDrift] Warning: Snap export has no image for route "${route.routeId}" ` + `in baseline ${baseline.id}. Skipping the route.\n`
         );
         continue;
       }
@@ -1013,15 +1344,15 @@ export class SnapProvider {
       // exactly; otherwise keep custom dimensions. This round-trips with the
       // descriptor expansion capture() applies on the way up.
       const presetName = hasDescriptorDims ? viewportHash(descriptor) : null;
-      const dimensions = readPngDimensions(bytes)
-        ?? (hasDescriptorDims ? { width: descriptor.width, height: descriptor.height } : { width: 1, height: 1 });
-      const viewport = presetName && VIEWPORT_PRESETS[presetName]
-        ? presetName
-        : hasDescriptorDims
-          ? { width: descriptor.width, height: descriptor.height }
-          : { width: dimensions.width, height: dimensions.height };
-
-      const extension = path.extname(archivePath) || '.png';
+      const dimensions = readPngDimensions(bytes) ?? (hasDescriptorDims ? { width: descriptor.width, height: descriptor.height } : { width: 1, height: 1 });
+      const viewport =
+        presetName && VIEWPORT_PRESETS[presetName]
+          ? presetName
+          : hasDescriptorDims
+            ? { width: descriptor.width, height: descriptor.height }
+            : { width: dimensions.width, height: dimensions.height };
+
+      const extension = typeof archivePath === 'string' ? path.extname(archivePath) || '.png' : '.png';
       const filename = `${sanitizeRouteId(route.routeId)}${extension}`;
       screenshots.push({ filename, data: Buffer.from(bytes) });
       manifestEntries.push({
@@ -1035,15 +1366,10 @@ export class SnapProvider {
     }
 
     if (screenshots.length === 0) {
-      throw new Error(
-        `Snap baseline "${baseline.id}" contained no exportable screenshots — ` +
-        `the export archive had no image bytes for any of its routes.`
-      );
+      throw new Error(`Snap baseline "${baseline.id}" contained no exportable screenshots — ` + `the export archive had no image bytes for any of its routes.`);
     }
 
-    const captureProfile = safeJsonParse(
-      entries.get(`${baseline.id}/capture_profile.json`)?.toString('utf-8')
-    ) ?? {};
+    const captureProfile = safeJsonParse(entries.get(`${baseline.id}/capture_profile.json`)?.toString('utf-8')) ?? {};
     const engine = resolveExportEngine(captureProfile);
 
     const generatedAt = new Date().toISOString();
@@ -1124,7 +1450,7 @@ export class SnapProvider {
       if (!repo) {
         throw new Error(
           'Snap project ID is set to "auto" but GITHUB_REPOSITORY is not set. ' +
-          'Set the GITHUB_REPOSITORY environment variable or provide an explicit snap.projectId.'
+            'Set the GITHUB_REPOSITORY environment variable or provide an explicit snap.projectId.'
         );
       }
       return repoSlugToProjectId(repo);
@@ -1153,9 +1479,9 @@ export class SnapProvider {
    *
    * @returns {Promise<string | null>}
    */
-  async #resolveLatestBaselineId() {
+  async #resolveLatestBaselineId(operation = this.#createOperationDeadline('baseline lookup')) {
     try {
-      const baseline = await this.#request('GET', `/v1/visual/projects/${this.#projectId}/baselines/latest`);
+      const baseline = await this.#request('GET', `/v1/visual/projects/${this.#projectId}/baselines/latest`, undefined, undefined, operation);
       return baseline?.id ?? null;
     } catch (error) {
       if (error instanceof SnapApiError && error.status === 404) {
@@ -1185,6 +1511,324 @@ export class SnapProvider {
     return crypto.randomUUID();
   }
 
+  /** @param {string} [label] @returns {OperationDeadline} */
+  #createOperationDeadline(label = 'Snap operation') {
+    return { deadline: this.#nowFn() + MAX_OPERATION_DURATION_MS, label };
+  }
+
+  /** @param {OperationDeadline} operation @returns {number} */
+  #remainingOperationMs(operation) {
+    return operation.deadline - this.#nowFn();
+  }
+
+  /**
+   * @param {string} requestPath
+   * @param {OperationDeadline} operation
+   * @returns {SnapUnavailableError}
+   */
+  #operationDeadlineError(requestPath, operation) {
+    return new SnapUnavailableError(
+      `Snap ${operation.label} operation deadline exceeded while requesting ${requestPath}; ` + `the ${OPERATION_LIMIT_TEXT} Snap operation limit was reached`
+    );
+  }
+
+  /**
+   * @param {string} requestPath
+   * @param {number} timeoutMs
+   * @param {OperationDeadline} operation
+   * @param {number} requestLimitMs
+   * @returns {Error}
+   */
+  #requestTimeoutError(requestPath, timeoutMs, operation, requestLimitMs) {
+    const error = new Error(
+      `Snap ${operation.label} request ${requestPath} timed out after ` +
+        `${Math.max(0, Math.round(timeoutMs))}ms (request limit ${requestLimitMs}ms; ` +
+        `operation limit ${OPERATION_LIMIT_TEXT})`
+    );
+    error.name = 'SnapTransportTimeoutError';
+    return error;
+  }
+
+  /** @param {number} attempt @returns {number} */
+  #retryDelay(attempt) {
+    return Math.min(INITIAL_RETRY_DELAY_MS * RETRY_MULTIPLIER ** (attempt - 1), RETRY_DELAY_CAP_MS);
+  }
+
+  /** @param {string} requestPath @param {number} delayMs @param {OperationDeadline} operation @returns {SnapUnavailableError} */
+  #sleepTimeoutError(requestPath, delayMs, operation) {
+    return new SnapUnavailableError(
+      `Snap ${operation.label} wait for ${requestPath} timed out after ${delayMs}ms ` + `before the ${OPERATION_LIMIT_TEXT} operation deadline`
+    );
+  }
+
+  /**
+   * Read and classify an HTTP error response under the current deadline.
+   *
+   * A received 4xx remains non-retryable even when its diagnostic body cannot
+   * be read. Retryable 5xx body failures are returned to the transport loop so
+   * they retain the normal availability semantics.
+   *
+   * @param {any} response
+   * @param {string} requestPath
+   * @param {AbortController} controller
+   * @param {number} attemptDeadline
+   * @param {OperationDeadline} operation
+   * @param {number} requestLimitMs
+   * @returns {Promise<SnapApiError>}
+   */
+  async #readApiError(response, requestPath, controller, attemptDeadline, operation, requestLimitMs) {
+    let errorBody;
+    try {
+      errorBody = await this.#readResponseBody(response, requestPath, controller, attemptDeadline, operation, requestLimitMs, () => response.text());
+    } catch (error) {
+      if (response.status < 400 || response.status >= 500) throw error;
+      const detail = error instanceof Error ? error.message : String(error);
+      const reason =
+        error instanceof SnapUnavailableError || error?.name === 'SnapTransportTimeoutError'
+          ? `diagnostic body timed out (${detail})`
+          : `diagnostic body unavailable (${detail})`;
+      return new SnapApiError(response.status, `Snap API ${response.status}: ${reason}`, requestPath);
+    }
+
+    let detail = '';
+    try {
+      const parsed = JSON.parse(errorBody);
+      detail = parsed?.error || parsed?.message || '';
+    } catch {
+      /* use default message */
+    }
+    return new SnapApiError(response.status, detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`, requestPath);
+  }
+
+  /**
+   * Read a response body under the current attempt and operation deadlines.
+   *
+   * @template T
+   * @param {any} response
+   * @param {string} requestPath
+   * @param {AbortController} controller
+   * @param {number} attemptDeadline
+   * @param {OperationDeadline} operation
+   * @param {number} requestLimitMs
+   * @param {() => Promise<T>} reader
+   * @returns {Promise<T>}
+   */
+  async #readResponseBody(response, requestPath, controller, attemptDeadline, operation, requestLimitMs, reader) {
+    const now = this.#nowFn();
+    const attemptRemaining = attemptDeadline - now;
+    const operationRemaining = this.#remainingOperationMs(operation);
+    if (operationRemaining <= 0) {
+      controller.abort();
+      cancelResponseBody(response);
+      throw this.#operationDeadlineError(requestPath, operation);
+    }
+    if (attemptRemaining <= 0) {
+      controller.abort();
+      cancelResponseBody(response);
+      throw this.#requestTimeoutError(requestPath, requestLimitMs, operation, requestLimitMs);
+    }
+    const remaining = Math.min(attemptRemaining, operationRemaining);
+    return runWithTimeout(
+      reader,
+      remaining,
+      () => {
+        controller.abort();
+        cancelResponseBody(response);
+      },
+      () =>
+        this.#remainingOperationMs(operation) <= 0
+          ? this.#operationDeadlineError(requestPath, operation)
+          : this.#requestTimeoutError(requestPath, remaining, operation, requestLimitMs)
+    );
+  }
+
+  /**
+   * Sleep for a retry or poll interval without exceeding the operation budget.
+   *
+   * @param {number} delayMs
+   * @param {OperationDeadline} operation
+   * @param {string} requestPath
+   * @returns {Promise<void>}
+   */
+  async #sleepWithinOperation(delayMs, operation, requestPath) {
+    const remaining = this.#remainingOperationMs(operation);
+    if (remaining <= 0) {
+      throw this.#operationDeadlineError(requestPath, operation);
+    }
+    const delay = Math.min(delayMs, remaining);
+    const controller = new AbortController();
+    await runWithTimeout(
+      () => this.#sleepFn(delay, controller.signal),
+      // Keep a one-millisecond watchdog margin so a sleep timer scheduled by
+      // an async injected sleepFn can settle before the watchdog at the same
+      // nominal deadline. The signal aborts the default timer on timeout.
+      delay + 1,
+      () => controller.abort(),
+      () => this.#sleepTimeoutError(requestPath, delay, operation)
+    );
+  }
+
+  /**
+   * Shared JSON/binary transport with retries and bounded request bodies.
+   *
+   * @param {{
+   *   method: string,
+   *   requestPath: string,
+   *   body?: object,
+   *   idempotencyKey?: string,
+   *   contentType?: string,
+   *   accept?: string,
+   *   operation: OperationDeadline,
+   *   requestTimeoutMs: number,
+   *   decode: (response: any, controller: AbortController, attemptDeadline: number, operation: OperationDeadline, requestLimitMs: number) => Promise<any>
+   * }} options
+   * @returns {Promise<any>}
+   */
+  async #requestTransport(options) {
+    const serializedBody = options.body ? JSON.stringify(options.body) : undefined;
+    const requestHeaders = {
+      Authorization: `Bearer ${this.#apiKey}`
+    };
+    if (options.accept) {
+      requestHeaders['Accept'] = options.accept;
+    }
+    if (options.contentType) {
+      requestHeaders['Content-Type'] = options.contentType;
+    }
+    if (options.idempotencyKey && options.method === 'POST') {
+      requestHeaders['Idempotency-Key'] = options.idempotencyKey;
+    }
+
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      const remaining = this.#remainingOperationMs(options.operation);
+      if (remaining <= 0) {
+        return this.#handleUnavailable(this.#operationDeadlineError(options.requestPath, options.operation));
+      }
+
+      const attemptBudget = Math.min(options.requestTimeoutMs, remaining);
+      const attemptDeadline = this.#nowFn() + attemptBudget;
+      const controller = new AbortController();
+      try {
+        const response = await runWithTimeout(
+          () =>
+            this.#fetchFn(`${this.#apiUrl}${options.requestPath}`, {
+              method: options.method,
+              headers: { ...requestHeaders },
+              body: serializedBody,
+              signal: controller.signal
+            }),
+          attemptBudget,
+          () => controller.abort(),
+          () => this.#requestTimeoutError(options.requestPath, attemptBudget, options.operation, options.requestTimeoutMs)
+        );
+
+        if (response.ok) {
+          return await options.decode(response, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
+        }
+
+        // 4xx — non-retryable when the diagnostic body is available. A body
+        // read timeout still preserves the received HTTP status, rather than
+        // turning an already-classified API response into an availability retry.
+        if (response.status >= 400 && response.status < 500) {
+          throw await this.#readApiError(response, options.requestPath, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
+        }
+
+        // 5xx — retry with backoff unless this is the last attempt. Cancel
+        // discarded response bodies so a slow server cannot retain a stream.
+        if (attempt < MAX_RETRIES) {
+          cancelResponseBody(response);
+          await this.#sleepWithinOperation(this.#retryDelay(attempt), options.operation, options.requestPath);
+          continue;
+        }
+
+        throw await this.#readApiError(response, options.requestPath, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
+      } catch (error) {
+        if (error instanceof SnapSkipError || error instanceof SnapFallbackError) {
+          throw error;
+        }
+        if (error instanceof SnapApiError && error.status >= 400 && error.status < 500) {
+          throw error;
+        }
+        if (error instanceof SnapApiError && error.status >= 500) {
+          return this.#handleUnavailable(error);
+        }
+        if (error instanceof SnapUnavailableError) {
+          return this.#handleUnavailable(error);
+        }
+
+        if (this.#remainingOperationMs(options.operation) <= 0) {
+          return this.#handleUnavailable(this.#operationDeadlineError(options.requestPath, options.operation));
+        }
+
+        if (attempt < MAX_RETRIES) {
+          try {
+            await this.#sleepWithinOperation(this.#retryDelay(attempt), options.operation, options.requestPath);
+          } catch (retryError) {
+            return this.#handleUnavailable(retryError instanceof Error ? retryError : new SnapUnavailableError(String(retryError)));
+          }
+          continue;
+        }
+
+        const detail = error instanceof Error ? error.message : String(error);
+        return this.#handleUnavailable(new SnapUnavailableError(`Snap request ${options.requestPath} failed after ${MAX_RETRIES} attempts: ${detail}`));
+      } finally {
+        controller.abort();
+      }
+    }
+
+    return this.#handleUnavailable(this.#operationDeadlineError(options.requestPath, options.operation));
+  }
+
+  /**
+   * Make a JSON request with retry and operation deadlines.
+   *
+   * @param {string} method
+   * @param {string} requestPath
+   * @param {object} [body]
+   * @param {string} [idempotencyKey]
+   * @param {OperationDeadline} [operation]
+   * @returns {Promise<any>}
+   */
+  async #request(method, requestPath, body, idempotencyKey, operation = this.#createOperationDeadline('Snap request')) {
+    return this.#requestTransport({
+      method,
+      requestPath,
+      body,
+      idempotencyKey,
+      contentType: 'application/json',
+      accept: 'application/json',
+      operation,
+      requestTimeoutMs: JSON_REQUEST_TIMEOUT_MS,
+      decode: async (response, controller, attemptDeadline, requestOperation, requestLimitMs) => {
+        const text = await this.#readResponseBody(response, requestPath, controller, attemptDeadline, requestOperation, requestLimitMs, () => response.text());
+        return text ? JSON.parse(text) : {};
+      }
+    });
+  }
+
+  /**
+   * Make a binary request with retry and operation deadlines.
+   *
+   * @param {string} method
+   * @param {string} requestPath
+   * @param {OperationDeadline} [operation]
+   * @returns {Promise<Buffer>}
+   */
+  async #requestBinary(method, requestPath, operation = this.#createOperationDeadline('binary export')) {
+    return this.#requestTransport({
+      method,
+      requestPath,
+      operation,
+      requestTimeoutMs: BINARY_REQUEST_TIMEOUT_MS,
+      decode: async (response, controller, attemptDeadline, requestOperation, requestLimitMs) => {
+        const bytes = await this.#readResponseBody(response, requestPath, controller, attemptDeadline, requestOperation, requestLimitMs, () =>
+          response.arrayBuffer()
+        );
+        return Buffer.from(bytes);
+      }
+    });
+  }
+
   /**
    * @param {{
    *   configPath?: string,
@@ -1195,10 +1839,11 @@ export class SnapProvider {
    *   selectedRouteIds: string[],
    *   purpose: 'baseline' | 'capture' | 'diff',
    *   configuredRouteIds: string[],
-   *   expectedCaptures: import('../types/visual-diff-types').SnapExpectedCaptureIdentity[],
-   *   runContext: { branch?: string, prHeadSha?: string },
-   *   baselineRef?: { refBranch: string, refSha: string, publicationWorkflowRef: string, publicationSequence: number }
-   * }} options
+ *   expectedCaptures: import('../types/visual-diff-types').SnapExpectedCaptureIdentity[],
+ *   runContext: { branch?: string, prHeadSha?: string },
+ *   baselineRef?: { refBranch: string, refSha: string, publicationWorkflowRef: string, publicationSequence: number },
+ *   comparisonPolicy?: ComparisonPolicy
+ * }} options
    * @returns {Promise<CaptureResult>}
    */
   async #captureLocalAndUpload(options) {
@@ -1226,59 +1871,82 @@ export class SnapProvider {
     });
 
     const runId = `run_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+    const operation = this.#createOperationDeadline('capture');
     // A baseline run establishes new ground truth and must not be diffed, so we
     // omit the baselineId. Captures then settle to "new" server-side (no
     // comparison), and publishBaseline harvests their object keys. A diff run
     // attaches the latest baseline so the backend can compare against it.
-    const baselineId = options.purpose === 'diff' ? await this.#resolveLatestBaselineId() : null;
-
-    await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
-      id: runId,
-      baseUrl: options.config.baseUrl,
-      trigger: 'ci',
-      ...(baselineId ? { baselineId } : {}),
-      // A baseline run must not be diffed. Suppress the server's
-      // auto-resolve-by-branch so no prior baseline is attached.
-      ...(options.purpose !== 'diff' ? { skipBaselineResolution: true } : {}),
-      capturePlan: {
-        purpose: options.purpose === 'baseline' ? 'baseline' : 'diff',
-        ...(options.baselineRef
-          ? {
-              publicationWorkflowRef: options.baselineRef.publicationWorkflowRef,
-              publicationSequence: options.baselineRef.publicationSequence
-            }
-          : {}),
-        configuredRouteIds: options.configuredRouteIds,
-        selectedRouteIds: options.selectedRouteIds,
-        expectedCaptures: options.expectedCaptures
+    const baselineId = options.purpose === 'diff' ? await this.#resolveLatestBaselineId(operation) : null;
+
+    const runResponse = await this.#request(
+      'POST',
+      `/v1/visual/projects/${this.#projectId}/runs`,
+      {
+        id: runId,
+        baseUrl: options.config.baseUrl,
+        trigger: 'ci',
+        ...(baselineId ? { baselineId } : {}),
+        // A baseline run must not be diffed. Suppress the server's
+        // auto-resolve-by-branch so no prior baseline is attached.
+        ...(options.purpose !== 'diff' ? { skipBaselineResolution: true } : {}),
+        capturePlan: {
+          purpose: options.purpose === 'baseline' ? 'baseline' : 'diff',
+          ...(options.baselineRef
+            ? {
+                publicationWorkflowRef: options.baselineRef.publicationWorkflowRef,
+                publicationSequence: options.baselineRef.publicationSequence
+              }
+            : {}),
+          configuredRouteIds: options.configuredRouteIds,
+          selectedRouteIds: options.selectedRouteIds,
+          expectedCaptures: options.expectedCaptures
+        },
+        ...options.runContext,
+        ...(options.comparisonPolicy ? { comparisonPolicy: options.comparisonPolicy } : {})
       },
-      ...options.runContext
-    }, this.#generateIdempotencyKey());
+      this.#generateIdempotencyKey(),
+      operation
+    );
+    if (options.comparisonPolicy) {
+      assertComparisonPolicyAcknowledged(runResponse?.comparisonPolicy, options.comparisonPolicy, 'Snap local-upload run creation');
+    }
 
     for (const { route, manifestEntry } of uploads) {
       const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
       const viewportDescriptor = resolveViewportDescriptor(route.viewport);
 
-      await this.#request('POST', `/v1/visual/runs/${runId}/captures`, {
-        id: captureId,
-        routeId: route.id,
-        routePath: route.path,
-        viewportDescriptorJson: JSON.stringify(viewportDescriptor),
-        // The screenshot is captured locally and uploaded below, not rendered by
-        // Snap. This flag tells the backend to keep the capture out of the render
-        // worker's queue — without it the worker would try to render baseUrl
-        // (a client-only/loopback address it can't reach) and error the run.
-        localCapture: true,
-      }, this.#generateIdempotencyKey());
+      await this.#request(
+        'POST',
+        `/v1/visual/runs/${runId}/captures`,
+        {
+          id: captureId,
+          routeId: route.id,
+          routePath: route.path,
+          viewportDescriptorJson: JSON.stringify(viewportDescriptor),
+          // The screenshot is captured locally and uploaded below, not rendered by
+          // Snap. This flag tells the backend to keep the capture out of the render
+          // worker's queue — without it the worker would try to render baseUrl
+          // (a client-only/loopback address it can't reach) and error the run.
+          localCapture: true
+        },
+        this.#generateIdempotencyKey(),
+        operation
+      );
 
       const imagePath = path.resolve(localCapture.screenshotsRoot, manifestEntry.imagePath);
       const imageBytes = await fs.readFile(imagePath);
 
-      await this.#request('POST', `/v1/visual/captures/${captureId}/local-result`, {
-        imageBase64: imageBytes.toString('base64'),
-        width: manifestEntry.width,
-        height: manifestEntry.height
-      }, this.#generateIdempotencyKey());
+      await this.#request(
+        'POST',
+        `/v1/visual/captures/${captureId}/local-result`,
+        {
+          imageBase64: imageBytes.toString('base64'),
+          width: manifestEntry.width,
+          height: manifestEntry.height
+        },
+        this.#generateIdempotencyKey(),
+        operation
+      );
     }
 
     const snapResults = {
@@ -1288,6 +1956,7 @@ export class SnapProvider {
       runId,
       projectId: this.#projectId,
       purpose: options.purpose,
+      ...(options.comparisonPolicy ? { comparisonPolicy: options.comparisonPolicy } : {}),
       ...(options.baselineRef ? options.baselineRef : {}),
       configuredRouteIds: options.configuredRouteIds,
       selectedRouteIds: options.selectedRouteIds,
@@ -1299,149 +1968,6 @@ export class SnapProvider {
     return localCapture;
   }
 
-  /**
-   * Make an HTTP request to the Snap API with retry logic.
-   *
-   * @param {string} method
-   * @param {string} path
-   * @param {object} [body]
-   * @param {string} [idempotencyKey]
-   * @returns {Promise<any>} Parsed JSON response
-   */
-  async #request(method, path, body, idempotencyKey) {
-    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
-      try {
-        const headers = {
-          'Authorization': `Bearer ${this.#apiKey}`,
-          'Content-Type': 'application/json',
-          'Accept': 'application/json'
-        };
-        if (idempotencyKey && method === 'POST') {
-          headers['Idempotency-Key'] = idempotencyKey;
-        }
-
-        const url = `${this.#apiUrl}${path}`;
-        const response = await this.#fetchFn(url, {
-          method,
-          headers,
-          body: body ? JSON.stringify(body) : undefined
-        });
-
-        if (response.ok) {
-          const text = await response.text();
-          return text ? JSON.parse(text) : {};
-        }
-
-        // 4xx — never retry
-        if (response.status >= 400 && response.status < 500) {
-          const errorBody = await response.text().catch(() => '');
-          let detail = '';
-          try {
-            const parsed = JSON.parse(errorBody);
-            detail = parsed.error || parsed.message || '';
-          } catch { /* use default message */ }
-          const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
-          throw new SnapApiError(response.status, errorMessage, path);
-        }
-
-        // 5xx — retry with backoff (unless this is the last attempt)
-        if (attempt < MAX_RETRIES) {
-          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
-          await this.#sleepFn(delay);
-          continue;
-        }
-
-        // Exhausted retries
-        const errorBody = await response.text().catch(() => '');
-        let detail = '';
-        try {
-          const parsed = JSON.parse(errorBody);
-          detail = parsed.error || parsed.message || '';
-        } catch { /* use default message */ }
-        const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
-        return this.#handleUnavailable(new SnapApiError(response.status, errorMessage, path));
-
-      } catch (error) {
-        if (error instanceof SnapApiError) {
-          throw error;
-        }
-
-        // Network error — retry
-        if (attempt < MAX_RETRIES) {
-          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
-          await this.#sleepFn(delay);
-          continue;
-        }
-
-        return this.#handleUnavailable(new SnapUnavailableError(error instanceof Error ? error.message : String(error)));
-      }
-    }
-
-    // Unreachable, but satisfies the type checker
-    return this.#handleUnavailable(new SnapUnavailableError('Max retries exceeded'));
-  }
-
-  /**
-   * Make an HTTP request to the Snap API that returns a binary body (e.g. the
-   * export tar). Mirrors #request's retry and error semantics — 4xx never
-   * retries and throws SnapApiError, 5xx/network errors retry with backoff and
-   * consult onUnavailable when exhausted — but returns the raw bytes instead
-   * of parsed JSON.
-   *
-   * @param {string} method
-   * @param {string} path
-   * @returns {Promise<any>} Raw response bytes as a Buffer
-   */
-  async #requestBinary(method, path) {
-    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
-      try {
-        const response = await this.#fetchFn(`${this.#apiUrl}${path}`, {
-          method,
-          headers: { 'Authorization': `Bearer ${this.#apiKey}` }
-        });
-
-        if (response.ok) {
-          return Buffer.from(await response.arrayBuffer());
-        }
-
-        // 4xx — never retry
-        if (response.status >= 400 && response.status < 500) {
-          const detail = await readErrorDetail(response);
-          const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
-          throw new SnapApiError(response.status, errorMessage, path);
-        }
-
-        // 5xx — retry with backoff (unless this is the last attempt)
-        if (attempt < MAX_RETRIES) {
-          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
-          await this.#sleepFn(delay);
-          continue;
-        }
-
-        // Exhausted retries
-        const detail = await readErrorDetail(response);
-        const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
-        return this.#handleUnavailable(new SnapApiError(response.status, errorMessage, path));
-      } catch (error) {
-        if (error instanceof SnapApiError) {
-          throw error;
-        }
-
-        // Network error — retry
-        if (attempt < MAX_RETRIES) {
-          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
-          await this.#sleepFn(delay);
-          continue;
-        }
-
-        return this.#handleUnavailable(new SnapUnavailableError(error instanceof Error ? error.message : String(error)));
-      }
-    }
-
-    // Unreachable, but satisfies the type checker
-    return this.#handleUnavailable(new SnapUnavailableError('Max retries exceeded'));
-  }
-
   /**
    * Handle unavailable behavior based on onUnavailable config.
    * @param {Error} error
@@ -1471,34 +1997,37 @@ export class SnapProvider {
    * Poll a run until it reaches a terminal state.
    * @param {string} runId
    * @param {number} [expectedCaptureCount]
+   * @param {(detail: string) => Error} [errorFactory]
+   * @param {OperationDeadline} [operation]
    * @returns {Promise<JsonObject>}
    */
-  async #pollRun(runId, expectedCaptureCount) {
-    const startTime = Date.now();
+  async #pollRun(runId, expectedCaptureCount, errorFactory = (detail) => new Error(detail), operation = this.#createOperationDeadline('run polling')) {
     let incompleteTerminalSignature;
     let stableIncompleteTerminalPolls = 0;
     let incompleteSignature;
     let stableIncompletePolls = 0;
 
-    while (Date.now() - startTime < MAX_POLL_DURATION_MS) {
-      const run = await this.#request('GET', `/v1/visual/runs/${runId}`);
+    while (this.#remainingOperationMs(operation) > 0) {
+      const requestPath = `/v1/visual/runs/${runId}`;
+      const run = await this.#request('GET', requestPath, undefined, undefined, operation);
+      if (!run || typeof run !== 'object' || Array.isArray(run)) {
+        throw errorFactory(`Snap returned a malformed run response for requested run "${runId}".`);
+      }
       const captures = Array.isArray(run.captures) ? run.captures : [];
       const completeCaptureSet =
         expectedCaptureCount === undefined ||
-        (captures.length >= expectedCaptureCount &&
-          captures.every((capture) => TERMINAL_CAPTURE_STATUSES.has(capture?.status)));
+        (captures.length >= expectedCaptureCount && captures.every((capture) => TERMINAL_CAPTURE_STATUSES.has(capture?.status)));
 
       if (expectedCaptureCount !== undefined && !completeCaptureSet) {
-        const signature = JSON.stringify(captures.map((capture) => [
-          capture?.id,
-          capture?.routeId,
-          capture?.status,
-          capture?.currentObjectKey
-        ]).sort((left, right) => {
-          const leftJson = JSON.stringify(left);
-          const rightJson = JSON.stringify(right);
-          return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
-        }));
+        const signature = JSON.stringify(
+          captures
+            .map((capture) => [capture?.id, capture?.routeId, capture?.status, capture?.currentObjectKey])
+            .sort((left, right) => {
+              const leftJson = JSON.stringify(left);
+              const rightJson = JSON.stringify(right);
+              return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+            })
+        );
         if (signature === incompleteSignature) stableIncompletePolls += 1;
         else {
           incompleteSignature = signature;
@@ -1522,19 +2051,16 @@ export class SnapProvider {
         // An older server can report a terminal run after only an early subset
         // has settled. Keep polling for the full capture set until the normal
         // ten-minute deadline; ordinary renders routinely exceed a few seconds.
-        if (
-          captures.length < expectedCaptureCount &&
-          captures.every((capture) => TERMINAL_CAPTURE_STATUSES.has(capture?.status))
-        ) {
-          const signature = JSON.stringify(captures.map((capture) => [
-            capture?.id,
-            capture?.routeId,
-            capture?.status
-          ]).sort((left, right) => {
-            const leftJson = JSON.stringify(left);
-            const rightJson = JSON.stringify(right);
-            return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
-          }));
+        if (captures.length < expectedCaptureCount && captures.every((capture) => TERMINAL_CAPTURE_STATUSES.has(capture?.status))) {
+          const signature = JSON.stringify(
+            captures
+              .map((capture) => [capture?.id, capture?.routeId, capture?.status])
+              .sort((left, right) => {
+                const leftJson = JSON.stringify(left);
+                const rightJson = JSON.stringify(right);
+                return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+              })
+          );
           if (signature === incompleteTerminalSignature) stableIncompleteTerminalPolls += 1;
           else {
             incompleteTerminalSignature = signature;
@@ -1549,21 +2075,37 @@ export class SnapProvider {
         }
       }
 
-      await this.#sleepFn(POLL_INTERVAL_MS);
+      try {
+        await this.#sleepWithinOperation(POLL_INTERVAL_MS, operation, requestPath);
+      } catch (error) {
+        return this.#handleUnavailable(error instanceof Error ? error : new SnapUnavailableError(String(error)));
+      }
     }
 
-    throw new Error(`Snap run ${runId} did not complete within 10 minutes.`);
+    return this.#handleUnavailable(
+      new SnapUnavailableError(
+        `Snap ${operation.label} run ${runId} did not complete within ${OPERATION_LIMIT_TEXT}; ` + 'the Snap operation deadline was reached while polling'
+      )
+    );
   }
 
   /**
    * Map a Snap run result to a VisualDiffSummary.
    * @param {JsonObject} run
    * @param {VisualRegressionConfig} config
+   * @param {{
+   *   selectedRouteIds: string[],
+   *   expectedCaptures: Array<{ routeId: string, routePath: string, viewportDescriptorJson: string, viewport: import('../types/visual-diff-types').VisualViewport }>,
+   *   expectedByIdentity: Map<string, { routeId: string, routePath: string, viewportDescriptorJson: string, viewport: import('../types/visual-diff-types').VisualViewport }>,
+   *   expectedByRouteId: Map<string, { routeId: string, routePath: string, viewportDescriptorJson: string, viewport: import('../types/visual-diff-types').VisualViewport }>
+   * }} diffPlan
+   * @param {ComparisonPolicy} [comparisonPolicy]
    * @returns {import('../types/visual-diff-types').VisualDiffSummary}
    */
-  #mapRunToSummary(run, config) {
-    const captures = run.captures || [];
-    const totalScreenshots = captures.length;
+  #mapRunToSummary(run, config, diffPlan, comparisonPolicy) {
+    const captures = Array.isArray(run.captures) ? run.captures : [];
+    const comparisonThreshold = comparisonPolicy?.threshold ?? config.diff.threshold;
+    const totalScreenshots = diffPlan.expectedCaptures.length;
     let matchedScreenshots = 0;
     let changedScreenshots = 0;
     let missingInBaseline = 0;
@@ -1581,72 +2123,197 @@ export class SnapProvider {
     /** @type {import('../types/visual-diff-types').VisualDiffErrorItem[]} */
     const errors = [];
 
+    /**
+     * @param {string} id
+     * @param {string | undefined} path
+     * @param {import('../types/visual-diff-types').VisualViewport | undefined} viewport
+     * @param {string} message
+     */
+    const addError = (id, path, viewport, message) => {
+      errors.push({ id, path, viewport, status: 'error', message });
+    };
+
+    if (!Array.isArray(run.captures)) {
+      addError(`run:${run.id}`, undefined, undefined, 'Snap run returned no valid captures array.');
+    }
+
+    if (run.status === 'error') {
+      addError(`run:${run.id}`, undefined, undefined, run.errorDetails?.message || run.errorCode || run.message || 'Snap run ended with status "error".');
+    }
+
+    const seenIdentities = new Set();
+    const coveredExpectedRoutes = new Set();
     for (const capture of captures) {
+      if (!capture || typeof capture !== 'object' || Array.isArray(capture)) {
+        addError('unknown', undefined, undefined, 'Snap run returned a malformed capture.');
+        continue;
+      }
+
+      if (typeof capture.routeId === 'string' && diffPlan.expectedByRouteId.has(capture.routeId)) {
+        coveredExpectedRoutes.add(capture.routeId);
+      }
+
+      let identity;
+      try {
+        identity = captureIdentityKey(capture, `source capture "${capture.routeId || capture.id || 'unknown'}"`, hostedDiffError);
+      } catch (error) {
+        const malformedRouteId = typeof capture.routeId === 'string' && capture.routeId ? capture.routeId : 'unknown';
+        const expected = diffPlan.expectedByRouteId.get(malformedRouteId);
+        addError(
+          malformedRouteId,
+          typeof capture.routePath === 'string' ? capture.routePath : expected?.routePath,
+          expected?.viewport ?? capture.viewport,
+          error instanceof Error ? error.message : String(error)
+        );
+        continue;
+      }
+
+      const expected = diffPlan.expectedByIdentity.get(identity);
+      if (!expected) {
+        addError(capture.routeId, capture.routePath, capture.viewport, `Snap run returned an unexpected route/viewport capture for "${capture.routeId}".`);
+        continue;
+      }
+      if (seenIdentities.has(identity)) {
+        addError(expected.routeId, expected.routePath, expected.viewport, `Snap run returned a duplicate route/viewport capture for "${expected.routeId}".`);
+        continue;
+      }
+      seenIdentities.add(identity);
+
+      if (capture.routePath !== expected.routePath) {
+        addError(expected.routeId, capture.routePath, expected.viewport, `Snap run returned an unexpected path for "${expected.routeId}".`);
+        continue;
+      }
+
       if (capture.status === 'error') {
-        errors.push({
-          id: capture.routeId || capture.id,
-          path: capture.routePath,
-          viewport: capture.viewport,
-          status: 'error',
-          message: capture.errorDetails?.message || capture.errorCode || 'Unknown error'
-        });
+        addError(
+          expected.routeId,
+          expected.routePath,
+          expected.viewport,
+          capture.errorDetails?.message || capture.errorCode || 'Snap capture ended with status "error".'
+        );
+        continue;
+      }
+
+      if (capture.status !== 'new' && capture.status !== 'diffed') {
+        addError(
+          expected.routeId,
+          expected.routePath,
+          expected.viewport,
+          `Snap capture "${expected.routeId}" ended with unknown status "${capture.status || 'unknown'}".`
+        );
+        continue;
+      }
+
+      if (typeof capture.currentObjectKey !== 'string' || !capture.currentObjectKey) {
+        addError(expected.routeId, expected.routePath, expected.viewport, `Snap capture "${expected.routeId}" has no currentObjectKey.`);
         continue;
       }
 
       if (capture.status === 'new') {
-        // The backend rendered this capture but had no baseline to diff against
-        // (first run for the route). Surface it as a missing baseline rather than
-        // a silent match — there is nothing to compare yet.
+        // The backend rendered this capture but had no baseline to diff against.
         missingInBaseline++;
         missing.push({
-          id: capture.routeId || capture.id,
+          id: expected.routeId,
           reason: 'no baseline capture found on Snap',
-          path: capture.routePath,
-          viewport: capture.viewport,
+          path: expected.routePath,
+          viewport: expected.viewport,
           location: 'baseline'
         });
         continue;
       }
 
-      if (capture.status === 'diffed') {
-        if (!capture.baselineObjectKey) {
-          // No baseline was attached to this capture: the backend short-circuits
-          // to "diffed" with no comparison data (no diffPct / diff image). Surface
-          // it as a missing baseline instead of silently counting it as a match.
-          missingInBaseline++;
-          missing.push({
-            id: capture.routeId || capture.id,
-            reason: 'no baseline capture found on Snap',
-            path: capture.routePath,
-            viewport: capture.viewport,
-            location: 'baseline'
-          });
-        } else if (capture.diffPct != null && capture.diffPct > config.diff.threshold) {
-          comparedWithBaseline++;
-          changedScreenshots++;
-          changed.push({
-            id: capture.routeId || capture.id,
-            path: capture.routePath || '',
-            viewport: capture.viewport,
-            baselineImagePath: capture.baselineObjectKey || '',
-            currentImagePath: capture.currentObjectKey || '',
-            width: capture.width || 0,
-            height: capture.height || 0,
-            differentPixels: capture.diffPixels || 0,
-            totalPixels: (capture.width || 0) * (capture.height || 0),
-            mismatchRatio: capture.diffPct,
-            status: 'changed'
-          });
-        } else {
-          comparedWithBaseline++;
-          if (capture.diffPct === 0) {
-            exactZeroMatches++;
-          }
-          matchedScreenshots++;
+      if (capture.baselineObjectKey !== undefined && capture.baselineObjectKey !== null && typeof capture.baselineObjectKey !== 'string') {
+        addError(expected.routeId, expected.routePath, expected.viewport, `Snap capture "${expected.routeId}" has an invalid baselineObjectKey.`);
+        continue;
+      }
+
+      if (!capture.baselineObjectKey) {
+        // No baseline was attached to this capture: the backend short-circuits
+        // to "diffed" with no comparison data.
+        missingInBaseline++;
+        missing.push({
+          id: expected.routeId,
+          reason: 'no baseline capture found on Snap',
+          path: expected.routePath,
+          viewport: expected.viewport,
+          location: 'baseline'
+        });
+        continue;
+      }
+
+      const comparison = comparisonFromCapture(capture);
+      if (comparisonPolicy && !comparison) {
+        addError(
+          expected.routeId,
+          expected.routePath,
+          expected.viewport,
+          `Snap capture "${expected.routeId}" is missing complete comparison metadata; ` +
+            'upgrade the Snap server and diff Lambda before enabling comparisonPolicy v1.'
+        );
+        continue;
+      }
+
+      if (!Number.isFinite(capture.diffPct) || capture.diffPct < 0 || capture.diffPct > 1) {
+        addError(expected.routeId, expected.routePath, expected.viewport, `Snap capture "${expected.routeId}" has an invalid diffPct.`);
+        continue;
+      }
+
+      if (comparisonPolicy && comparison && !hasCompleteComparisonResult(capture, comparison, comparisonPolicy.threshold)) {
+        addError(
+          expected.routeId,
+          expected.routePath,
+          expected.viewport,
+          `Snap capture "${expected.routeId}" has incomplete or inconsistent comparison statistics.`
+        );
+        continue;
+      }
+
+      if (comparison && (!Number.isInteger(capture.diffPixels) || capture.diffPixels < 0 || capture.diffPixels > comparison.totalPixels)) {
+        addError(expected.routeId, expected.routePath, expected.viewport, `Snap capture "${expected.routeId}" has invalid comparison pixel statistics.`);
+        continue;
+      }
+
+      const legacyWidth = capture.width || 0;
+      const legacyHeight = capture.height || 0;
+      const dimensionsChanged = comparison?.dimensionsChanged === true;
+      if (dimensionsChanged || capture.diffPct > comparisonThreshold) {
+        comparedWithBaseline++;
+        changedScreenshots++;
+        changed.push({
+          id: expected.routeId,
+          path: expected.routePath,
+          viewport: expected.viewport,
+          baselineImagePath: capture.baselineObjectKey,
+          currentImagePath: capture.currentObjectKey,
+          width: comparison?.canvas.width ?? legacyWidth,
+          height: comparison?.canvas.height ?? legacyHeight,
+          differentPixels: capture.diffPixels || 0,
+          totalPixels: comparison?.totalPixels ?? legacyWidth * legacyHeight,
+          mismatchRatio: capture.diffPct,
+          status: 'changed',
+          ...(comparison ? { comparison } : {})
+        });
+      } else {
+        comparedWithBaseline++;
+        if (capture.diffPct === 0) {
+          exactZeroMatches++;
         }
+        matchedScreenshots++;
       }
     }
 
+    for (const expected of diffPlan.expectedByRouteId.values()) {
+      if (coveredExpectedRoutes.has(expected.routeId)) continue;
+      missingInCurrent++;
+      missing.push({
+        id: expected.routeId,
+        reason: 'capture missing from Snap run',
+        path: expected.routePath,
+        viewport: expected.viewport,
+        location: 'current'
+      });
+    }
+
     // False-negative guard: when a diff run compared every route against a real
     // baseline yet every single comparison came back pixel-identical (0% drift),
     // the most likely explanation is that the client captured a stale or wrong
@@ -1661,9 +2328,9 @@ export class SnapProvider {
     if (comparedWithBaseline > 1 && exactZeroMatches === comparedWithBaseline) {
       process.stderr.write(
         `[SnapDrift] Warning: all ${comparedWithBaseline} compared route(s) were pixel-identical ` +
-        `to the baseline (0% drift). If you expected a visual change, the captured page may be ` +
-        `stale or wrong — verify the resolved baseUrl points at the PR preview and that the ` +
-        `preview was deployed before capture ran. See issue #93.\n`
+          `to the baseline (0% drift). If you expected a visual change, the captured page may be ` +
+          `stale or wrong — verify the resolved baseUrl points at the PR preview and that the ` +
+          `preview was deployed before capture ran. See issue #93.\n`
       );
     }
 
@@ -1673,11 +2340,11 @@ export class SnapProvider {
       finishedAt: run.finishedAt || new Date().toISOString(),
       completed: true,
       status: run.status === 'pass' ? 'clean' : run.status === 'fail' ? 'changes-detected' : 'incomplete',
-      selectedRoutes: captures.map((c) => c.routeId || c.id),
+      selectedRoutes: diffPlan.selectedRouteIds,
       baselineManifestPath: '',
       currentManifestPath: '',
       diffMode: config.diff.mode,
-      threshold: config.diff.threshold,
+      threshold: comparisonThreshold,
       baselineResultsPath: '',
       currentResultsPath: '',
       totalScreenshots,
@@ -1689,6 +2356,7 @@ export class SnapProvider {
       missing,
       errors,
       dimensionChanges: [],
+      ...(comparisonPolicy ? { comparisonPolicy: { ...comparisonPolicy } } : {}),
       dashboardUrl: `${this.#apiUrl}/dashboard/visual/${this.#projectId}/runs/${run.id}`
     };
 
@@ -1719,6 +2387,21 @@ export class SnapApiError extends Error {
   }
 }
 
+/**
+ * Error raised when an updated client opts into a comparison policy that the
+ * connected Snap server does not acknowledge.
+ */
+export class SnapUpgradeRequiredError extends Error {
+  /** @type {'comparison_policy_unsupported'} */
+  code = 'comparison_policy_unsupported';
+
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'SnapUpgradeRequiredError';
+  }
+}
+
 /**
  * Error thrown when the Snap API is unreachable after all retries.
  */