snapdrift 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.12.0 - 2026-09-16
+
+### Fixes
+
+- **PR comments no longer render `[object Object]` for a viewport.** A viewport is
+  either a preset name or a `{ width, height }` object, and the PR-comment renderer
+  stringified it directly. Hosted diff runs always build the object form, so every
+  hosted report printed the useless placeholder in its Error, Drift signals, and
+  Dimension shifts tables. All three report renderers now share one
+  `formatViewport` helper (exported from `@snapdrift/adapter-report-md`).
+
+### Features
+
+- **`compareImages` accepts a per-call `maxPixels` union-canvas ceiling.**
+  `MAX_COMPARISON_PIXELS` (32 Mi) is a *process memory* bound, not an algorithm
+  property, so callers with a larger envelope — a dedicated diff Lambda — can raise
+  it while callers sharing a small host keep the default. A missing, non-positive,
+  or non-finite value falls back to the default, so the guard cannot be removed by
+  accident. The `ComparisonTooLargeError` message now reports the ceiling that was
+  actually exceeded.
+
+### Documentation
+
+- Document that `migrate-baselines --to snap` is unsupported and point to
+  `snapdrift baseline` as the supported way to seed a hosted project. The
+  integration guide still described the retired upload direction as a working
+  one-shot command, and the contracts reference documented its request body,
+  idempotency, and storage behavior as if it succeeded. Both contradicted the
+  CLI, which has failed the direction since 0.7.0 with a pointer to
+  `snapdrift baseline`.
+- Document the screenshot size budget's memory cost for `maxPixels` callers: the
+  comparison retains both decoded RGBA inputs plus the optional diff canvas, so the
+  floor is roughly 12 bytes per union pixel before PNG overhead (~32-35 measured end
+  to end), and the ceiling should be sized against a measured peak rather than that
+  arithmetic.
+
+### Workspace packages
+
+- `@snapdrift/adapter-report-md` 1.2.1 publishes the `[object Object]` viewport fix;
+  `@snapdrift/compare-core` 1.3.0 publishes the per-call `maxPixels` option and the
+  new size-budget guidance.
+- The root package's dependency floors move to `^1.2.1` (adapter-report-md) and
+  `^1.3.0` (compare-core) so `snapdrift` 0.12.0 actually requires those fixes. A
+  retained lockfile resolution of adapter-report-md 1.2.0 still satisfies `^1.2.0`,
+  so without the floor bump an upgrade of `snapdrift` alone could install the
+  unfixed report renderer.
+
 ## 0.11.0 - 2026-09-14
 
 ### Behavior changes

package/README.md

@@ -48,7 +48,7 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.11.0
+  uses: ranacseruet/snapdrift@v0.12.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
@@ -60,7 +60,7 @@ With `provider: "snap"`, baseline publication is a complete, fail-closed snapsho
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.11.0
+  uses: ranacseruet/snapdrift@v0.12.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}

package/action.yml

@@ -155,7 +155,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@799cfb16ff9d51e57d515cdddd4b329950574ef2 # v0.11.0
+      uses: ranacseruet/snapdrift/actions/baseline@e4b92c2243c6e69594cab7405f68eb58fe94587e # v0.12.0
       with:
         repo-config-path: ${{ inputs.repo-config-path }}
         route-ids: ${{ inputs.route-ids }}
@@ -165,7 +165,7 @@ runs:
     - name: SnapDrift pull request diff
       id: pr-diff
       if: inputs.mode == 'pr-diff'
-      uses: ranacseruet/snapdrift/actions/pr-diff@799cfb16ff9d51e57d515cdddd4b329950574ef2 # v0.11.0
+      uses: ranacseruet/snapdrift/actions/pr-diff@e4b92c2243c6e69594cab7405f68eb58fe94587e # v0.12.0
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/docs/contracts.md

@@ -297,7 +297,29 @@ dimensions.
 
 The comparator reports this condition with the stable error code
 `comparison_too_large` and includes the baseline, current, and union-canvas
-dimensions in the error message. Approximate maximum full-page CSS heights below
+dimensions in the error message. The ceiling that was exceeded is included too,
+since a caller may raise it per call.
+
+`32 × 1024 × 1024` is the *default* ceiling, not an algorithm property. The cost
+is dominated by the decoded images: both RGBA inputs (4 bytes per pixel each) are
+retained plus, when the diff image is rendered (the default), a union-sized diff
+canvas — at least ~12 bytes per union pixel when both inputs approach the union
+dimensions, before PNG decode/encode overhead. Measured end-to-end RSS on real
+full-page captures is ~32-35 bytes per union pixel (~1.16 GB at 33.8 M pixels,
+~3.37 GB at 103.9 M), so the default bounds a comparison to a process with a few
+GB of headroom.
+
+Direct `@snapdrift/compare-core` callers running in a larger memory envelope can
+pass `compareImages(..., { maxPixels })` to raise it for that call. **Size
+`maxPixels` against your own measured peak**, not against the byte-per-pixel
+arithmetic: PNG decode and encode overhead, GC, and concurrency all add to it. A
+missing, non-finite, or sub-1 `maxPixels` falls back to the default; fractions are
+floored (`16.9` becomes `16`). The sub-1 rule matters because a positive fraction
+such as `0.5` floors to `0`, which would otherwise reject every comparison.
+SnapDrift's own local and hosted paths keep the default, because the host process
+— not the image — decides how much memory is actually safe.
+
+Approximate maximum full-page CSS heights below
 assume that the raster width remains equal to the configured CSS width and that
 the document height scales by the same device scale factor:
 
@@ -353,18 +375,16 @@ All three directories can be overridden with `--baseline-dir`, `--current-dir`,
 
 ### migrate-baselines
 
-Migrate baselines between local storage and Snap. Both directions require a `snap` block in `snapdrift.json` (or `--to local` for the `snap → local` direction, since the export call still talks to Snap first).
+Move baselines between local storage and Snap. Only the `snap → local` direction is supported; it requires a `snap` block in `snapdrift.json` (the export call talks to Snap).
 
-**Upload local baselines to Snap:**
+**Upload local baselines to Snap — not supported:**
 
 ```
-snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
+snapdrift migrate-baselines --to snap   # always fails
 ```
 
-- Reads `results.json`, `manifest.json`, and `screenshots/*.png` from the local baseline directory.
-- Uploads as the initial accepted baseline on Snap via `POST /v1/visual/projects/:id/baselines`.
-- Idempotent: if a baseline already exists for the same commit SHA (derived from `GITHUB_SHA` or `git rev-parse HEAD`), the upload is skipped.
-- Screenshots are base64-encoded in the request body; very large suites may want to migrate per-route.
+- The command exits with an error. Snap cannot accept a pre-built local baseline bundle: the screenshots it carries are never uploaded to Snap storage, and its manifest references local filenames rather than Snap object keys, so the call could only ever create a baseline with no pixels behind it. Snap rejects the request with `400 unsupported_baseline_body` (i2Dev-com/snap#653); the legacy `SnapProvider.migrateBaselineFromLocal()` path was removed in 0.7.0.
+- **Use `snapdrift baseline` instead** — with `provider: "snap"` it captures each route through Snap so the images actually land in storage, then publishes a baseline referencing the stored objects. Canonical hosted publication is CI-only (default-branch job); see [`snapdrift baseline`](local-cli.md#snapdrift-baseline).
 
 **Download Snap baselines to local:**
 

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@v0.11.0
+  uses: ranacseruet/snapdrift@v0.12.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
@@ -71,7 +71,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.11.0
+  uses: ranacseruet/snapdrift@v0.12.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -86,8 +86,8 @@ The wrappers remain published in their own right, and are equivalent to the disp
 
 | Entry point | Equivalent to |
 |-------------|---------------|
-| `ranacseruet/snapdrift@v0.11.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.11.0` |
-| `ranacseruet/snapdrift@v0.11.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.11.0` |
+| `ranacseruet/snapdrift@v0.12.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.12.0` |
+| `ranacseruet/snapdrift@v0.12.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.12.0` |
 
 Use the wrappers directly when you want to skip the dispatcher's input indirection, and the lower-level `capture`, `compare`, `scope`, `resolve-baseline`, `stage`, `comment`, and `enforce` actions when you need to orchestrate the stages yourself.
 
@@ -130,7 +130,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.11.0
+        uses: ranacseruet/snapdrift@v0.12.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.11.0
+        uses: ranacseruet/snapdrift@v0.12.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -249,10 +249,11 @@ When `provider: "snap"` and `baseUrl` points to a local address (localhost, `127
 
 With the Snap provider, the PR comment includes a **"View in dashboard →"** link that points to `${apiUrl}/dashboard/visual/${projectId}/runs/${runId}`. The local provider omits the link.
 
-Migrating an existing local repo to the Snap provider is a one-shot CLI command:
+To adopt the hosted provider, seed the project with a hosted baseline. `migrate-baselines --to snap` is **not** the way to do it — Snap cannot accept a pre-built local baseline bundle, because the screenshots it carries are never uploaded to Snap storage and its manifest references local filenames rather than Snap object keys. Use `snapdrift baseline` with `provider: "snap"` instead: it captures each route through Snap so the pixels actually land in storage before the baseline manifest is published. Canonical hosted publication is CI-only — run it from your default-branch job, where GitHub Actions supplies the publication metadata automatically (other CI systems set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`); a plain local checkout fails before creating a hosted run.
 
 ```bash
-snapdrift migrate-baselines --to snap
+# In CI, on the default branch, with provider: "snap"
+snapdrift baseline
 ```
 
 Conversely, downloading a Snap baseline back to a local directory (useful for reproducible local debugging) is:
@@ -297,9 +298,6 @@ snapdrift capture
 # After making changes, compare and open the HTML report
 snapdrift diff --open
 
-# Migrate an established local baseline to the hosted Snap backend
-snapdrift migrate-baselines --to snap
-
 # Translate a snap/github-action workflow into snapdrift.json
 snapdrift init --from-snap-action .github/workflows/snap.yml
 ```

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

@@ -82,7 +82,7 @@ jobs:
 
       - name: Publish SnapDrift baseline
         if: steps.baseline_candidate.outputs.current == 'true'
-        uses: ranacseruet/snapdrift@v0.11.0
+        uses: ranacseruet/snapdrift@v0.12.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

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
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -103,8 +103,8 @@
   },
   "dependencies": {
     "@snapdrift/adapter-fs": "^1.3.0",
-    "@snapdrift/adapter-report-md": "^1.2.0",
-    "@snapdrift/compare-core": "^1.2.0",
+    "@snapdrift/adapter-report-md": "^1.2.1",
+    "@snapdrift/compare-core": "^1.3.0",
     "@snapdrift/manifest": "^1.4.0",
     "js-yaml": "^5.4.0",
     "playwright": "^1.59.1",