snapdrift 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.2.1 - 2026-04-13
+
+### Infrastructure
+
+- **Integration test for compare → stage pipeline** — `tests/integration/capture-compare-pipeline.test.js` exercises the full `generateDriftReport → stageArtifacts` data flow with synthetic PNG fixtures (no live browser needed), catching interface mismatches between modules that unit tests alone would miss.
+
+### Features
+
+- **Configurable PR comment truncation limits** — `actions/pr-diff` and `actions/comment` now accept optional `max-changed-rows` (default: 20) and `max-error-rows` (default: 10) inputs, letting teams control how many rows appear in the drift and error tables before the overflow note.
+- **Per-route navigation timeout** — routes now accept an optional `navigationTimeout` (positive integer, ms) that overrides the global 30 000 ms default for that route. Useful for slow SSR pages that need more time or fast static pages that should fail fast.
+- **Baseline refresh workflow template** — `docs/workflow-templates/refresh-baseline-on-merge.yml` is a drop-in workflow template for consumer repos that automatically republishes the SnapDrift baseline on every push to the default branch. Supports an optional label gate to avoid republishing on every push.
+
+### Fixes
+
+- **Baseline refresh template trigger** — switched from `pull_request: closed` to `push` on the default branch so published artifacts are actually discoverable by the baseline resolver in `actions/pr-diff`, which hardcodes `event:'push'` when querying workflow runs.
+- **Artifact action pins** — `actions/upload-artifact` and `actions/download-artifact` in composite action YAMLs are now pinned to v7 SHAs, matching the CI workflow (the v0.2.0 changelog noted this upgrade but only the CI workflow was updated at the time).
+- **Stale version references** — README and integration guide examples now reference `@v0.2.1` instead of the outdated `@v0.1.0`. README "Current constraints" updated to reflect custom viewport support.
+
 ## 0.2.0 - 2026-04-08
 
 ### Features

package/README.md

@@ -44,7 +44,7 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift/actions/baseline@v0.1.0
+  uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
   with:
     repo-config-path: .github/snapdrift.json
 ```
@@ -53,7 +53,7 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift/actions/pr-diff@v0.1.0
+  uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
   with:
     github-token: ${{ secrets.GITHUB_TOKEN }}
     repo-config-path: .github/snapdrift.json
@@ -90,7 +90,7 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 
 - Ubuntu runners only
 - Full-page capture only
-- Fixed viewport presets: `desktop` (1440×900) and `mobile` (390×844)
+- Viewport presets: `desktop` (1440×900) and `mobile` (390×844), or custom `{ "width": number, "height": number }`
 - One global `diff.threshold`
 - Dimension shifts are reported separately from pixel drift
 

package/actions/baseline/action.yml

@@ -134,7 +134,7 @@ runs:
         EOF
 
     - if: inputs.upload-artifact == 'true'
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
       with:
         name: ${{ steps.config.outputs.artifact_name }}
         retention-days: ${{ inputs.artifact-retention-days }}

package/actions/comment/action.yml

@@ -20,6 +20,14 @@ inputs:
     description: Artifact label to include in the comment.
     required: false
     default: ''
+  max-changed-rows:
+    description: Maximum number of changed-route rows shown in the PR comment before truncation.
+    required: false
+    default: '20'
+  max-error-rows:
+    description: Maximum number of error rows shown in the PR comment before truncation.
+    required: false
+    default: '10'
 
 runs:
   using: composite
@@ -34,6 +42,8 @@ runs:
         VISUAL_DIFF_RUN_URL: ${{ inputs.run-url }}
         VISUAL_DIFF_ARTIFACT_NAME: ${{ inputs.artifact-name }}
         INPUT_PR_NUMBER: ${{ inputs.pr-number }}
+        MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
+        MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
         github-token: ${{ inputs.github-token }}
         script: |
@@ -59,9 +69,13 @@ runs:
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
           const runUrl = process.env.VISUAL_DIFF_RUN_URL || `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
 
