snapdrift 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,42 @@
 # Changelog
 
-## Unreleased
+## 0.3.0 - 2026-05-26
+
+### Infrastructure
+
+- **Package extraction (Phase 1a)** — extracted `@snapdrift/manifest` (schema, validation, indexing, viewport presets) and `@snapdrift/compare-core` (pure pixel comparison, ignore-region masking) as standalone npm packages with zero runtime deps beyond `pngjs`.
+- **Package extraction (Phase 1b)** — extracted `@snapdrift/adapter-fs` (all filesystem I/O: capture, compare, config, staging, drift report generation) and `@snapdrift/adapter-report-md` (pure markdown/HTML report generators, zero runtime deps) as standalone npm packages.
+- **Lib/ shim refactor** — all `lib/*.mjs` modules are now thin re-export shims that delegate to packages. `lib/report.mjs` wires the default filesystem `imageReader` for HTML reports. Backward-compatible — all export surfaces preserved.
+- **`generateDiffImage` ignore regions** — `@snapdrift/compare-core` now overlays ignored pixel regions with semi-transparent gray instead of skipping them.
+- **Publish workflow** — `.github/workflows/publish.yml` now publishes all four `@snapdrift/*` workspace packages in dependency order before the root `snapdrift` package.
+
+### Performance
+
+- **Faster screenshot capture** — navigation now waits for `load` instead of `networkidle`, removing a guaranteed ≥500 ms floor per route. A 20-route run saves ~10 s in navigation waits alone.
+- **Concurrent route capture** — routes within the same viewport are now captured in parallel (up to `SNAPDRIFT_CAPTURE_CONCURRENCY` at a time, default 5) rather than sequentially, giving a further 3–5× throughput improvement on multi-route suites.
+- **Deterministic animation handling** — screenshots are taken with `animations: 'disabled'` so Playwright finishes/cancels CSS animations before capture, replacing reliance on the settle delay for animation timing.
+
+### Features
+
+- **`SNAPDRIFT_CAPTURE_CONCURRENCY` env var** — controls the maximum number of routes captured concurrently within a viewport context (positive integer, default `5`). Set to `1` to restore serial-per-viewport behaviour for apps with shared session or auth state.
+
+## 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
 

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
 
@@ -179,9 +180,11 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 | Setting | Value |
 |:--------|:------|
-| Navigation wait | `networkidle` |
+| Navigation wait | `load` |
 | Navigation timeout | 30000ms |
 | Settle delay | 300ms |
+| Screenshot animations | `disabled` (Playwright finishes/cancels CSS animations before capture) |
+| Capture concurrency | 5 routes per viewport (overridable via `SNAPDRIFT_CAPTURE_CONCURRENCY`)|
 
 ## Local CLI directory layout
 
@@ -231,3 +234,4 @@ These are for custom orchestration only. Wrapper actions set them automatically.
 | `SNAPDRIFT_BASELINE_ARTIFACT_NAME` | `compare-results.mjs` | Baseline artifact label to embed in the report |
 | `SNAPDRIFT_BASELINE_SOURCE_SHA` | `compare-results.mjs` | Baseline source SHA to embed in the report |
 | `SNAPDRIFT_ENFORCE_OUTCOME` | `compare-results.mjs` | Set to `0` to disable enforcement in direct CLI usage |
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behaviour for apps with shared session/auth state. |

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
+      # ────────────────────────────────────────────────────────────────────────