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

The homepage video poster was a 2400x1200 PNG served at 974 CSS px. Measured
over the wire against a local `next build && next start`: 406,703 B, no
transport compression (image/png, Content-Length == file size). It is the
heaviest single element the homepage loads.

Re-encoded from the master `docs/screenshots/hero-cover-dark.png` to WebP at
quality 80 / effort 6 (sharp 0.35.3, libwebp 1.6.0), keeping 2400x1200 so the
declared `og:image:width` / `og:image:height` stay true and 2x displays stay
oversampled. 83,272 B on the wire -- 20.5% of the PNG, and 83,572 B including
response headers as Chrome's Resource Timing reports it.

Fidelity, measured at the exact device-pixel size Chrome paints (1948x974,
read off the running page): SSIM 0.994713, PSNR 47.10 dB against the master,
max per-pixel delta 24/255, 0.739% of pixels differing by more than 5/255. The
same harness scores the master against itself at SSIM 1.0 / PSNR infinity, so
it is not fabricating agreement. Crops of the four regions most at risk --
code panel, smallest dashboard labels, gradient headline, and the two
worst-scoring tiles -- are indistinguishable at 2x magnification.

WebP rather than AVIF deliberately: this is a plain `<img>` with no `<picture>`
fallback and it doubles as the og:image, so it must decode everywhere. AVIF is
measurably better per byte on this image (q60 reaches SSIM 0.998 at 65 KB) and
was rejected because unfurler support is not there.

The path was spelled three times -- the poster, the homepage card, the blog
card -- and two of those read as SEO config rather than image references. It is
now `HERO_COVER` in `lib/site.ts`, next to `SITE_ORIGIN`, carrying the
re-encode recipe and the reason the dimensions and the format are constrained.

`docs/screenshots/hero-cover-dark.png` -- the README's copy, a separate file
for a separate consumer -- is untouched: same blob sha before and after.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

apps/docs/app/[lang]/blog/[[...slug]]/page.tsx

@@ -4,7 +4,7 @@ import { blog } from '@/lib/source';
 import { getMDXComponents } from '@/mdx-components';
 import { HomeLayout } from 'fumadocs-ui/layouts/home';
 import { baseOptions } from '@/lib/layout.shared';
-import { absoluteUrl } from '@/lib/site';
+import { absoluteUrl, HERO_COVER } from '@/lib/site';
 import {
   compact,
   JsonLd,
@@ -78,7 +78,7 @@ function postGraph(url: string, data: BlogPostData): JsonLdNode[] {
       url: canonical,
       mainEntityOfPage: canonical,
       inLanguage: 'en',
-      image: absoluteUrl(BLOG_CARD.url),
+      image: absoluteUrl(HERO_COVER.url),
       datePublished: isoDate(data.date),
       dateModified: sitemapLastModified(url),
       keywords: data.tags,
@@ -251,29 +251,25 @@ export async function generateStaticParams() {
   }));
 }
 
+const BLOG_INDEX_TITLE = 'Blog';
+const BLOG_INDEX_DESCRIPTION =
+  'Insights, updates, and best practices from the ObjectStack team.';
+
 /**
- * The blog's social card.
+ * Metadata for the blog index and for every post.
+ *
+ * The social card in both branches is the shared hero cover, `HERO_COVER` from
+ * `lib/site.ts` — the same image the homepage presents itself with, and the same
+ * one `postGraph()` above puts in the `BlogPosting` node. It used to be a literal
+ * spelled here and again on the homepage; one declaration now, so a re-encode
+ * cannot leave half the site pointing at a file that no longer exists.
  *
  * ⚠️ The card generator at `app/og/docs/[...slug]/route.tsx` is docs-only: it
  * renders from `source` (the `content/docs` loader) and has no branch for `blog`,
  * so there is no per-post card to reference and this card is shared by the index
  * and every post. Giving posts their own generated cards is a separate decision,
  * not a gap in this wiring — it would mean a second `app/og/**` route.
- *
- * ⚠️ Same path as `apps/docs/app/[lang]/page.tsx`'s `HOME_CARD`; that file
- * carries the note on why it is spelled twice and what must change together.
  */