+          const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
+          const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
           const body = buildReportCommentBody(summary, {
             artifactName: process.env.VISUAL_DIFF_ARTIFACT_NAME || '',
-            runUrl
+            runUrl,
+            maxChangedRows,
+            maxErrorRows
           });
 
           const comments = await github.paginate(github.rest.issues.listComments, {

package/actions/pr-diff/action.yml

@@ -45,6 +45,14 @@ inputs:
     description: Whether to publish the SnapDrift PR report.
     required: false
     default: 'true'
+  max-changed-rows:
+    description: Maximum number of changed-route rows shown in the PR comment before truncation.
+    required: false
+    default: '20'
+  max-error-rows:
+    description: Maximum number of error rows shown in the PR comment before truncation.
+    required: false
+    default: '10'
 
 outputs:
   should-run:
@@ -254,7 +262,7 @@ runs:
           }
 
     - if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found == 'true'
-      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
       with:
         github-token: ${{ inputs.github-token }}
         repository: ${{ inputs.baseline-repository || github.repository }}
@@ -467,7 +475,7 @@ runs:
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
         EOF
 
-    - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+    - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
       with:
         name: ${{ steps.context.outputs.artifact_name }}
         retention-days: ${{ inputs.artifact-retention-days }}
@@ -490,6 +498,8 @@ runs:
         SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
         ARTIFACT_NAME: ${{ steps.context.outputs.artifact_name }}
         RUN_URL: ${{ steps.context.outputs.run_url }}
+        MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
+        MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
         github-token: ${{ inputs.github-token }}
         script: |
@@ -525,9 +535,13 @@ runs:
           const { buildReportCommentBody } = await import(pathToFileURL(modulePath));
 
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
+          const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
+          const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
           const body = buildReportCommentBody(summary, {
             artifactName: process.env.ARTIFACT_NAME || '',
-            runUrl: process.env.RUN_URL || ''
+            runUrl: process.env.RUN_URL || '',
+            maxChangedRows,
+            maxErrorRows
           });
 
           const comments = await github.paginate(github.rest.issues.listComments, {

package/actions/resolve-baseline/action.yml

@@ -135,7 +135,7 @@ runs:
           }
 
     - if: steps.resolve.outputs.found == 'true'
-      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
       with:
         github-token: ${{ inputs.github-token }}
         repository: ${{ inputs.repository || github.repository }}

package/docs/contracts.md

@@ -26,6 +26,7 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 | `path` | `string` | URL path appended to `baseUrl` |
 | `viewport` | `string` or `object` | Preset name (`"desktop"`, `"mobile"`) or a custom object `{ "width": number, "height": number }` |
 | `changePaths` | `string[]` | Optional prefixes used for changed-file scoping |
+| `navigationTimeout` | `number` | Optional per-route navigation timeout in ms (overrides the 30 000 ms global default) |
 
 ### Optional fields
 

package/docs/integration-guide.md

@@ -46,7 +46,7 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift/actions/baseline@v0.1.0
+  uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
   with:
     repo-config-path: .github/snapdrift.json
     artifact-retention-days: '30'
@@ -70,7 +70,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift/actions/pr-diff@v0.1.0
+  uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
   with:
     github-token: ${{ secrets.GITHUB_TOKEN }}
     repo-config-path: .github/snapdrift.json
@@ -111,7 +111,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.1.0
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
@@ -150,7 +150,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.1.0
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
@@ -178,6 +178,8 @@ jobs:
 | `baseline-workflow-id` | Override the baseline workflow id |
 | `baseline-branch` | Override the baseline branch |
 | `comment-on-pr` | Set to `false` to suppress the PR report |
+| `max-changed-rows` | Max changed-route rows shown before truncation (default: `20`) |
+| `max-error-rows` | Max error rows shown before truncation (default: `10`) |
 
 ## Low-level actions
 
@@ -207,6 +209,20 @@ The CLI reads the same `.github/snapdrift.json` config used by the Actions workf
 
 See the [Local CLI guide](local-cli.md) for full command reference, flags, directory layout, and examples.
 
+## Refresh the baseline automatically
+
+After an intentional layout change or dimension shift merges, the baseline must be republished before SnapDrift can compare like-for-like frames again. Without automation, this is a manual step.
+
+Use the provided workflow template to refresh the baseline automatically on every push to your default branch (i.e. every merge):
+
+**`docs/workflow-templates/refresh-baseline-on-merge.yml`**
+
+Drop a copy into your repo at `.github/workflows/snapdrift-refresh-baseline.yml`, then fill in the `TODO` blocks with your app's build and start steps — the same steps you use in your PR workflow. The template uses a `push` trigger on the default branch so published artifacts are discoverable by the baseline resolver in `actions/pr-diff`.
+
+### Label-gated refreshes
+
+If you don't want to republish the baseline on every push, the template includes a commented `if` condition that gates on a label (e.g. `snapdrift:refresh-baseline`). A preceding job can check the most recent merged PR for the label and set an output to control whether the baseline refresh runs.
+
 ## Troubleshooting
 
 **"No non-expired SnapDrift baseline artifact was found"**  

package/docs/workflow-templates/refresh-baseline-on-merge.yml

@@ -0,0 +1,82 @@
+# SnapDrift — Baseline Refresh on Merge
+#
+# Drop this file into your consumer repo at:
+#   .github/workflows/snapdrift-refresh-baseline.yml
+#
+# What it does:
+#   Automatically re-publishes the SnapDrift baseline on every push to your
+#   default branch. Since merging a PR produces a push event, this keeps the
+#   baseline in sync after intentional layout changes, dimension shifts, or
+#   any other UI refactor lands.
+#
+# Prerequisites:
+#   - A working `.github/snapdrift.json` in your repo
+#   - The same build + start steps used in your PR workflow
+#
+# Uses a push trigger so published artifacts are discoverable by the baseline
+# resolver in actions/pr-diff (which filters on event: 'push'). A merge into
+# the default branch produces a push event, so this fires exactly when needed.
+#
+# Optional — refresh only on a specific label:
+#   If you don't want to refresh on every push, you can gate on a label applied
+#   before merging. Use the pull_request: labeled event in a separate workflow to
+#   set an output, or simply restrict this workflow to specific paths.
+#   See the commented block below for a label-based gate using a preceding job.
+
+name: SnapDrift Refresh Baseline
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  actions: write   # required to upload the baseline artifact
+
+jobs:
+  refresh-baseline:
+    # Optional: gate on a label to avoid refreshing on every push.
+    # Requires a preceding job that checks for the label on the most recent
+    # merged PR and sets an output. Replace "snapdrift:refresh-baseline" with
+    # your label name.
+    # if: needs.check-label.outputs.refresh == 'true'
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # ── TODO: add your app's build + dependency steps here ──────────────────
+      # Example for a Node app:
+      #
+      # - uses: actions/setup-node@v4
+      #   with:
+      #     node-version: '22'
+      #     cache: npm
+      # - run: npm ci
+      # - run: npm run build
+      # ────────────────────────────────────────────────────────────────────────
+
+      # ── TODO: start your app and wait for it to be ready ────────────────────
+      # SnapDrift needs a running server to capture screenshots.
+      # Replace the URL and port to match your app's baseUrl from snapdrift.json.
+      #
+      # - name: Start app
+      #   run: |
+      #     npm start &
+      #     for i in $(seq 1 45); do
+      #       curl -sf http://127.0.0.1:8080 && break || sleep 1
+      #     done
+      # ────────────────────────────────────────────────────────────────────────
+
+      - name: Publish SnapDrift baseline
+        uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
+        with:
+          repo-config-path: .github/snapdrift.json
+          artifact-retention-days: '30'
+
+      # ── TODO: shut down your app if needed ───────────────────────────────────
+      # - name: Stop app
+      #   if: always()
+      #   run: pkill -f "npm start" || true
+      # ────────────────────────────────────────────────────────────────────────

package/lib/capture-routes.mjs

@@ -132,7 +132,7 @@ async function captureRoute(context, route, baseUrl, screenshotsRoot) {
     const targetUrl = new URL(route.path, baseUrl).toString();
     await page.goto(targetUrl, {
       waitUntil: 'networkidle',
-      timeout: SNAPDRIFT_NAVIGATION_TIMEOUT_MS
+      timeout: route.navigationTimeout ?? SNAPDRIFT_NAVIGATION_TIMEOUT_MS
     });
     await page.waitForTimeout(SNAPDRIFT_SETTLE_DELAY_MS);
 

package/lib/pr-comment.mjs

@@ -32,10 +32,12 @@ const STATUS_LABELS = {
 
 /**
  * @param {Record<string, unknown>} summary
- * @param {{ artifactName?: string, runUrl?: string }} [meta]
+ * @param {{ artifactName?: string, runUrl?: string, maxChangedRows?: number, maxErrorRows?: number }} [meta]
  * @returns {string}
  */
 export function buildReportCommentBody(summary, meta = {}) {
+  const maxChangedRows = meta.maxChangedRows ?? 20;
+  const maxErrorRows = meta.maxErrorRows ?? 10;
   const status = /** @type {string} */ (summary.status) || 'incomplete';
   const statusIcon = STATUS_ICONS[status] || '⚠️';
   const statusLabel = STATUS_LABELS[status] || status;
@@ -66,15 +68,15 @@ export function buildReportCommentBody(summary, meta = {}) {
     lines.push('');
     lines.push('| Route | Viewport | Error |');
     lines.push('|:------|:---------|:------|');
-    for (const item of errors.slice(0, 10)) {
+    for (const item of errors.slice(0, maxErrorRows)) {
       lines.push(`| ${escapeMarkdown(item.id)} | ${escapeMarkdown(item.viewport)} | ${escapeMarkdown(item.message)} |`);
     }
-    if (errorCount > 10) {
+    if (errorCount > maxErrorRows) {
       lines.push('');
       const runLinkSuffix = meta.runUrl && /^https?:\/\//.test(meta.runUrl)
         ? ` — [View full report →](${meta.runUrl})`
         : '';
-      lines.push(`*...and ${errorCount - 10} more*${runLinkSuffix}`);
+      lines.push(`*...and ${errorCount - maxErrorRows} more*${runLinkSuffix}`);
     }
     lines.push('');
     lines.push('</details>');
@@ -87,18 +89,18 @@ export function buildReportCommentBody(summary, meta = {}) {
     lines.push('');
     lines.push('| Route | Viewport | Mismatch |');
     lines.push('|:------|:---------|:---------|');
-    for (const item of changed.slice(0, 20)) {
+    for (const item of changed.slice(0, maxChangedRows)) {
       const percentChanged = typeof item.mismatchRatio === 'number'
         ? `${(item.mismatchRatio * 100).toFixed(2)}%`
         : 'n/a';
       lines.push(`| ${escapeMarkdown(item.id)} | ${escapeMarkdown(item.viewport)} | ${percentChanged} |`);
     }
-    if (changed.length > 20) {
+    if (changed.length > maxChangedRows) {
       lines.push('');
       const runLinkSuffix = meta.runUrl && /^https?:\/\//.test(meta.runUrl)
         ? ` — [View full report →](${meta.runUrl})`
         : '';
-      lines.push(`*...and ${changed.length - 20} more*${runLinkSuffix}`);
+      lines.push(`*...and ${changed.length - maxChangedRows} more*${runLinkSuffix}`);
     }
     lines.push('');
     lines.push('</details>');

package/lib/snapdrift-config.mjs

@@ -156,6 +156,11 @@ export function validateSnapdriftConfig(value, sourceLabel = 'inline config') {
       if (route.changePaths !== undefined && !isNonEmptyStringArray(route.changePaths)) {
         errors.push(`${routeLabel}.changePaths must be an array of non-empty strings when provided.`);
       }
+
+      if (route.navigationTimeout !== undefined &&
+          (!Number.isInteger(route.navigationTimeout) || /** @type {number} */ (route.navigationTimeout) <= 0)) {
+        errors.push(`${routeLabel}.navigationTimeout must be a positive integer when provided.`);
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",

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

@@ -12,6 +12,7 @@ export interface VisualRegressionRouteConfig {
   path: string;
   viewport: VisualViewport;
   changePaths?: string[];
+  navigationTimeout?: number;
 }
 
 export interface VisualRegressionConfig {