Use server-generated ThumbHashes in Storage receipts and Viewer

[kvz]

Why

The SDK's native image decoder was removed to restore lightweight, portable installs and Supabase Edge compatibility. API2 now owns optional ThumbHash extraction (API2 #9182); clients should request and preserve that metadata without downloading/decoding originals themselves.

What

• Opt in with storeImage(..., { placeholder: 'blur' }) or storage store --placeholder blur. Ordinary uploads are unchanged. Extraction is best-effort and its metadata usage is disclosed.
• Preserve canonical thumbhash / has_alpha through verified receipts, Assembly recovery/batch results, native asset reads and catalog sync. Viewer still accepts older hasAlpha catalogs.
• Keep public blur server-rendered, transparent/letterboxed backgrounds clear, and request-authorized private pixels out of inline placeholders. Hashless uploads remain usable; hashed replays never upload or overwrite just to obtain a placeholder.
• Preserve upgrades of older headerless generated declarations, including CRLF, while still rejecting another catalog's declarations. Council found this regression; the fix is covered red-first.
• Document recovery limits and add Changesets notes. No new dependency, lockfile change, Built-in, Terraform change or Uppy work.

Verification

• Final head 8bed9b9 is fully green in CI run 35773972305, monitored with gh-run-watch.ts. The final local yarn check and packed 126-test browser fixture also passed.
• Red-first SDK/Viewer and CLI tests; all 148 final focused CLI tests pass.
• yarn check, yarn verify:full, then the final check plus wrapper sync / Knip / type tests after the council fix.
• Packed Next fixture: 58 Chromium/WebKit tests with Cache Components, 58 without, 10 development tests. The seed calls the actual packed SDK and CLI, with only the Assembly response simulated. Explicit private blur is checked in HTML and RSC; a JavaScript-disabled Chromium capture checks the blur color before delivery.
• Both SDK names bundled and ran in pinned Supabase Edge: zero native files, about 2.45 MB compressed (5 MiB budget).
• Council review completed and its verified finding fixed. Two independent Opus browser-evidence passes returned PASS; their color/private-blur evidence gaps are closed. The exploratory desktop/mobile pass covered public images, alpha/letterboxing and private sign-in recovery. This is synthetic local integration proof, not a production deployment claim.

CI follow-up

At a1eb5e2, the legacy Supabase Edge bundler exited 135 twice with no output; scoped Node and local ARM passed. A fresh unchanged-main control passed, followed by both packages passing on the diagnostic head and again on final head 8bed9b9 without verbose diagnostics. The native crash's root cause remains unconfirmed. Normal container-state/bundler-log evidence is now retained on failure; no package gate, budget, dependency or SDK runtime behavior was weakened.

Rollout

Apply migrations/2026-09-22-add-dam-version-placeholders.sql before deploying API2 #9182. Then prove a live opt-in upload → native metadata → recovered catalog → Viewer. Release through Changesets afterward, retaining Viewer's explicit alpha status, then pin/dogfood it in Content. Existing assets are not automatically backfilled.

API2 main 525f77ca7a includes #9182 and its x64 build/tests passed. Verified uploaded tar: s3://build-artifacts-transloadit/main/api2/api2-gha-ci-35767194563.tar.gz. The overall main run is red because ARM timed out in the untouched standalone core/test/unit/gha-runner-spot-watch.vitest.ts test; no CI-infrastructure change or backend deployment was made here.

Kevin explicitly deferred the newly reproduced 1×1-source ThumbHash color edge case to the next API2 slice. Its reproduction and required bounded-sampling/aspect/alpha tests are saved in the living document; this PR does not fix or conceal that backend limitation.

Living checklist: docs/prompts/2026-09-22-sdk-thumbhash.md.