-const BLOG_CARD = {
-  url: '/hero-cover-dark.png',
-  width: 2400,
-  height: 1200,
-  alt: 'ObjectStack — the metadata framework for AI-written apps',
-};
-
-const BLOG_INDEX_TITLE = 'Blog';
-const BLOG_INDEX_DESCRIPTION =
-  'Insights, updates, and best practices from the ObjectStack team.';
-
 export async function generateMetadata({
   params,
 }: {
@@ -296,13 +292,13 @@ export async function generateMetadata({
         title: BLOG_INDEX_TITLE,
         description: BLOG_INDEX_DESCRIPTION,
         url: canonical,
-        images: [BLOG_CARD],
+        images: [HERO_COVER],
       },
       twitter: {
         card: 'summary_large_image',
         title: BLOG_INDEX_TITLE,
         description: BLOG_INDEX_DESCRIPTION,
-        images: [BLOG_CARD.url],
+        images: [HERO_COVER.url],
       },
     };
   }
@@ -324,13 +320,13 @@ export async function generateMetadata({
       title: page.data.title,
       description: page.data.description,
       url: canonical,
-      images: [BLOG_CARD],
+      images: [HERO_COVER],
     },
     twitter: {
       card: 'summary_large_image',
       title: page.data.title,
       description: page.data.description,
-      images: [BLOG_CARD.url],
+      images: [HERO_COVER.url],
     },
   };
 }

apps/docs/app/[lang]/page.tsx

@@ -4,7 +4,7 @@ import { ArrowRight, Check } from 'lucide-react';
 import { Bricolage_Grotesque, IBM_Plex_Mono } from 'next/font/google';
 import { HomeLayout } from 'fumadocs-ui/layouts/home';
 import { baseOptions, gitConfig } from '@/lib/layout.shared';
