perf(images): WebP covers with srcset, JPEG share images, hero and thumbnails through astro:assets

[objectstack-fleet]

Fixes #220

Branch. This PR carries 5 commit(s) from the seat's linear stack, replayed onto main @ 1408a0c. The replay is patch-equal to git diff 0b84524 lin/issue-220, with byte-identical diffs. Head: 85474eb. The staged SHAs quoted below are the pre-replay commits; their content is unchanged.

Images were almost the whole page weight: 1.6-1.9 MB PNG covers as the LCP element of 80 posts, a 1.7 MB hero loaded by 120 marketing pages, and an SVG og:image on 209 posts that X, LinkedIn, Facebook and Slack cannot draw. This PR fixes all three. The PNG-cover posts go from about 10-11 s LCP to 1.7 s on a phone under the card's profile, the marketing hero from 10.6 s to 2.0 s at 1366, one scroll of /en/blog/ downloads 1.2 MB instead of 18.8 MB, and a cluster page downloads 0.28 MB instead of 1.18 MB. Every post now has a 1200x630 JPEG share image.

What changed

1. Covers (BlogPost.astro, ArticleCard.astro, MarketingHome.astro, ClusterPage.astro). A PNG or JPG cover now goes through the astro:assets Image component as WebP, with a width list and a sizes value for each slot:

• Post header: 480-1600w, (min-width: 908px) 860px, calc(100vw - 2rem). It stays eager with fetchpriority=high because it is the LCP element.
• Card thumbnails: 400-1280w. sizes gives the width the image is actually drawn at. A 16:10 thumb crops a 16:9 cover with object-fit: cover, which draws it 1.11x the card's width.
• Feature card: its cover is eager, because it opens the blog index above the fold.
• Home latest-posts grid: 360-1080w.
• Cluster reading-path cards: 400-1080w on the 40 cluster pages. They loaded the original 240-370 KB JPGs into 180px slots. Above 640px the image column is 180px (150px at 641-900px) and as tall as the card's text: I measured 190-227px. object-fit: cover fills it by height, so the cover is drawn 304-364px wide and sizes says 400px. On a phone the card stacks and the 16:9 image is drawn at the column width.

An SVG cover is a few KB and scales itself, so it keeps a plain img element on the original. The ai-agent-workbench cover at 1280w is 58 KB; the original is 1.62 MB. A 1:1 crop against the original shows no visible loss (PSNR 39 dB), and neither do the close-ups and thumbnails listed under Browser check.

2. Hero (src/assets/objectos-home-hero.png, moved from public/images/). It is served through the Image component as WebP, 400-1586w. The hero box crops the 1.6:1 image with object-fit: cover, so sizes gives the drawn width: 545px on a desktop, and about 1.2x the box on a phone.

• Marketing evidence pages: I measured all six viewports. The hero's top is at 172px on a desktop, where it is the LCP element, and at 713-781px on an 800-844px phone. It is in the first screen at every viewport, so it stays eager, now with fetchpriority=high.
• Home: the hero sits below the hero copy and the video at every viewport, so it stays lazy.
• Dark mode: a muted image. No dark variant of the render exists, so the image itself is dimmed with filter: brightness(0.6) contrast(1.12). I compared three strengths side by side in the panel. No layout CSS was touched.
• Original dropped from dist: the components no longer read the import's width, so Astro drops the 1.7 MB original from dist/.

3. Share images (scripts/og-images.mjs, scripts/lib/og-image.mjs, scripts/lib/og-fonts.mjs). A build step runs after astro build and renders one 1200x630 JPEG per cover into dist/og/blog/POST/.

• Page tags: BlogPost.astro names that JPEG in og:image, twitter:image and BlogPosting.image. It also sets og:image:width/height to 1200x630 and uses the post title as og:image:alt.
• One URL rule: the page and the renderer share it (scripts/lib/og-image.mjs). The URL carries a hash of the cover's bytes, so an edited cover gets a new URL that the networks re-fetch.
• Fails the build when:
  • a page names a share image that no cover maps to;
  • a page declares a size that is not the file's;
  • an og:image of this site is not in dist/.
• SVG text uses bundled fonts only. sharp renders SVG text with the machine's fonts. The covers ask for -apple-system, Segoe UI, Inter, Arial and Menlo, and CI's ubuntu-latest has no CJK font, so the Chinese covers would have shipped as boxes. The rasterizer now sees only bundled OFL faces:
  • Arimo and Cousine: these have the Arial and Courier New metrics that pnpm svg:lint measures with, so a line that passes svg:lint has the same width in the raster.
  • Noto Sans SC, Noto Sans Symbols 2, Noto Sans Math, Noto Emoji.
  • Why wawoff2: Fontsource ships WOFF2 and WOFF. The FreeType in sharp's libvips reads neither (every glyph drew as a box), so wawoff2 decodes them to TrueType for a generated fonts.conf.
