snapdrift 0.11.0 → 0.13.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

@@ -46,7 +46,6 @@ const BINARY_REQUEST_TIMEOUT_MS = 120 * 1000;
 const POLL_INTERVAL_MS = 2000;
 const MAX_OPERATION_DURATION_MS = 10 * 60 * 1000;
 const MAX_STABLE_INCOMPLETE_POLLS = 30;
-const MAX_COMPARISON_PIXELS = 32 * 1024 * 1024;
 const BASELINE_RUN_SUCCESS_STATUS = 'new';
 const BASELINE_CAPTURE_SUCCESS_STATUS = 'new';
 const TERMINAL_CAPTURE_STATUSES = new Set(['new', 'diffed', 'error']);
@@ -178,8 +177,7 @@ function isComparisonMetadata(value) {
     canvas.height === Math.max(baseline.height, current.height) &&
     Number.isInteger(comparison.totalPixels) &&
     comparison.totalPixels >= 0 &&
-    comparison.totalPixels <= canvas.width * canvas.height &&
-    canvas.width * canvas.height <= MAX_COMPARISON_PIXELS
+    comparison.totalPixels <= canvas.width * canvas.height
   );
 }
 
@@ -950,6 +948,7 @@ export class SnapProvider {
       resultsPath,
       manifestPath,
       screenshotsRoot: outDir,
+      artifacts: { localScreenshots: false, artifactsRoot: undefined },
       selectedRouteIds
     };
   }
@@ -1965,7 +1964,7 @@ export class SnapProvider {
     };
     await fs.writeFile(localCapture.resultsPath, JSON.stringify(snapResults, null, 2));
 
-    return localCapture;
+    return { ...localCapture, artifacts: { localScreenshots: true, artifactsRoot: localCapture.screenshotsRoot } };
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.11.0",
+  "version": "0.13.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.0",
-    "@snapdrift/compare-core": "^1.2.0",
-    "@snapdrift/manifest": "^1.4.0",
+    "@snapdrift/adapter-fs": "^1.4.0",
+    "@snapdrift/adapter-report-md": "^1.3.0",
+    "@snapdrift/compare-core": "^1.4.0",
+    "@snapdrift/manifest": "^1.5.0",
     "js-yaml": "^5.4.0",
     "playwright": "^1.59.1",
     "pngjs": "^7.0.0"

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

@@ -192,6 +192,7 @@ export interface VisualDiffSummary {
   changed: VisualDiffChangedItem[];
   missing: VisualDiffMissingItem[];
   errors: VisualDiffErrorItem[];
+  captureCompatibility?: import('@snapdrift/manifest').CaptureCompatibility;
   dimensionChanges: VisualDiffDimensionItem[];
   comparisonPolicy?: ComparisonPolicy;
   message?: string;