snapdrift 0.9.0 → 0.10.0

package/lib/snap-provider.mjs

@@ -31,6 +31,8 @@ import {
 /** @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 */
 
@@ -44,6 +46,7 @@ const BINARY_REQUEST_TIMEOUT_MS = 120 * 1000;
 const POLL_INTERVAL_MS = 2000;
 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']);
@@ -65,9 +68,7 @@ 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();
+  return typeof globalThis.performance?.now === 'function' ? globalThis.performance.now() : Date.now();
 }
 
 /**
@@ -92,19 +93,22 @@ function runWithTimeout(task, timeoutMs, onTimeout, timeoutError) {
       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));
+    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) => {
+    taskPromise.then(
+      (value) => {
         if (settled) {
           if (value && typeof value === 'object') cancelResponseBody(value);
           return;
@@ -112,12 +116,14 @@ function runWithTimeout(task, timeoutMs, onTimeout, timeoutError) {
         settled = true;
         clearTimeout(timer);
         resolve(value);
-      }, (error) => {
+      },
+      (error) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
         reject(error);
-      });
+      }
+    );
   });
 }
 
@@ -139,14 +145,113 @@ 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 */
@@ -171,13 +276,10 @@ function normalizeViewportDescriptor(value, context, errorFactory) {
   } catch {
     throw errorFactory(`${context} has malformed viewportDescriptorJson.`);
   }
-  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor) ||
-      !Number.isFinite(descriptor.width) || !Number.isFinite(descriptor.height)) {
+  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))));
 }
 
 /**
@@ -234,51 +336,43 @@ function validateHostedDiffMetadata(metadata, projectId) {
     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}".`
-    );
+    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.'
-    );
+    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.'
-    );
+    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).`
-    );
+    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)) {
+    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 viewportDescriptorJson = normalizeViewportDescriptor(expected.viewportDescriptorJson, `expected capture "${expected.routeId}"`, hostedDiffError);
     const viewportDescriptor = JSON.parse(viewportDescriptorJson);
     const expectedCapture = {
       routeId: expected.routeId,
@@ -310,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.'
   );
 }
 
@@ -328,23 +422,14 @@ 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', completeBaselineError);
@@ -357,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}"`, completeBaselineError),
-      expected
-    );
+    expectedByIdentity.set(captureIdentityKey(expected, `expected capture "${expected.routeId}"`, completeBaselineError), expected);
   }
 
   if (!Array.isArray(run.captures)) throw completeBaselineError('source run has no captures array.');
@@ -378,11 +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'}"`,
-      completeBaselineError
-    );
+    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}".`);
     }
@@ -486,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'
   };
 }
@@ -499,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 (
@@ -513,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 };
@@ -679,18 +757,21 @@ export class SnapProvider {
   constructor(snapConfig, options = {}) {
     this.#snapConfig = snapConfig;
     this.#fetchFn = options.fetchFn ?? globalThis.fetch;
-    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.#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(/\/+$/, '');
@@ -714,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);
@@ -727,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({
@@ -743,7 +820,8 @@ export class SnapProvider {
         configuredRouteIds,
         expectedCaptures,
         runContext,
-        baselineRef
+        baselineRef,
+        comparisonPolicy: resolveComparisonPolicy(config)
       });
     }
 
@@ -772,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, operation);
+      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, operation);
+      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 });
 
@@ -823,6 +916,7 @@ export class SnapProvider {
       runId,
       projectId: this.#projectId,
       purpose,
+      ...(comparisonPolicy ? { comparisonPolicy } : {}),
       ...(baselineRef ? baselineRef : {}),
       startedAt: new Date().toISOString(),
       configuredRouteIds,
@@ -831,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/${sanitizeRouteId(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 {
@@ -872,31 +973,39 @@ export class SnapProvider {
       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)}`
+        `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)}`
+        `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 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}".`
-      );
+      throw hostedDiffError(`Snap returned run "${run?.id || 'unknown'}" for requested run "${diffPlan.runId}".`);
     }
 
-    const summary = this.#mapRunToSummary(run, config, diffPlan);
+    if (comparisonPolicy) {
+      assertComparisonPolicyAcknowledged(run.comparisonPolicy, comparisonPolicy, 'Snap run retrieval');
+    }
+
+    const summary = this.#mapRunToSummary(run, config, diffPlan, comparisonPolicy);
 
     return {
       summary,
@@ -916,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.
@@ -941,9 +1049,9 @@ 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)}` : ''}`
         );
       }
 
@@ -953,9 +1061,7 @@ export class SnapProvider {
         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
@@ -964,9 +1070,7 @@ export class SnapProvider {
         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
@@ -977,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.'
           );
         }
 
@@ -1016,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.'
     );
   }
 
@@ -1089,7 +1193,13 @@ export class SnapProvider {
   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)}`, undefined, undefined, operation);
+      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) {
@@ -1141,21 +1251,21 @@ export class SnapProvider {
         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 }
           );
         }
@@ -1172,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").`
       );
     }
 
@@ -1189,21 +1298,16 @@ 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[]>} */
@@ -1229,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;
       }
