perf(docs): re-encode the hero cover to WebP and hoist its path into one constant

[os-zhuang]

Fixes#12242

The homepage's click-to-play video poster was a 2400×1200 PNG. It is now a WebP re-encode of the same master, and the path all three consumers spell is one exported constant.

Before / after, measured over the wire

Both numbers come from next build && next start in this worktree (port 3242), not from ls and not from production — production has been serving one unchanged deployment since ~16:55 (#12333), so the live site is evidence about a stale build only.

	before	after
path	/hero-cover-dark.png	/hero-cover-dark.webp
Content-Type	image/png	image/webp
Content-Length / curlsize_download	406,703 B	83,272 B
Content-Encoding	none	none
Chrome Resource Timing transferSize	—	83,572 B (83,272 body + 300 headers)
share of the PNG	100%	20.5% — 79.5% off

$ curl -sI -H 'Accept-Encoding: gzip, deflate, br, zstd' http://127.0.0.1:3242/hero-cover-dark.webp
HTTP/1.1 200 OK
Content-Type: image/webp
Content-Length: 83272
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3242/hero-cover-dark.png
404

The 404 is the reverse check: the PNG is gone from the build output, so nothing can still be quietly reading it.

Displayed size — the card's "~1024 px" re-derived

Read off the running page in Chrome rather than inferred from the Tailwind classes:

displayedCssW 974 displayedCssH 486 devicePixelRatio 2 deviceW 1948
naturalWidth 2400 naturalHeight 1200

max-w-5xl (64rem) minus px-6 padding pins the figure at 974 CSS px at every viewport ≥ 1024 px — checked at 1280, 1440 and 2560 and it does not move. So the widest a 2× desktop ever needs is 1948 device px; the card's "~1024 px" is close but the exact number is 974. The asset stays 2400 px wide, which is 1.23× more than a 2× display consumes.

Keeping 2400×1200 is deliberate: og:image:width / og:image:height are emitted from the same constant, and a declared size that disagrees with the bytes is worse than no declaration. They did not have to move because the dimensions did not.

Fidelity — what was actually compared

Encode: sharp('docs/screenshots/hero-cover-dark.png').webp({ quality: 80, effort: 6 }), sharp 0.35.3 / libwebp 1.6.0. Reproducible — re-running it produces 83,272 B again.

Both images were decoded to raw at native size, then resampled Lanczos3 to 1948×974 — the exact device-pixel box measured above — and compared on the luma plane:

	value
SSIM (8×8 windows)	0.994713
PSNR	47.10 dB
max per-pixel Δ	24 / 255
pixels with |Δ| > 5	0.739%
control: master vs. master through the same pipeline	SSIM 1.000000, PSNR ∞

The control matters. A first pass scored a lossless WebP of this PNG at SSIM 0.9936 against the PNG it was losslessly encoded from — because sharp(file).resize(...) hands the target size to the codec (libwebp's rescaler, libjpeg shrink-on-load), so each format was being downscaled by a different resampler. That pass was ranking rescalers, not codecs. Decoding to raw first fixed it, and the lossless control now reads exactly 1.0.

Beyond the aggregate, 32×32 tiles were scored across the rendered frame and the four regions most at risk were cropped and inspected side by side at 2× magnification of the 2× render — the code panel (syntax-coloured monospace on dark, the classic ringing target), the smallest text on the image (the dashboard sub-labels), the purple gradient headline (banding target), and the two worst-scoring tiles. Original, q75, q80, q85 and q90 are indistinguishable in all four. The worst-scoring tiles turn out to be near-uniform white chart areas where SSIM is hypersensitive to tiny absolute differences, not places where anything is visibly wrong.

Quality 80 was chosen over 85 (93.6 KB) because it clears the ~100 KB bar with margin rather than grazing it, and the visual comparison could not separate them.

WebP rather than AVIF, deliberately. AVIF is measurably better per byte on this image — q60 reaches SSIM 0.998 at 65 KB, beating WebP q85 at 94 KB. It was rejected anyway: this is a plain <img> with no <picture> fallback and it is the og:image, so it has to decode in every browser and every unfurler. Two independent published test matrices agree that WebP now works across the major unfurlers and AVIF works in roughly a third of them. The constraint is recorded next to the constant so the next person does not re-litigate it from the byte table alone.

One constant, three call sites

HERO_COVER now lives in apps/docs/lib/site.ts beside SITE_ORIGIN / absoluteUrl(), and carries the re-encode recipe, the provenance of the master, and why the dimensions and format are constrained. The three literals that used to spell the path:

call site	was	now
app/[lang]/page.tsx — video poster	poster="/hero-cover-dark.png"	poster={HERO_COVER.url}
app/[lang]/page.tsx — HOME_CARD (OG + Twitter + JSON-LD image)	local object literal	HERO_COVER (constant deleted)
app/[lang]/blog/[[...slug]]/page.tsx — BLOG_CARD (index + every post, OG + Twitter + BlogPostingimage)	local object literal	HERO_COVER (constant deleted)

Verified in the served HTML rather than in the source:

homepage <img src="/hero-cover-dark.webp" …>
homepage og:image / twitter:image = https://objectstack.ai/hero-cover-dark.webp
og:image:width 2400 · og:image:height 1200
/blog og:image / twitter:image = https://objectstack.ai/hero-cover-dark.webp
/blog/… og:image and BlogPosting "image" = https://objectstack.ai/hero-cover-dark.webp

A repo-wide grep leaves no /hero-cover-dark.png URL anywhere; the only remaining .png spellings are the README's own <img src="docs/screenshots/hero-cover-dark.png"> and prose in two docblocks pointing at that master.

Out-of-surface edit, declared

apps/docs/components/youtube-embed.tsx is outside the dispatched file surface. One clause of its docblock said the cover is docs/screenshots/hero-cover-dark.png "copied into public/" — this change makes that false (it is a re-encode now, not a copy), in the file that documents this exact asset. Comment-only, one sentence, no behaviour: it now says re-encoded and points at HERO_COVER. No open PR claims that file (all 100 open PRs enumerated against my file surface: zero hits).

docs/screenshots/hero-cover-dark.png — the README's copy still resolves

Untouched, and proved rather than asserted:

$ git rev-parse HEAD:docs/screenshots/hero-cover-dark.png d8322c8392b2839baec5bf232f315b6b73caaaad
$ git hash-object docs/screenshots/hero-cover-dark.png d8322c8392b2839baec5bf232f315b6b73caaaad
$ git diff HEAD -- docs/screenshots/ README.md (empty)
$ shasum -a 256 … 6ab3f83c…065fe9 (identical to pre-change)

Still tracked, still 406,703 B, still at the path the README's relative <img src> resolves to from the repo root. It is now also the master this PR's WebP is derived from, which gives it a second reason to stay.

Verification

At the pushed head 63e50a103, tree clean:

check	verdict line
pnpm --filter @objectstack/docs typecheck	VERDICT command-exit 0
next build (apps/docs)	✓ Compiled successfully, VERDICT command-exit 0
pnpm check:docs-locale-catch-all	VERDICT command-exit 0
pnpm check:page-declaration-shape	VERDICT command-exit 0
pnpm check:published-files	VERDICT command-exit 0
pnpm check:test-source-alias	VERDICT command-exit 0
pnpm check:type-source-resolution	VERDICT command-exit 0
pnpm check:nul-bytes	VERDICT command-exit 0

The five check:* families are what node scripts/pm/dispatch-gates.mjs derives for this diff's six paths (it reads the change set from git itself); check:nul-bytes is owed by any edit.

Verification ran UNLOCKED, declared.scripts/pm/os-verify-lock.sh reports no usable flock on this host — the shared verify lock is Linux-only and this is macOS — so every command above ran through the entry point but with no mutual exclusion. Each ends VERDICT … · UNLOCKED (declared).

Repo-wide pnpm lint is NOT MEASURED here, and narrowed lint is declared in its place.pnpm lint (eslint . --no-inline-config) died twice with a V8 heap OOM on this host — FATAL ERROR: Ineffective mark-compacts near heap limit, exit 134, at the default heap and again at --max-old-space-size=6144. That is a host failure, not a red gate, and CI runs the full scan regardless. The narrowing is measured, not assumed:

1. Receiving population read from ESLint's own config, not guessed: ESLint#isPathIgnored says all four changed source files are in scope and both changed binaries (.png, .webp) are ignored.
2. File count read from --format json: exactly 4 files reported linted, 0 errors, 0 warnings, exit 0 — so nothing was silently skipped.
3. Config invariance for untouched files: calculateConfigForFile returns parserOptions.project: null, projectService: null, EXPERIMENTAL_useProjectService: null for every probed file, inside and outside apps/docs, and the flat config contains no such switch at all. With no type-aware linting, no rule's verdict on a file I did not touch can depend on this diff — so the narrowing excludes nothing.

No changeset: docs-site only, @objectstack/docs is private: true and this publishes nothing. skip-changeset applied.

---

Generated by Claude Code