• Glyph gate: every character in an SVG cover's text elements is checked against the faces' cmaps before rendering. A missing one fails the build and names the cover, the code point and the line.
• Cropping:
  • SVG covers are drawn whole at the card's height and widened by repeating their edge columns. Two covers put a caption in the bottom 23px, which a centre crop would cut.
  • PNG/JPG covers are illustrations with no text, so they are centre-cropped.
• Worker processes: rendering SVG text on several libvips threads in one process crashed it (SIGSEGV or "SVG rendering failed" in 4 of 6 runs). The step renders in 3 worker processes, one image at a time in each, and passed 5 of 5 runs.
• Default share image (Base.astro): it was the hero by its public path, which the move removes. It is now a 1200x630 JPEG of the moved asset (94 KB, generated with getImage) instead of the 1.7 MB PNG.

Before / after

Measured with Playwright Chromium (desktop rows at 1366x625), 390x844 at 3x, 4x CPU throttle and DevTools "Slow 4G" (562.5 ms RTT, 1.44 Mbps down). Cache was cold. LCP is the median of 3 runs.

Bytes are transfer sizes from a local static server that does no gzip, so HTML and CSS are counted uncompressed:

• No scroll: everything the load starts, including lazy images inside Chrome's load-in distance.
• Full scroll: after scrolling to the bottom.

Before is staged/issue-219 @ 5d685cf; after is bec5251. Both were measured back to back under one lock, on a shared 4-core box with a load average around 10. The cluster rows compare bec5251 (ClusterPage unchanged from 5d685cf) with 95ada62, also back to back under the lock.

Page	LCP before	LCP after	Bytes, no scroll: before → after	Bytes, full scroll: before → after
home /en/	1,944 ms (text)	1,916 ms (text)	1,821,615 → 170,412	1,835,942 → 184,739
pricing /en/pricing/	1,560 ms (text)	1,548 ms (text)	46,504 → 46,534	46,504 → 46,534
platform /en/platform/	1,796 ms (text)	1,808 ms (text)	1,805,784 → 129,837	same
blog index /en/blog/	2,708 ms (SVG cover)	1,808 ms (SVG cover)	142,787 → 148,368	18,826,110 → 1,167,398
post /en/blog/ai-agent-workbench/ (PNG)	9,956 ms (PNG)	1,700 ms (WebP)	1,685,249 → 120,959	same
post /en/blog/ai-expense-audit/ (PNG)	11,120 ms (PNG)	1,752 ms (WebP)	1,903,685 → 135,214	same
platform @1366x625	2,060 ms (h1)	1,928 ms (h1)	1,805,784 → 92,303	same
ai /en/ai/ @1366x625	10,620 ms (hero PNG)	1,964 ms (hero WebP)	1,804,910 → 91,429	same
cluster /en/ai-native-app-platform/	1,688 ms (text)	1,680 ms (text)	903,617 → 230,655	1,182,014 → 282,059
cluster /en/ai-native-app-platform/ @1366x625	1,848 ms (h1)	1,828 ms (h1)	1,182,014 → 124,226	same

The small increases on pricing and the blog index (+30 B and +5.6 KB) are the longer og:image URL and the srcset attributes.

Build and dist, both with a cold Astro image cache on the same shared box:

	before	after
pnpm build wall time	87.5 s	108.4 s (90.5 s with a warm image cache at 95ada62)
astro image generation	0.6 s	6.3 s
og-images.mjs	n/a	14.3 s (87 images, 3 workers)
dist/	57,657,630 B, 1,082 files	68,235,078 B, 1,321 files

The dist increase is:

• +6.05 MB of cover WebP variants (143 files);
• +5.46 MB of share JPEGs (87 files: median 52 KB, max 152 KB);
• +0.4 MB of hero variants;
• −1.73 MB for the hero PNG.

Share-image checks

• All 87 are 1200x630 JPEG. The step checks this, and a separate metadata pass confirmed it.
• The glyph gate covered 70 SVG covers and 721 distinct characters. Its first run on this tree found U+21B6 (↶) and U+2298 (⊘), which is why Noto Sans Math is in the set.
• The gate can fail:
  • A synthetic cover with Hangul and Thai reported those 6 code points. It did not report CJK, ✓ or an entity-encoded emoji.
  • On a copy of dist/, a page with og:image:width 1201 and a page with an unmapped share-image URL each failed the step. It exited 1 with 3 issues.
• Looked at in full:
  • zh-Hans and zh-Hant (one shared Chinese cover per post): ai-wrote-your-app-dare-to-merge (🤔 ✓ →), beyond-agentforce-copilot-open-runtime (✓ ⊘), natural-language-to-app-metadata (curly quotes), airtable-omni-vs-governed-ai-app-platform (↶ ✓), self-hosted-ai-app-platform (1.6:1 viewBox).
  • ja and ko (these use the English cover-en.svg, like de, es and fr): why-ai-agent-pilots-fail-four-layers (①-④, U+3000), when-ai-agent-deletes-production-database (⛔ 💥 ✓).
  • The 10 PNG and 7 JPG illustrations, which ja and ko share.
  • All 87 rasters in six contact sheets.
  • No missing glyph anywhere.