@@ -1241,13 +1344,13 @@ 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 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}`;
@@ -1263,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();
@@ -1352,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);
@@ -1430,8 +1528,7 @@ export class SnapProvider {
    */
   #operationDeadlineError(requestPath, operation) {
     return new SnapUnavailableError(
-      `Snap ${operation.label} operation deadline exceeded while requesting ${requestPath}; ` +
-      `the ${OPERATION_LIMIT_TEXT} Snap operation limit was reached`
+      `Snap ${operation.label} operation deadline exceeded while requesting ${requestPath}; ` + `the ${OPERATION_LIMIT_TEXT} Snap operation limit was reached`
     );
   }
 
@@ -1445,8 +1542,8 @@ export class SnapProvider {
   #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})`
+        `${Math.max(0, Math.round(timeoutMs))}ms (request limit ${requestLimitMs}ms; ` +
+        `operation limit ${OPERATION_LIMIT_TEXT})`
     );
     error.name = 'SnapTransportTimeoutError';
     return error;
@@ -1454,17 +1551,13 @@ export class SnapProvider {
 
   /** @param {number} attempt @returns {number} */
   #retryDelay(attempt) {
-    return Math.min(
-      INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)),
-      RETRY_DELAY_CAP_MS
-    );
+    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`
+      `Snap ${operation.label} wait for ${requestPath} timed out after ${delayMs}ms ` + `before the ${OPERATION_LIMIT_TEXT} operation deadline`
     );
   }
 
@@ -1486,38 +1579,25 @@ export class SnapProvider {
   async #readApiError(response, requestPath, controller, attemptDeadline, operation, requestLimitMs) {
     let errorBody;
     try {
-      errorBody = await this.#readResponseBody(
-        response,
-        requestPath,
-        controller,
-        attemptDeadline,
-        operation,
-        requestLimitMs,
-        () => response.text()
-      );
+      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
-      );
+      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
-    );
+    } catch {
+      /* use default message */
+    }
+    return new SnapApiError(response.status, detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`, requestPath);
   }
 
   /**
@@ -1555,9 +1635,10 @@ export class SnapProvider {
         controller.abort();
         cancelResponseBody(response);
       },
-      () => this.#remainingOperationMs(operation) <= 0
-        ? this.#operationDeadlineError(requestPath, operation)
-        : this.#requestTimeoutError(requestPath, remaining, operation, requestLimitMs)
+      () =>
+        this.#remainingOperationMs(operation) <= 0
+          ? this.#operationDeadlineError(requestPath, operation)
+          : this.#requestTimeoutError(requestPath, remaining, operation, requestLimitMs)
     );
   }
 
@@ -1606,7 +1687,7 @@ export class SnapProvider {
   async #requestTransport(options) {
     const serializedBody = options.body ? JSON.stringify(options.body) : undefined;
     const requestHeaders = {
-      'Authorization': `Bearer ${this.#apiKey}`
+      Authorization: `Bearer ${this.#apiKey}`
     };
     if (options.accept) {
       requestHeaders['Accept'] = options.accept;
@@ -1629,12 +1710,13 @@ export class SnapProvider {
       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
-          }),
+          () =>
+            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)
@@ -1648,14 +1730,7 @@ export class SnapProvider {
         // 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
-          );
+          throw await this.#readApiError(response, options.requestPath, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
         }
 
         // 5xx — retry with backoff unless this is the last attempt. Cancel
@@ -1666,14 +1741,7 @@ export class SnapProvider {
           continue;
         }
 
-        throw await this.#readApiError(
-          response,
-          options.requestPath,
-          controller,
-          attemptDeadline,
-          options.operation,
-          options.requestTimeoutMs
-        );
+        throw await this.#readApiError(response, options.requestPath, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
       } catch (error) {
         if (error instanceof SnapSkipError || error instanceof SnapFallbackError) {
           throw error;
@@ -1696,19 +1764,13 @@ export class SnapProvider {
           try {
             await this.#sleepWithinOperation(this.#retryDelay(attempt), options.operation, options.requestPath);
           } catch (retryError) {
-            return this.#handleUnavailable(retryError instanceof Error
-              ? retryError
-              : new SnapUnavailableError(String(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}`
-          )
-        );
+        return this.#handleUnavailable(new SnapUnavailableError(`Snap request ${options.requestPath} failed after ${MAX_RETRIES} attempts: ${detail}`));
       } finally {
         controller.abort();
       }
@@ -1738,15 +1800,7 @@ export class SnapProvider {
       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()
-        );
+        const text = await this.#readResponseBody(response, requestPath, controller, attemptDeadline, requestOperation, requestLimitMs, () => response.text());
         return text ? JSON.parse(text) : {};
       }
     });
@@ -1767,14 +1821,8 @@ export class SnapProvider {
       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()
+        const bytes = await this.#readResponseBody(response, requestPath, controller, attemptDeadline, requestOperation, requestLimitMs, () =>
+          response.arrayBuffer()
         );
         return Buffer.from(bytes);
       }
@@ -1791,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) {
@@ -1829,53 +1878,75 @@ export class SnapProvider {
     // attaches the latest baseline so the backend can compare against it.
     const baselineId = options.purpose === 'diff' ? await this.#resolveLatestBaselineId(operation) : 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 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(), operation);
+      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(), operation);
+      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(), operation);
+      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 = {
@@ -1885,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,
@@ -1929,12 +2001,7 @@ export class SnapProvider {
    * @param {OperationDeadline} [operation]
    * @returns {Promise<JsonObject>}
    */