-import { absoluteUrl } from '@/lib/site';
+import { absoluteUrl, HERO_COVER } from '@/lib/site';
 import {
   APACHE_2_0_URL,
   GITHUB_REPO_URL,
@@ -36,30 +36,22 @@ const HOME_DESCRIPTION =
   'ObjectStack turns the whole app — data model, UI, workflows, permissions — into typed metadata: a complete CRM in under 150k tokens, one context window.';
 
 /**
- * The homepage's social card.
+ * The homepage's metadata. Its social card is the shared hero cover,
+ * `HERO_COVER` from `lib/site.ts` — the same image the video poster below uses.
  *
  * ⚠️ Deliberately NOT the docs card generator. `app/og/docs/[...slug]/route.tsx`
  * renders from a `source.getPage()` result, and the homepage has no MDX file
  * behind it — there is no slug to hand it. It reuses the hero cover instead,
  * which is already shipped and already the video poster on this page, so the
  * shared card costs no extra bytes and no extra route.
  *
- * ⚠️ `apps/docs/app/[lang]/blog/[[...slug]]/page.tsx` spells this same path for
- * the blog's card. Two spellings rather than one shared constant because
- * `lib/site.ts` is the origin's home, not the asset manifest's; if a third page
- * ever needs it, hoist it there. Anything that renames, re-encodes or deletes
- * `public/hero-cover-dark.png` must update BOTH — an `og:image` that 404s is
- * worse than none, because crawlers then scrape whatever else the page offers.
+ * The path used to be spelled as a literal here, again in the blog's card, and a
+ * third time as the `poster` further down this file — with a note asking whoever
+ * added a third consumer to hoist it. That happened; it lives in `lib/site.ts`
+ * now, and the reasons a re-encode has to be careful live with it.
  *
  * Left site-relative: `metadataBase` in `app/layout.tsx` absolutises it.
  */
-const HOME_CARD = {
-  url: '/hero-cover-dark.png',
-  width: 2400,
-  height: 1200,
-  alt: 'ObjectStack — the metadata framework for AI-written apps',
-};
-
 export const metadata: Metadata = {
   title: HOME_TITLE,
   description: HOME_DESCRIPTION,
@@ -77,13 +69,13 @@ export const metadata: Metadata = {
     // Same absolute URL as the canonical link — see the docs route for why the
     // two must not drift.
     url: absoluteUrl('/'),
-    images: [HOME_CARD],
+    images: [HERO_COVER],
   },
   twitter: {
     card: 'summary_large_image',
     title: HOME_TITLE,
     description: HOME_DESCRIPTION,
-    images: [HOME_CARD.url],
+    images: [HERO_COVER.url],
   },
 };
 
@@ -104,7 +96,7 @@ export const metadata: Metadata = {
  *
  * Every field is drawn from something already on this page or in `lib/`: the
  * title and description are the same constants `metadata` uses, the image is
- * `HOME_CARD`, the licence is the repo's own, and the two `sameAs` links are the
+ * `HERO_COVER`, the licence is the repo's own, and the two `sameAs` links are the
  * GitHub organisation and the YouTube channel this page links to in its hero.
  */
 function homeGraph(): JsonLdNode[] {
@@ -119,7 +111,7 @@ function homeGraph(): JsonLdNode[] {
       // itself one way to a crawler and another way to a social card.
       headline: HOME_TITLE,
       description: HOME_DESCRIPTION,
-      image: absoluteUrl(HOME_CARD.url),
+      image: absoluteUrl(HERO_COVER.url),
       codeRepository: GITHUB_REPO_URL,
       programmingLanguage: 'TypeScript',
       runtimePlatform: 'Node.js',
@@ -279,7 +271,7 @@ export default function HomePage() {
             <YouTubeEmbed
               videoId={OVERVIEW_VIDEO_ID}
               title="ObjectStack in 90 Seconds"
-              poster="/hero-cover-dark.png"
+              poster={HERO_COVER.url}
             />
             <figcaption
               className="mt-3 flex flex-wrap items-center justify-center gap-x-3 gap-y-1 text-[12px] text-fd-muted-foreground"

apps/docs/components/youtube-embed.tsx

@@ -18,11 +18,12 @@ type YouTubeEmbedProps = {
  * A facade, not a bare `<iframe>`: nothing is requested from YouTube until the
  * viewer actually clicks play, so the homepage costs no third-party frame,
  * script or cookie on load. The cover is the same one the README links from
- * (`docs/screenshots/hero-cover-dark.png`, copied into `public/`), which is 2:1
- * rather than the video's 16:9 — hence the fixed 2:1 frame with the player
- * centred inside it at its own aspect ratio. Cropping the cover to 16:9 would
- * cut through the logo on the left edge, and letting the frame change shape on
- * click would shove the rest of the page down mid-interaction.
+ * (`docs/screenshots/hero-cover-dark.png`, re-encoded to WebP into `public/` —
+ * `HERO_COVER` in `lib/site.ts` owns the path and the re-encode recipe), which
+ * is 2:1 rather than the video's 16:9 — hence the fixed 2:1 frame with the
+ * player centred inside it at its own aspect ratio. Cropping the cover to 16:9
+ * would cut through the logo on the left edge, and letting the frame change
+ * shape on click would shove the rest of the page down mid-interaction.
  */
 export function YouTubeEmbed({ videoId, title, poster }: YouTubeEmbedProps) {
   const [playing, setPlaying] = useState(false);

apps/docs/lib/site.ts

@@ -1,5 +1,6 @@
 /**
- * Canonical identity of the documentation site.
+ * Canonical identity of the documentation site — the origin it names itself by,
+ * and the shared cover asset it presents itself with.
  *
  * The origin is a maintainer ruling, not configuration. Every absolute URL this
  * site emits — sitemap entries, the `Sitemap:` line in `robots.txt`, and (as the
@@ -36,3 +37,51 @@ export function absoluteUrl(path: string): string {
 
   return new URL(path, SITE_ORIGIN).toString();
 }
+
+/**
+ * The hero cover — the one image this site presents itself with.
+ *
+ * Three consumers, one declaration: the homepage's click-to-play video poster
+ * (`app/[lang]/page.tsx`), the homepage's Open Graph / Twitter card and JSON-LD
+ * `image` (same file), and the blog's card for the index and every post
+ * (`app/[lang]/blog/[[...slug]]/page.tsx`). Before this constant the path was
+ * spelled as a literal in all three, and two of them do not read as image
+ * references at all — they read as SEO config — so a re-encode had to find them
+ * by memory. It is declared here, next to `SITE_ORIGIN`, because the cover is
+ * part of the site's identity in the same way the origin is: one asset, named
+ * once, that every self-description reads.
+ *
+ * ⚠️ `width` / `height` are emitted as `og:image:width` / `og:image:height`. A
+ * declared size that disagrees with the bytes is worse than no declaration — a
+ * crawler reserves the wrong box and some renderers reject the card outright —
+ * so anything that changes the asset's pixel dimensions must change these in the
+ * same commit. They are correct only because the re-encode below deliberately
+ * kept 2400x1200.
+ *
+ * ## Provenance — how to re-encode it
+ *
+ * The master is `docs/screenshots/hero-cover-dark.png` (2400x1200, 406,703 B),
+ * which the README embeds directly from the repo and which is NOT served by this
+ * site. This file is a lossy WebP derived from that master, and the derivation is
+ * the whole reason it is small enough to sit above the fold:
+ *
+ *   sharp('docs/screenshots/hero-cover-dark.png')
+ *     .webp({ quality: 80, effort: 6 })            // sharp 0.35.3 / libwebp 1.6.0
+ *     .toFile('apps/docs/public/hero-cover-dark.webp')
+ *
+ * 83,272 B — 20.5% of the PNG. Re-encode from the master, never from this file:
+ * a lossy re-encode of a lossy source compounds. And do not "restore" the PNG
+ * alongside it — a `public/` holding both is how the next re-encode picks the
+ * wrong one.
+ *
+ * Format is a constraint, not a preference. It is a plain `<img>` with no
+ * `<picture>` fallback and it is also the og:image, so it must be a format every
+ * browser AND every unfurler decodes. WebP is; AVIF is measurably better per byte
+ * on this image and was rejected because it is not.
+ */
+export const HERO_COVER = {
+  url: '/hero-cover-dark.webp',
+  width: 2400,
+  height: 1200,
+  alt: 'ObjectStack — the metadata framework for AI-written apps',
+} as const;