• No SVG cover today has Japanese or Korean text. Kana and Traditional Chinese are covered by Noto Sans SC (checked). Hangul is not, so a future Korean-text SVG cover fails the build with its code points named.
• Emoji render in monochrome (Noto Emoji). The COLRv1 colour emoji font decodes, but cairo draws nothing for it.

Browser check

There are 36 page states (plus the cluster page, below): the six viewports (1366x625, 1440x750, 1512x830, 1920x945, 390x844, 360x800) × {PNG-cover post, blog index, home} × {light, dark}. Each has a first-screen and a full-page screenshot, taken after scrolling every lazy image into view.

• Every state reports 0 unloaded images and 0 px horizontal overflow.
• Close-ups:
  • the ai-expense-audit cover at 1920 and at 390@3x;
  • raster card thumbnails at 1366 light, 1920 dark, 390 dark and 360 light;
  • the 1366 thumb before and after, side by side;
  • the home hero and the marketing hero panel in light and dark.
• /en/ai-native-app-platform/ at 1366x625 and 390x844, in light and dark, full page plus the reading-path section, all after scrolling every lazy image into view:
  • 0 unloaded images and 0 px horizontal overflow;
  • the card image boxes are unchanged (180x227 on a desktop, 356x200 on a phone);
  • a before/after close-up of the first card's image at each width.
• No visible quality loss.

Gates (at 95ada62)

• pnpm check: Result (150 files): 0 errors, 0 warnings, 0 hints. Run under the lock, VERDICT command-exit 0.
• pnpm content:lint: ✓ content lint passed (339 files, 44 glossary terms checked)
• pnpm content:lint --published: ✓ content lint passed (339 files, 44 glossary terms checked)
• pnpm build: BUILD_EXIT=0, run under the lock. It includes:
  • svg-text-fit: OK — … (112 SVGs, 2244 text boxes, tolerance 2px, 1 allowlisted);
  • ✓ share images: 87 rendered at 1200x630 (5.2 MB, 13.3 s, 3 workers) for 879 pages; 125 bundled font files, no uncovered glyph;
  • ✓ content lint --dist passed (478 built blog pages checked);
  • ✓ content lint --dist links passed (93199 internal links in 880 built pages resolve to built files).
• pnpm seo:smoke: SEO smoke test passed (870 HTML pages checked; 569 sitemap URLs against 301 noindexed pages; …)
• pnpm svg:lint: svg-text-fit: OK — no text box crosses the shape under it or runs under a shape painted over it (112 SVGs, 2244 text boxes, tolerance 2px, 1 allowlisted)

New dependencies

All are build-time devDependencies. sharp was already a dependency.

• wawoff2 (MIT): decodes WOFF2 to TrueType, because the FreeType in sharp's libvips cannot read WOFF2 or WOFF.
• Six Fontsource packages (OFL-1.1): @fontsource-variable/arimo, @fontsource/cousine, @fontsource-variable/noto-sans-sc, @fontsource/noto-sans-symbols-2, @fontsource/noto-sans-math, @fontsource-variable/noto-emoji. These are the faces above; each one is needed by at least one character in the current covers.

Acceptance notes

• Base.astro is outside the card's Surface. It is edited because moving the hero removes the public path its default og:image named. The edit is the DEFAULT_IMAGE block only.
• ClusterPage.astro replays cleanly with Accessibility and dark-mode tokens: muted text 3.08:1, focus ring 1.5:1, dark-mode accents 2.4–2.8:1, the mobile drawer does not manage focus, small tap targets #218. It was added at the coordinator's request; Accessibility and dark-mode tokens: muted text 3.08:1, focus ring 1.5:1, dark-mode accents 2.4–2.8:1, the mobile drawer does not manage focus, small tap targets #218 also edits this file. This card's hunks are the frontmatter (the import, and the width list replacing coverSrc) and the card markup; Accessibility and dark-mode tokens: muted text 3.08:1, focus ring 1.5:1, dark-mode accents 2.4–2.8:1, the mobile drawer does not manage focus, small tap targets #218's are CSS around line 151. git merge-tree --write-tree staged/issue-218 staged/issue-220 exits 0 with tree 1b733e9, which carries both Accessibility and dark-mode tokens: muted text 3.08:1, focus ring 1.5:1, dark-mode accents 2.4–2.8:1, the mobile drawer does not manage focus, small tap targets #218's dark kicker colour and this card's CARD_WIDTHS.
• Original raster covers stay in dist/. The 17 originals (18.9 MB) are referenced by no page after this PR. Astro keeps the originals of content-collection images, and this PR does not work around that.
• The home latest-posts raster branch is not exercised yet. The latest three posts in every locale have SVG covers today.
• astro.config.mjs is unchanged. No image-service configuration was needed.
• No content edits.

---

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr