✨ Resolve screenshot SHAs before byte upload

[Robdel12]

Why

Screenshot upload is one of Vizzly's hottest SDK paths. When a build captures thousands of screenshots, sending image bytes for files we already have in storage is wasted work for the CLI, API, and object storage.

The paired Vizzly API change lets the screenshot create endpoint accept sha256 without image_data, resolve reusable storage server-side, and only ask for bytes when the image is missing. This CLI change moves the per-screenshot upload path to that contract.

Approach

• Compute the screenshot SHA before upload and first call the screenshot create endpoint with name, metadata, and SHA only.
• Skip the byte upload when the API returns upload_required: false, preserving the existing skipped/fromExisting result shape for callers.
• Fall back to the normal byte upload path when SHA resolution is unavailable, returns a server error, or talks to an older server that still requires image_data.
• Continue surfacing auth and ownership failures instead of retrying them as byte uploads, so the fallback does not hide real access-control errors.
• Document that skipped uploads mean Vizzly reused existing storage, and that --upload-all still forces screenshots through.

This keeps the CLI simple: no SDK-side batching, no client-side cache, and no extra state to recover from. The API stays authoritative about whether a screenshot can reuse existing storage.

Confidence

The API payload helper now has a pure test proving SHA resolution omits image bytes. The upload endpoint tests cover resolve misses, resolve hits, old-server fallback, auth failure, and --upload-all. The full CLI test suite and Biome lint pass locally.

Related

• Coordinates with vizzly-testing/vizzly#543, which adds the server-side create-with-SHA behavior.

[vizzly-testing]

Vizzly - Visual Test Results

CLI Reporter - Waiting for build

No builds received yet for this pull request.

CLI TUI - Approved

5 comparisons, no changes detected.

View build

---

_{rd/screenshot-sha-create-resolve · 68f5d1b4}