snapdrift 0.8.1 → 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,21 @@ 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';
+const TERMINAL_CAPTURE_STATUSES = new Set(['new', 'diffed', 'error']);
 
 // Snap reports a run as "new" when it has no baseline to compare against (first
 // capture for a project, or any baseline-publish run that intentionally omits a
@@ -39,6 +54,372 @@ const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
 // 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 }}
+ */
+function resolveViewportDescriptor(viewport) {
+  return typeof viewport === 'string'
+    ? (VIEWPORT_PRESETS[viewport] ?? { width: 1280, height: 720 })
+    : viewport;
+}
+
+/** @param {VisualRegressionConfig['routes'][number]} route */
+function expectedCaptureIdentity(route) {
+  return {
+    routeId: route.id,
+    routePath: route.path,
+    viewportDescriptorJson: JSON.stringify(resolveViewportDescriptor(route.viewport))
+  };
+}
+
+/**
+ * @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 errorFactory(`${context} has malformed viewportDescriptorJson.`);
+  }
+  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)
+  ));
+}
+
+/**
+ * @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 errorFactory(`${context} has no routeId.`);
+  }
+  return `${capture.routeId}\u0000${normalizeViewportDescriptor(capture.viewportDescriptorJson, context, errorFactory)}`;
+}
+
+/**
+ * @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 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 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);
+  const missing = configuredRouteIds.filter((id) => !selected.has(id));
+  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.'
+  );
+}
+
+/**
+ * @param {import('../types/visual-diff-types').SnapRunMetadata} metadata
+ * @param {JsonObject} run
+ * @param {string} projectId
+ */
+function validateCompleteBaselineRun(metadata, run, projectId) {
+  if (metadata.projectId !== projectId) {
+    throw completeBaselineError(`source run belongs to project "${metadata.projectId || 'unknown'}", not "${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) {
+    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.publicationWorkflowRef !== 'string' || !metadata.publicationWorkflowRef.trim()) {
+    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);
+  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).`);
+  }
+
+  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)) {
+      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
+    );
+  }
+
+  if (!Array.isArray(run.captures)) throw completeBaselineError('source run has no captures array.');
+  if (run.captures.length !== expectedByIdentity.size) {
+    throw completeBaselineError(`source run has ${run.captures.length} capture(s), expected ${expectedByIdentity.size}.`);
+  }
+
+  const seen = new Set();
+  const routes = run.captures.map((capture) => {
+    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
+    );
+    if (seen.has(identity)) {
+      throw completeBaselineError(`duplicate source route/viewport identity for "${capture.routeId}".`);
+    }
+    seen.add(identity);
+    const expected = expectedByIdentity.get(identity);
+    if (!expected) {
+      throw completeBaselineError(`source run contains an unexpected route/viewport capture for "${capture.routeId}".`);
+    }
+    if (capture.routePath !== expected.routePath) {
+      throw completeBaselineError(`source route "${capture.routeId}" used an unexpected path.`);
+    }
+    if (capture.status !== BASELINE_CAPTURE_SUCCESS_STATUS) {
+      throw completeBaselineError(`source capture "${capture.routeId}" ended with status "${capture.status || 'unknown'}".`);
+    }
+    if (typeof capture.currentObjectKey !== 'string' || !capture.currentObjectKey) {
+      throw completeBaselineError(`source capture "${capture.routeId}" has no currentObjectKey.`);
+    }
+    return {
+      routeId: expected.routeId,
+      routePath: expected.routePath,
+      viewportDescriptorJson: expected.viewportDescriptorJson,
+      objectKey: capture.currentObjectKey
+    };
+  });
+
+  return routes.sort((left, right) => {
+    const leftKey = captureIdentityKey(left, `route "${left.routeId}"`, completeBaselineError);
+    const rightKey = captureIdentityKey(right, `route "${right.routeId}"`, completeBaselineError);
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+}
+
+/** @param {string} runId */
+function baselineIdForRun(runId) {
+  return `bsl_${crypto.createHash('sha256').update(runId).digest('hex').slice(0, 24)}`;
+}
+
 /**
  * @param {string | undefined} baseUrl
  * @returns {boolean}
@@ -114,6 +495,33 @@ export function resolveGitRef() {
   };
 }
 
+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 sequenceValue = process.env.SNAPDRIFT_PUBLICATION_SEQUENCE || process.env.GITHUB_RUN_NUMBER;
+  const publicationSequence = Number(sequenceValue);
+  if (
+    !refBranch ||
+    !refSha ||
+    !/^[0-9a-f]{40}$/i.test(refSha) ||
+    !publicationWorkflowRef ||
+    !Number.isSafeInteger(publicationSequence) ||
+    publicationSequence <= 0
+  ) {
+    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.'
+    );
+  }
+  return { refBranch, refSha, publicationWorkflowRef, publicationSequence };
+}
+
 /**
  * Read the package version from package.json.
  * @returns {string}
@@ -131,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 →
@@ -252,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.
@@ -279,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} */
@@ -294,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);
@@ -329,6 +719,17 @@ export class SnapProvider {
       : 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);
+    const expectedCaptures = routes.map(expectedCaptureIdentity);
+
+    if (purpose === 'baseline') {
+      assertCompleteHostedBaselineSelection(configuredRouteIds, selectedRouteIds);
+    }
+
+    const baselineRef = purpose === 'baseline' ? resolveHostedBaselinePublicationRef() : undefined;
+    const runContext = baselineRef
+      ? { branch: baselineRef.refBranch, prHeadSha: baselineRef.refSha }
+      : this.#gitRunContext();
 
     if (isLocalBaseUrl(config.baseUrl)) {
       return this.#captureLocalAndUpload({
@@ -338,12 +739,17 @@ export class SnapProvider {
         config,
         routes,
         selectedRouteIds,
-        purpose
+        purpose,
+        configuredRouteIds,
+        expectedCaptures,
+        runContext,
+        baselineRef
       });
     }
 
     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
@@ -355,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 === 'baseline' ? null : await this.#resolveLatestBaselineId();
+    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
@@ -373,23 +779,33 @@ export class SnapProvider {
       ...(baselineId ? { baselineId } : {}),
       // A baseline run must not be diffed. Suppress the server's
       // auto-resolve-by-branch so no prior baseline is attached.
-      ...(purpose === 'baseline' ? { skipBaselineResolution: true } : {}),
-      ...this.#gitRunContext(),
-    }, idempotencyKey);
+      ...(purpose !== 'diff' ? { skipBaselineResolution: true } : {}),
+      capturePlan: {
+        purpose: purpose === 'baseline' ? 'baseline' : 'diff',
+        ...(baselineRef
+          ? {
+              publicationWorkflowRef: baselineRef.publicationWorkflowRef,
+              publicationSequence: baselineRef.publicationSequence
+            }
+          : {}),
+        configuredRouteIds,
+        selectedRouteIds,
+        expectedCaptures
+      },
+      ...runContext,
+    }, idempotencyKey, operation);
 
     // 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 = typeof route.viewport === 'string'
-        ? (VIEWPORT_PRESETS[route.viewport] ?? { width: 1280, height: 720 })
-        : route.viewport;
+      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);
+      }, captureKey, operation);
     }
 
     // Write run metadata to a temp file so diff() can thread the run_id
