snapdrift 0.12.0 → 0.14.0

package/lib/outage-policy.mjs

@@ -73,10 +73,21 @@ function createBaselineLookupFallbackError(outageError, phase, lookupMessage) {
  * @returns {boolean}
  */
 export function hasLocalScreenshots(providerName, config) {
-  if (providerName !== 'snap') {
-    return true;
-  }
-  return isLocalBaseUrl(config?.baseUrl);
+  return describeCaptureArtifacts(providerName, undefined, config).localScreenshots;
+}
+
+/**
+ * Prefer provider-returned artifacts; infer capabilities only for legacy results.
+ *
+ * @param {string} providerName
+ * @param {Partial<CaptureResult>} [result]
+ * @param {VisualRegressionConfig} [config]
+ * @returns {{ localScreenshots: boolean, artifactsRoot?: string }}
+ */
+export function describeCaptureArtifacts(providerName, result, config) {
+  if (result?.artifacts) return result.artifacts;
+  const localScreenshots = providerName !== 'snap' || isLocalBaseUrl(config?.baseUrl);
+  return { localScreenshots, artifactsRoot: localScreenshots ? result?.screenshotsRoot : undefined };
 }
 
 /**
@@ -97,7 +108,8 @@ export function hasLocalScreenshots(providerName, config) {
  *   outcome: 'captured' | 'skipped',
  *   providerName: string,
  *   result?: CaptureResult,
- *   localScreenshots: boolean
+ *   localScreenshots: boolean,
+ *   artifacts: ReturnType<typeof describeCaptureArtifacts>
  * }>}
  */
 export async function captureWithPolicy(options) {
@@ -108,16 +120,18 @@ export async function captureWithPolicy(options) {
 
   try {
     const result = await options.provider.capture(options.captureOptions);
+    const artifacts = describeCaptureArtifacts(providerName, result, options.config);
     return {
       outcome: 'captured',
       providerName,
       result,
-      localScreenshots: hasLocalScreenshots(providerName, options.config)
+      artifacts,
+      localScreenshots: artifacts.localScreenshots
     };
   } catch (error) {
     if (error instanceof SnapSkipError) {
       onSkip(error);
-      return { outcome: 'skipped', providerName, localScreenshots: false };
+      return { outcome: 'skipped', providerName, localScreenshots: false, artifacts: { localScreenshots: false } };
     }
     if (error instanceof SnapFallbackError) {
       onFallback(error);
@@ -127,7 +141,8 @@ export async function captureWithPolicy(options) {
       const result = await createLocalProvider().capture(options.captureOptions);
       // The rest of the pipeline must be told the *effective* provider, not the
       // configured one — otherwise it rebuilds SnapProvider around local output.
-      return { outcome: 'captured', providerName: 'local', result, localScreenshots: true };
+      const artifacts = describeCaptureArtifacts('local', result, options.config);
+      return { outcome: 'captured', providerName: 'local', result, localScreenshots: artifacts.localScreenshots, artifacts };
     }
     throw error;
   }
@@ -147,12 +162,19 @@ export async function captureWithPolicy(options) {
  *    does not, so we recapture locally first rather than diffing a manifest of
  *    zero-dimension placeholders.
  *
+ * Capability precedence: legacy `localScreenshots` overrides `artifacts`, then
+ * `captureResult.artifacts`, then provider/config inference. Without any of those
+ * inputs (including config), preserve the legacy local-screenshots default.
+ *
  * @param {{
  *   provider: VisualProvider,
  *   providerName?: string,
  *   diffOptions: DiffOptions,
+ *   captureResult?: CaptureResult,
  *   captureOptions?: CaptureOptions,
  *   localScreenshots?: boolean,
+ *   artifacts?: ReturnType<typeof describeCaptureArtifacts>,
+ *   config?: VisualRegressionConfig,
  *   baselineAvailable?: boolean,
  *   createLocalProvider?: () => VisualProvider,
  *   onSkip?: (error: SnapSkipError) => void,
@@ -166,11 +188,23 @@ export async function captureWithPolicy(options) {
  *   outcome: 'diffed' | 'skipped' | 'baseline-unavailable',
  *   providerName: string,
  *   result?: DiffResult,
- *   recapture?: CaptureResult
+ *   recapture?: CaptureResult,
+ *   localScreenshots: boolean,
+ *   artifacts: ReturnType<typeof describeCaptureArtifacts>
  * }>}
  */
 export async function diffWithPolicy(options) {
   const providerName = options.providerName || 'local';
+  /** @type {Partial<CaptureResult>} */
+  const captureResult = options.captureResult || { screenshotsRoot: options.diffOptions.currentRunDir };
+  const described = options.artifacts || (captureResult.artifacts || options.config
+    ? describeCaptureArtifacts(providerName, captureResult, options.config)
+    : { localScreenshots: true, artifactsRoot: captureResult.screenshotsRoot });
+  let artifacts = {
+    ...described,
+    localScreenshots: options.localScreenshots ?? described.localScreenshots
+  };
+  if (!artifacts.localScreenshots) artifacts.artifactsRoot = undefined;
   const createLocalProvider = options.createLocalProvider || (() => createProvider('local'));
   const onSkip = options.onSkip || noop;
   const onFallback = options.onFallback || noop;
@@ -179,11 +213,11 @@ export async function diffWithPolicy(options) {
 
   try {
     const result = await options.provider.diff(options.diffOptions);
-    return { outcome: 'diffed', providerName, result };
+    return { outcome: 'diffed', providerName, result, artifacts, localScreenshots: artifacts.localScreenshots };
   } catch (error) {
     if (error instanceof SnapSkipError) {
       onSkip(error);
-      return { outcome: 'skipped', providerName };
+      return { outcome: 'skipped', providerName, artifacts, localScreenshots: artifacts.localScreenshots };
     }
     if (!(error instanceof SnapFallbackError)) {
       throw error;
@@ -199,7 +233,7 @@ export async function diffWithPolicy(options) {
       if (options.baselineResolutionStatus === 'error') {
         throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
       }
-      return { outcome: 'baseline-unavailable', providerName: 'local' };
+      return { outcome: 'baseline-unavailable', providerName: 'local', artifacts, localScreenshots: artifacts.localScreenshots };
     }
 
     if (options.baselineResolutionStatus === 'error') {
@@ -211,7 +245,7 @@ export async function diffWithPolicy(options) {
     /** @type {CaptureResult | undefined} */
     let recapture;
 
-    if (options.localScreenshots === false) {
+    if (!artifacts.localScreenshots) {
       if (!options.captureOptions) {
         throw new Error(
           'Cannot fall back to a local diff: the current capture has no screenshots on disk ' +
@@ -221,6 +255,7 @@ export async function diffWithPolicy(options) {
       }
       onRecapture();
       recapture = await localProvider.capture(options.captureOptions);
+      artifacts = describeCaptureArtifacts('local', recapture, options.config);
       diffOptions = {
         ...options.diffOptions,
         currentResultsPath: recapture.resultsPath,
@@ -230,7 +265,7 @@ export async function diffWithPolicy(options) {
     }
 
     const result = await localProvider.diff(diffOptions);
-    return { outcome: 'diffed', providerName: 'local', result, recapture };
+    return { outcome: 'diffed', providerName: 'local', result, recapture, artifacts, localScreenshots: artifacts.localScreenshots };
   }
 }
 

package/lib/provider.mjs

@@ -35,7 +35,8 @@ export class LocalProvider {
    * @returns {Promise<CaptureResult>}
    */
   async capture(options) {
-    return runBaselineCapture(options);
+    const result = await runBaselineCapture(options);
+    return { ...result, artifacts: { localScreenshots: true, artifactsRoot: result.screenshotsRoot } };
   }
 
   /**
@@ -58,6 +59,7 @@ export class LocalProvider {
   /**
    * @param {FetchBaselineOptions} _options
    * @returns {Promise<never>}
+   * Guard with providerSupports(providerName, 'fetchLatestBaseline') before calling.
    * @throws {Error} Not yet implemented for LocalProvider.
    *   Use the pr-diff action for baseline resolution, or wait for a future release.
    */
@@ -80,6 +82,22 @@ export class LocalProvider {
   }
 }
 
+export const PROVIDER_CAPABILITIES = Object.freeze({
+  local: Object.freeze({ capture: true, diff: true, publishBaseline: true, fetchLatestBaseline: false, buildCommentBody: true }),
+  snap: Object.freeze({ capture: true, diff: true, publishBaseline: true, fetchLatestBaseline: true, buildCommentBody: true })
+});
+
+/**
+ * @param {string} providerName
+ * @param {string} capability
+ * @returns {boolean}
+ */
+export function providerSupports(providerName, capability) {
+  return Object.hasOwn(PROVIDER_CAPABILITIES, providerName) &&
+    Object.hasOwn(PROVIDER_CAPABILITIES[providerName], capability) &&
+    PROVIDER_CAPABILITIES[providerName][capability] === true;
+}
+
 /** @type {{ local: (config?: VisualRegressionConfig) => LocalProvider, snap: (config: VisualRegressionConfig) => SnapProvider }} */
 const PROVIDER_FACTORIES = {
   local: () => new LocalProvider(),

package/lib/snap-provider.mjs

@@ -10,6 +10,7 @@ import path from 'node:path';
 
 import { makeMarkdown, buildReportCommentBody } from '@snapdrift/adapter-report-md';
 import { loadSnapdriftConfig, runBaselineCapture } from '@snapdrift/adapter-fs';
+import { COMPARISON_FALLBACK_REASONS, COMPARISON_ROW_KINDS } from '@snapdrift/compare-core';
 import {
   selectConfiguredRoutes,
   splitCommaList,
@@ -148,7 +149,7 @@ function hostedDiffError(detail) {
 function isComparisonPolicy(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const policy = /** @type {Record<string, any>} */ (value);
-  return policy.version === 1 && typeof policy.threshold === 'number' && Number.isFinite(policy.threshold) && policy.threshold >= 0 && policy.threshold <= 1;
+  return (policy.version === 1 || policy.version === 2) && typeof policy.threshold === 'number' && Number.isFinite(policy.threshold) && policy.threshold >= 0 && policy.threshold <= 1;
 }
 
 /** @param {unknown} value @returns {value is ComparisonMetadata} */
@@ -170,15 +171,66 @@ function isComparisonMetadata(value) {
     return false;
   }
   const [baseline, current, canvas] = dimensions;
-  return (
+  const baseMetadataValid = (
     typeof comparison.dimensionsChanged === 'boolean' &&
     comparison.dimensionsChanged === (baseline.width !== current.width || baseline.height !== current.height) &&
-    canvas.width === Math.max(baseline.width, current.width) &&
-    canvas.height === Math.max(baseline.height, current.height) &&
     Number.isInteger(comparison.totalPixels) &&
-    comparison.totalPixels >= 0 &&
-    comparison.totalPixels <= canvas.width * canvas.height
+    comparison.totalPixels >= 0
   );
+  if (!baseMetadataValid) return false;
+  if (comparison.policyVersion !== undefined && comparison.policyVersion !== 2) return false;
+
+  if (comparison.policyVersion !== 2) {
+    if (comparison.mode !== undefined || comparison.rowMapping !== undefined || comparison.fallbackReason !== undefined) {
+      return false;
+    }
+    return (
+      canvas.width === Math.max(baseline.width, current.width) &&
+      canvas.height === Math.max(baseline.height, current.height) &&
+      comparison.totalPixels <= canvas.width * canvas.height
+    );
+  }
+
+  if (comparison.mode === 'coordinate-fallback') {
+    return (
+      comparison.rowMapping === undefined &&
+      COMPARISON_FALLBACK_REASONS.includes(comparison.fallbackReason) &&
+      canvas.width === Math.max(baseline.width, current.width) &&
+      canvas.height === Math.max(baseline.height, current.height) &&
+      comparison.totalPixels <= canvas.width * canvas.height
+    );
+  }
+
+  if (comparison.mode !== 'vertical-aligned' || comparison.fallbackReason !== undefined || !Array.isArray(comparison.rowMapping) || baseline.width !== current.width || canvas.width !== baseline.width) {
+    return false;
+  }
+  let outputStart = 0;
+  let baselineStart = 0;
+  let currentStart = 0;
+  for (const segment of comparison.rowMapping) {
+    if (!segment || !COMPARISON_ROW_KINDS.includes(segment.kind) || !Number.isInteger(segment.outputStart) || segment.outputStart !== outputStart || !Number.isInteger(segment.length) || segment.length <= 0) {
+      return false;
+    }
+    const hasBaseline = segment.kind === 'matched' || segment.kind === 'changed' || segment.kind === 'deleted';
+    const hasCurrent = segment.kind === 'matched' || segment.kind === 'changed' || segment.kind === 'inserted';
+    if (hasBaseline !== (Number.isInteger(segment.baselineStart)) || hasCurrent !== (Number.isInteger(segment.currentStart))) {
+      return false;
+    }
+    if (
+      (hasBaseline && segment.baselineStart !== baselineStart) ||
+      (!hasBaseline && segment.baselineStart !== undefined) ||
+      (hasCurrent && segment.currentStart !== currentStart) ||
+      (!hasCurrent && segment.currentStart !== undefined)
+    ) {
+      return false;
+    }
+    if (hasBaseline && (segment.baselineStart < 0 || segment.baselineStart + segment.length > baseline.height)) return false;
+    if (hasCurrent && (segment.currentStart < 0 || segment.currentStart + segment.length > current.height)) return false;
+    outputStart += segment.length;
+    if (hasBaseline) baselineStart += segment.length;
+    if (hasCurrent) currentStart += segment.length;
+  }
+  return canvas.height === outputStart && baselineStart === baseline.height && currentStart === current.height && canvas.height >= Math.max(baseline.height, current.height) && canvas.height <= baseline.height + current.height && comparison.totalPixels === canvas.width * canvas.height;
 }
 
 /**
@@ -221,12 +273,17 @@ function comparisonFromCapture(capture) {
   return isComparisonMetadata(candidate) ? candidate : undefined;
 }
 
+/** @param {ComparisonMetadata} comparison @param {ComparisonPolicy} expected */
+function comparisonMatchesPolicy(comparison, expected) {
+  return expected.version === 2 ? comparison.policyVersion === 2 : comparison.policyVersion === undefined;
+}
+
 /** @param {unknown} actual @param {ComparisonPolicy} expected @param {string} context */
 function assertComparisonPolicyAcknowledged(actual, expected, context) {
-  if (!isComparisonPolicy(actual) || actual.threshold !== expected.threshold) {
+  if (!isComparisonPolicy(actual) || actual.version !== expected.version || actual.threshold !== expected.threshold) {
     throw new SnapUpgradeRequiredError(
-      `${context} did not acknowledge comparisonPolicy v1 with threshold ${expected.threshold}. ` +
-        'Upgrade the Snap server before enabling unequal-dimension comparisons.'
+      `${context} did not acknowledge comparisonPolicy v${expected.version} with threshold ${expected.threshold}. ` +
+        'Upgrade the Snap server before enabling this comparison policy.'
     );
   }
 }
@@ -948,6 +1005,7 @@ export class SnapProvider {
       resultsPath,
       manifestPath,
       screenshotsRoot: outDir,
+      artifacts: { localScreenshots: false, artifactsRoot: undefined },
       selectedRouteIds
     };
   }
@@ -1963,7 +2021,7 @@ export class SnapProvider {
     };
     await fs.writeFile(localCapture.resultsPath, JSON.stringify(snapResults, null, 2));
 
-    return localCapture;
+    return { ...localCapture, artifacts: { localScreenshots: true, artifactsRoot: localCapture.screenshotsRoot } };
   }
 
   /**
@@ -2246,7 +2304,18 @@ export class SnapProvider {
           expected.routePath,
           expected.viewport,
           `Snap capture "${expected.routeId}" is missing complete comparison metadata; ` +
-            'upgrade the Snap server and diff Lambda before enabling comparisonPolicy v1.'
+            `upgrade the Snap server and diff Lambda before enabling comparisonPolicy v${comparisonPolicy.version}.`
+        );
+        continue;
+      }
+
+      if (comparisonPolicy && comparison && !comparisonMatchesPolicy(comparison, comparisonPolicy)) {
+        addError(
+          expected.routeId,
+          expected.routePath,
+          expected.viewport,
+          `Snap capture "${expected.routeId}" returned comparison metadata for a different policy than v${comparisonPolicy.version}; ` +
+            'upgrade the Snap server and diff Lambda before enabling this comparison policy.'
         );
         continue;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -81,6 +81,7 @@
     "./lib/cli.mjs": "./lib/cli.mjs",
     "./lib/provider.mjs": "./lib/provider.mjs",
     "./lib/outage-policy.mjs": "./lib/outage-policy.mjs",
+    "./lib/github-requests.mjs": "./lib/github-requests.mjs",
     "./lib/snap-provider.mjs": "./lib/snap-provider.mjs",
      "./lib/migrate-baselines.mjs": "./lib/migrate-baselines.mjs",
      "./lib/init-from-action.mjs": "./lib/init-from-action.mjs",
@@ -102,10 +103,10 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@snapdrift/adapter-fs": "^1.3.0",
-    "@snapdrift/adapter-report-md": "^1.2.1",
-    "@snapdrift/compare-core": "^1.3.0",
-    "@snapdrift/manifest": "^1.4.0",
+    "@snapdrift/adapter-fs": "^1.5.0",
+    "@snapdrift/adapter-report-md": "^1.4.0",
+    "@snapdrift/compare-core": "^1.5.0",
+    "@snapdrift/manifest": "^1.6.0",
     "js-yaml": "^5.4.0",
     "playwright": "^1.59.1",
     "pngjs": "^7.0.0"

package/types/visual-diff-types.d.ts

@@ -15,11 +15,19 @@ export interface VisualRegressionSelectionConfig {
   sharedExact?: string[];
 }
 
-export interface ComparisonPolicy {
+/** @deprecated Coordinate-based comparison policy. Retained for existing configurations; use `ComparisonPolicyV2` for new configurations. */
+export interface ComparisonPolicyV1 {
   version: 1;
   threshold: number;
 }
 
+export interface ComparisonPolicyV2 {
+  version: 2;
+  threshold: number;
+}
+
+export type ComparisonPolicy = ComparisonPolicyV1 | ComparisonPolicyV2;
+
 export interface ComparisonDimensions {
   width: number;
   height: number;
@@ -31,6 +39,22 @@ export interface ComparisonMetadata {
   canvas: ComparisonDimensions;
   dimensionsChanged: boolean;
   totalPixels: number;
+  policyVersion?: 2;
+  mode?: 'vertical-aligned' | 'coordinate-fallback';
+  rowMapping?: ComparisonRowMapping[];
+  fallbackReason?: ComparisonFallbackReason;
+}
+
+export type ComparisonFallbackReason = 'width-mismatch' | 'alignment-limit' | 'ambiguous' | 'verification-failed' | 'ignore-regions';
+export const COMPARISON_FALLBACK_REASONS: readonly ['width-mismatch', 'alignment-limit', 'ambiguous', 'verification-failed', 'ignore-regions'];
+export type ComparisonRowKind = 'matched' | 'changed' | 'inserted' | 'deleted';
+export const COMPARISON_ROW_KINDS: readonly ['matched', 'changed', 'inserted', 'deleted'];
+export interface ComparisonRowMapping {
+  outputStart: number;
+  length: number;
+  kind: ComparisonRowKind;
+  baselineStart?: number;
+  currentStart?: number;
 }
 
 export interface VisualRegressionRouteConfig {
@@ -52,6 +76,7 @@ export interface VisualRegressionConfig {
   diff: {
     threshold: number;
     mode: 'report-only' | 'fail-on-changes' | 'fail-on-incomplete' | 'strict';
+    /** Deprecated v1 remains the compatibility default; new configurations should use v2. */
     comparisonPolicy?: ComparisonPolicy;
   };
   selection?: VisualRegressionSelectionConfig;
@@ -110,7 +135,7 @@ export interface SnapRunMetadata {
   runId: string;
   projectId: string;
   purpose: 'baseline' | 'capture' | 'diff';
-  /** Exact comparison policy acknowledged by Snap for updated clients. */
+  /** Exact comparison policy acknowledged by Snap; v1 is deprecated for compatibility. */
   comparisonPolicy?: ComparisonPolicy;
   /** CI source branch for hosted baseline runs; omitted for ordinary diff runs. */
   refBranch?: string;
@@ -192,7 +217,9 @@ export interface VisualDiffSummary {
   changed: VisualDiffChangedItem[];
   missing: VisualDiffMissingItem[];
   errors: VisualDiffErrorItem[];
+  captureCompatibility?: import('@snapdrift/manifest').CaptureCompatibility;
   dimensionChanges: VisualDiffDimensionItem[];
+  /** The exact policy used for the comparison; v1 is deprecated and retained for compatibility. */
   comparisonPolicy?: ComparisonPolicy;
   message?: string;
   /** Link to the provider's run detail page. Set by SnapProvider during diff(); undefined for LocalProvider. */