snapdrift 0.8.2 → 0.9.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 */
@@ -24,14 +32,17 @@ import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_
 /** @typedef {import('../types/visual-diff-types').SnapConfig} SnapConfig */
 /** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
 /** @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 BASELINE_RUN_SUCCESS_STATUS = 'new';
 const BASELINE_CAPTURE_SUCCESS_STATUS = 'new';
@@ -43,11 +54,91 @@ 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 {import('../types/visual-diff-types').VisualViewport} viewport
  * @returns {{ width: number, height: number, deviceScaleFactor?: number, isMobile?: boolean, hasTouch?: boolean }}
@@ -67,43 +158,151 @@ 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.`);
+    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)
   ));
 }
 
-/** @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);
@@ -148,8 +347,8 @@ function validateCompleteBaselineRun(metadata, run, projectId) {
     );
   }
 
-  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).`);
@@ -164,7 +363,7 @@ function validateCompleteBaselineRun(metadata, run, projectId) {
     }
     expectedRoutes.add(expected.routeId);
     expectedByIdentity.set(
-      captureIdentityKey(expected, `expected capture "${expected.routeId}"`),
+      captureIdentityKey(expected, `expected capture "${expected.routeId}"`, completeBaselineError),
       expected
     );
   }
@@ -179,7 +378,11 @@ 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 +409,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;
   });
 }
@@ -336,23 +539,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 +643,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 +654,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 +671,27 @@ 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);
@@ -564,6 +749,7 @@ export class SnapProvider {
 
     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 +761,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
@@ -607,7 +793,7 @@ export class SnapProvider {
         expectedCaptures
       },
       ...runContext,
-    }, idempotencyKey);
+    }, idempotencyKey, operation);
 
     // Submit each route as a capture with its own idempotency key
     for (const route of routes) {
@@ -619,7 +805,7 @@ export class SnapProvider {
         routeId: route.id,
         routePath: route.path,
         viewportDescriptorJson: JSON.stringify(viewportDescriptor),
-      }, captureKey);
+      }, captureKey, operation);
     }
 
     // Write run metadata to a temp file so diff() can thread the run_id
@@ -652,7 +838,7 @@ export class SnapProvider {
           id: r.id,
           path: r.path,
           viewport: r.viewport,
-          imagePath: `screenshots/${r.id}.png`,
+          imagePath: `screenshots/${sanitizeRouteId(r.id)}.png`,
           width: 0,
           height: 0
         }))
@@ -680,14 +866,37 @@ 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);
 
     // 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);
+    const summary = this.#mapRunToSummary(run, config, diffPlan);
 
     return {
       summary,
@@ -741,6 +950,7 @@ export class SnapProvider {
       {
         const { runId } = metadata;
         const idempotencyKey = `baseline-${runId}`;
+        const operation = this.#createOperationDeadline('baseline publication');
 
         if (!Array.isArray(metadata.expectedCaptures) || metadata.expectedCaptures.length === 0) {
           throw completeBaselineError(
@@ -751,7 +961,7 @@ export class SnapProvider {
         // 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(
@@ -794,7 +1004,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-'));
@@ -817,8 +1028,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 +1067,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 +1087,9 @@ 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,9 +1132,10 @@ 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) {
@@ -991,6 +1205,20 @@ export class SnapProvider {
       (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 = [];
     /** @type {JsonObject[]} */
@@ -1021,7 +1249,7 @@ export class SnapProvider {
           ? { width: descriptor.width, height: descriptor.height }
           : { width: dimensions.width, height: dimensions.height };
 
-      const extension = path.extname(archivePath) || '.png';
+      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({
@@ -1153,9 +1381,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 +1413,374 @@ 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,
@@ -1226,11 +1822,12 @@ 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;
+    const baselineId = options.purpose === 'diff' ? await this.#resolveLatestBaselineId(operation) : null;
 
     await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
       id: runId,
@@ -1253,7 +1850,7 @@ export class SnapProvider {
         expectedCaptures: options.expectedCaptures
       },
       ...options.runContext
-    }, this.#generateIdempotencyKey());
+    }, this.#generateIdempotencyKey(), operation);
 
     for (const { route, manifestEntry } of uploads) {
       const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
@@ -1269,7 +1866,7 @@ export class SnapProvider {
         // 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());
+      }, this.#generateIdempotencyKey(), operation);
 
       const imagePath = path.resolve(localCapture.screenshotsRoot, manifestEntry.imagePath);
       const imageBytes = await fs.readFile(imagePath);
@@ -1278,7 +1875,7 @@ export class SnapProvider {
         imageBase64: imageBytes.toString('base64'),
         width: manifestEntry.width,
         height: manifestEntry.height
-      }, this.#generateIdempotencyKey());
+      }, this.#generateIdempotencyKey(), operation);
     }
 
     const snapResults = {
@@ -1299,149 +1896,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,17 +1925,27 @@ 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 ||
@@ -1549,21 +2013,36 @@ 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
    * @returns {import('../types/visual-diff-types').VisualDiffSummary}
    */
-  #mapRunToSummary(run, config) {
-    const captures = run.captures || [];
-    const totalScreenshots = captures.length;
+  #mapRunToSummary(run, config, diffPlan) {
+    const captures = Array.isArray(run.captures) ? run.captures : [];
+    const totalScreenshots = diffPlan.expectedCaptures.length;
     let matchedScreenshots = 0;
     let changedScreenshots = 0;
     let missingInBaseline = 0;
@@ -1581,72 +2060,209 @@ 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;
+      }
+
+      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 (capture.diffPct > config.diff.threshold) {
+        comparedWithBaseline++;
+        changedScreenshots++;
+        changed.push({
+          id: expected.routeId,
+          path: expected.routePath,
+          viewport: expected.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++;
       }
     }
 
+    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
@@ -1673,7 +2289,7 @@ 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,