-  async #pollRun(
-    runId,
-    expectedCaptureCount,
-    errorFactory = (detail) => new Error(detail),
-    operation = this.#createOperationDeadline('run polling')
-  ) {
+  async #pollRun(runId, expectedCaptureCount, errorFactory = (detail) => new Error(detail), operation = this.#createOperationDeadline('run polling')) {
     let incompleteTerminalSignature;
     let stableIncompleteTerminalPolls = 0;
     let incompleteSignature;
@@ -1949,20 +2016,18 @@ export class SnapProvider {
       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;
@@ -1986,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;
@@ -2016,32 +2078,33 @@ export class SnapProvider {
       try {
         await this.#sleepWithinOperation(POLL_INTERVAL_MS, operation, requestPath);
       } catch (error) {
-        return this.#handleUnavailable(error instanceof Error
-          ? error
-          : new SnapUnavailableError(String(error)));
+        return this.#handleUnavailable(error instanceof Error ? error : new SnapUnavailableError(String(error)));
       }
     }
 
-    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'
-    ));
+    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 {{
+   *   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, diffPlan) {
+  #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;
@@ -2075,12 +2138,7 @@ export class SnapProvider {
     }
 
     if (run.status === 'error') {
-      addError(
-        `run:${run.id}`,
-        undefined,
-        undefined,
-        run.errorDetails?.message || run.errorCode || run.message || 'Snap run ended with 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();
@@ -2097,15 +2155,9 @@ export class SnapProvider {
 
       let identity;
       try {
-        identity = captureIdentityKey(
-          capture,
-          `source capture "${capture.routeId || capture.id || 'unknown'}"`,
-          hostedDiffError
-        );
+        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 malformedRouteId = typeof capture.routeId === 'string' && capture.routeId ? capture.routeId : 'unknown';
         const expected = diffPlan.expectedByRouteId.get(malformedRouteId);
         addError(
           malformedRouteId,
@@ -2118,32 +2170,17 @@ export class SnapProvider {
 
       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}".`
-        );
+        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}".`
-        );
+        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}".`
-        );
+        addError(expected.routeId, capture.routePath, expected.viewport, `Snap run returned an unexpected path for "${expected.routeId}".`);
         continue;
       }
 
@@ -2168,12 +2205,7 @@ export class SnapProvider {
       }
 
       if (typeof capture.currentObjectKey !== 'string' || !capture.currentObjectKey) {
-        addError(
-          expected.routeId,
-          expected.routePath,
-          expected.viewport,
-          `Snap capture "${expected.routeId}" has no currentObjectKey.`
-        );
+        addError(expected.routeId, expected.routePath, expected.viewport, `Snap capture "${expected.routeId}" has no currentObjectKey.`);
         continue;
       }
 
@@ -2190,15 +2222,8 @@ export class SnapProvider {
         continue;
       }
 
-      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.`
-        );
+      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;
       }
 
@@ -2216,17 +2241,42 @@ export class SnapProvider {
         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 an invalid diffPct.`
+          `Snap capture "${expected.routeId}" has incomplete or inconsistent comparison statistics.`
         );
         continue;
       }
 
-      if (capture.diffPct > config.diff.threshold) {
+      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({
@@ -2235,12 +2285,13 @@ export class SnapProvider {
           viewport: expected.viewport,
           baselineImagePath: capture.baselineObjectKey,
           currentImagePath: capture.currentObjectKey,
-          width: capture.width || 0,
-          height: capture.height || 0,
+          width: comparison?.canvas.width ?? legacyWidth,
+          height: comparison?.canvas.height ?? legacyHeight,
           differentPixels: capture.diffPixels || 0,
-          totalPixels: (capture.width || 0) * (capture.height || 0),
+          totalPixels: comparison?.totalPixels ?? legacyWidth * legacyHeight,
           mismatchRatio: capture.diffPct,
-          status: 'changed'
+          status: 'changed',
+          ...(comparison ? { comparison } : {})
         });
       } else {
         comparedWithBaseline++;
@@ -2277,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`
       );
     }
 
@@ -2293,7 +2344,7 @@ export class SnapProvider {
       baselineManifestPath: '',
       currentManifestPath: '',
       diffMode: config.diff.mode,
-      threshold: config.diff.threshold,
+      threshold: comparisonThreshold,
       baselineResultsPath: '',
       currentResultsPath: '',
       totalScreenshots,
@@ -2305,6 +2356,7 @@ export class SnapProvider {
       missing,
       errors,
       dimensionChanges: [],
+      ...(comparisonPolicy ? { comparisonPolicy: { ...comparisonPolicy } } : {}),
       dashboardUrl: `${this.#apiUrl}/dashboard/visual/${this.#projectId}/runs/${run.id}`
     };
 
@@ -2335,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.
  */