@@ -402,7 +818,17 @@ export class SnapProvider {
     const resultsPath = path.join(outDir, 'results.json');
     const manifestPath = path.join(outDir, 'manifest.json');
 
-    const runMetadata = { runId, projectId: this.#projectId, startedAt: new Date().toISOString() };
+    /** @type {import('../types/visual-diff-types').SnapRunMetadata} */
+    const runMetadata = {
+      runId,
+      projectId: this.#projectId,
+      purpose,
+      ...(baselineRef ? baselineRef : {}),
+      startedAt: new Date().toISOString(),
+      configuredRouteIds,
+      selectedRouteIds,
+      expectedCaptures
+    };
     await Promise.all([
       fs.writeFile(resultsPath, JSON.stringify(runMetadata, null, 2)),
       fs.writeFile(manifestPath, JSON.stringify({
@@ -412,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
         }))
@@ -440,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,
@@ -473,6 +922,7 @@ export class SnapProvider {
     // Snap-native baseline: poll the run that capture() submitted, then
     // create a baseline from the rendered S3 keys.
     if (resultsPath) {
+      /** @type {import('../types/visual-diff-types').SnapRunMetadata | undefined} */
       let metadata;
       /** @type {unknown} */
       let readError;
@@ -482,7 +932,7 @@ export class SnapProvider {
         readError = error;
       }
 
-      if (!metadata?.runId) {
+      if (typeof metadata?.runId !== 'string' || !metadata.runId) {
         // Previously this fell through to a "legacy" branch that POSTed
         // `manifest`/`results` as objects. Snap has never read those fields, so
         // the request could only ever fail — with an opaque 500 before, and with
@@ -500,60 +950,62 @@ export class SnapProvider {
       {
         const { runId } = metadata;
         const idempotencyKey = `baseline-${runId}`;
+        const operation = this.#createOperationDeadline('baseline publication');
 
-        // Poll until the run reaches a terminal state (renders + auto-diffs finish)
-        const run = await this.#pollRun(runId);
-
-        if (run.status === 'error') {
-          throw new Error(
-            `Snap baseline run ${runId} ended with status "error" — cannot publish baseline. ` +
-            `Check the snap dashboard for capture error details.`
+        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.'
           );
         }
 
-        const captures = run.captures ?? [];
-        const rendered = captures.filter((c) => c.currentObjectKey);
+        // 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, undefined, operation);
 
-        if (rendered.length === 0) {
+        if (run.id && run.id !== runId) {
           throw new Error(
-            `Snap baseline run ${runId} completed but no captures produced a screenshot ` +
-            `(${captures.length} capture(s) found, 0 rendered). Cannot publish an empty baseline.`
+            `Cannot publish a complete Snap baseline: requested source run ${runId}, but Snap returned ${run.id}.`
           );
         }
 
-        if (rendered.length < captures.length) {
-          const failed = captures.length - rendered.length;
-          process.stderr.write(
-            `[SnapDrift] Warning: ${failed} of ${captures.length} capture(s) did not produce ` +
-            `a screenshot and will be excluded from the baseline.\n`
+        // Hosted baseline runs intentionally use `new` because they omit a
+        // baseline comparison. The server accepts a wider terminal set for
+        // legacy/intentional workflows, but this client is stricter: any other
+        // terminal status means the baseline capture did not establish fresh
+        // ground truth.
+        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.'
           );
         }
 
-        // Build a manifest from the rendered captures
-        const routes = rendered.map((c) => ({
-            routeId: c.routeId,
-            routePath: c.routePath,
-            viewportDescriptorJson: c.viewportDescriptorJson,
-            objectKey: c.currentObjectKey
-          }));
+        const routes = validateCompleteBaselineRun(metadata, run, this.#projectId);
 
         const manifestJson = JSON.stringify({
           schemaVersion: 1,
           sourceRunId: runId,
+          publicationWorkflowRef: metadata.publicationWorkflowRef,
           routes
         });
 
-        const baselineId = `bsl_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+        const baselineId = baselineIdForRun(runId);
         await this.#request(
           'POST',
           `/v1/visual/projects/${this.#projectId}/baselines`,
           {
             id: baselineId,
-            ...resolveGitRef(),
+            refBranch: metadata.refBranch,
+            refSha: metadata.refSha,
+            publicationMode: 'complete',
+            sourceRunId: runId,
             manifestJson,
             captureProfileJson: JSON.stringify(this.#buildCaptureProfile())
           },
-          idempotencyKey
+          idempotencyKey,
+          operation
         );
 
         const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-baseline-'));
@@ -576,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');
@@ -614,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}
    */
@@ -634,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) {
@@ -678,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) {
@@ -750,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[]} */
@@ -780,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({
@@ -912,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) {
@@ -944,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,
@@ -952,7 +1789,11 @@ export class SnapProvider {
    *   config: VisualRegressionConfig,
    *   routes: VisualRegressionConfig['routes'],
    *   selectedRouteIds: string[],
-   *   purpose: 'baseline' | 'diff'
+   *   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
    * @returns {Promise<CaptureResult>}
    */
@@ -981,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 === 'baseline' ? null : await this.#resolveLatestBaselineId();
+    const baselineId = options.purpose === 'diff' ? await this.#resolveLatestBaselineId(operation) : null;
 
     await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
       id: runId,
@@ -994,15 +1836,25 @@ export class SnapProvider {
       ...(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 === 'baseline' ? { skipBaselineResolution: true } : {}),
-      ...this.#gitRunContext()
-    }, this.#generateIdempotencyKey());
+      ...(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
+    }, this.#generateIdempotencyKey(), operation);
 
     for (const { route, manifestEntry } of uploads) {
       const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
-      const viewportDescriptor = typeof route.viewport === 'string'
-        ? (VIEWPORT_PRESETS[route.viewport] ?? { width: 1280, height: 720 })
-        : route.viewport;
+      const viewportDescriptor = resolveViewportDescriptor(route.viewport);
 
       await this.#request('POST', `/v1/visual/runs/${runId}/captures`, {
         id: captureId,
@@ -1014,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);
@@ -1023,7 +1875,7 @@ export class SnapProvider {
         imageBase64: imageBytes.toString('base64'),
         width: manifestEntry.width,
         height: manifestEntry.height
-      }, this.#generateIdempotencyKey());
+      }, this.#generateIdempotencyKey(), operation);
     }
 
     const snapResults = {
@@ -1032,6 +1884,11 @@ export class SnapProvider {
       captureMode: 'local-upload',
       runId,
       projectId: this.#projectId,
+      purpose: options.purpose,
+      ...(options.baselineRef ? options.baselineRef : {}),
+      configuredRouteIds: options.configuredRouteIds,
+      selectedRouteIds: options.selectedRouteIds,
+      expectedCaptures: options.expectedCaptures,
       snapStartedAt: new Date().toISOString()
     };
     await fs.writeFile(localCapture.resultsPath, JSON.stringify(snapResults, null, 2));
@@ -1039,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
@@ -1210,33 +1924,125 @@ 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) {
-    const startTime = Date.now();
-
-    while (Date.now() - startTime < MAX_POLL_DURATION_MS) {
-      const run = await this.#request('GET', `/v1/visual/runs/${runId}`);
+  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 (this.#remainingOperationMs(operation) > 0) {
+      const requestPath = `/v1/visual/runs/${runId}`;
+      const run = await this.#request('GET', requestPath, undefined, undefined, operation);
+      if (!run || typeof run !== 'object' || Array.isArray(run)) {
+        throw errorFactory(`Snap returned a malformed run response for requested run "${runId}".`);
+      }
+      const captures = Array.isArray(run.captures) ? run.captures : [];
+      const completeCaptureSet =
+        expectedCaptureCount === undefined ||
+        (captures.length >= expectedCaptureCount &&
+          captures.every((capture) => TERMINAL_CAPTURE_STATUSES.has(capture?.status)));
+
+      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;
+        }));
+        if (signature === incompleteSignature) stableIncompletePolls += 1;
+        else {
+          incompleteSignature = signature;
+          stableIncompletePolls = 0;
+        }
+        // A server-side run can remain rendering forever after a cancelled
+        // worker. Do not spend the full ten-minute poll budget on a capture set
+        // that has made no progress for roughly one minute.
+        if (stableIncompletePolls >= MAX_STABLE_INCOMPLETE_POLLS) return run;
+      } else {
+        incompleteSignature = undefined;
+        stableIncompletePolls = 0;
+      }
 
       if (TERMINAL_RUN_STATUSES.has(run.status)) {
-        return run;
+        if (expectedCaptureCount === undefined || run.status === 'error') {
+          return run;
+        }
+
+        if (completeCaptureSet) return run;
+        // 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 (signature === incompleteTerminalSignature) stableIncompleteTerminalPolls += 1;
+          else {
+            incompleteTerminalSignature = signature;
+            stableIncompleteTerminalPolls = 0;
+          }
+          // A stable terminal subset cannot make render progress. Return it for
+          // precise fail-closed count validation instead of waiting ten minutes.
+          if (stableIncompleteTerminalPolls >= 2) return run;
+        } else {
+          incompleteTerminalSignature = undefined;
+          stableIncompleteTerminalPolls = 0;
+        }
       }
 
-      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;
@@ -1254,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
@@ -1346,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,