feat(hero): shader hero backgrounds + site-wide Open Graph images

[danielheene]

Summary

Two related features:

A. Shader hero backgrounds. Content editors can now choose a live WebGL shader (DarkVeil, FaultyTerminal, GradientBlinds, Grainient) as an alternative to uploaded media for the hero background on Pages and BlogPosts, picked via a visual admin drawer showing 4 live-animating previews.

• New shared HeroBackgroundField() Payload field (backgroundType: 'media' | 'shader' discriminator).
• Custom admin field component: click-to-open drawer, 4 live shader previews, pick-and-close — modeled on this repo's existing icon-picker pattern, including readOnly handling.
• HeroMedia gained a shader-rendering branch (dynamically imported, ssr: false — the shader components touch window outside any effect).
• Pages' hero.media and BlogPosts' flat heroImage both migrated to hero.background, with every dependent call site updated (list-view thumbnails, card thumbnails, JSON-LD, seed generators).
• seedPages/seedPosts now occasionally (~25%, deterministic) pick a shader background.

B. Site-wide Open Graph images. Investigating "what OG image does a shader-backed post get" surfaced that OG images weren't actually wired up for any page before this — the existing root opengraph-image.tsx was unfinished placeholder scaffold, and generateMeta's openGraph block was entirely commented out. This PR:

• Swaps next/og for takumi-js/response (native Tailwind v4 support, real CSS gradients, faster).
• Adds real, per-document OG images for every route: Pages/BlogPosts (hero-aware — real image or a static gradient approximation for shader-backed heroes), BlogTopics, /blog + pagination, and ResumeDocuments (which had no metadata at all before this).
• Completes generateMeta's openGraph block (title/description/siteName, relying on Next's auto-discovery of each route's opengraph-image.tsx).

Process

Built via Subagent-Driven Development: 14 planned tasks, each implemented and reviewed independently, followed by a final whole-branch review. Real bugs caught and fixed along the way:

• A link()-adjacent field-shape mismatch is not part of this branch, but two genuine admin-thumbnail regressions were: listViewThumbnailPath on both Pages and BlogPosts needed a .value suffix to correctly resolve through Payload's polymorphic upload-relation wrapping — traced through the real runtime code, not guessed.
• The admin shader picker completely failed to render in the browser during final verification — root cause was a generated import-map file never being regenerated after the component was added. Caught only because that verification step used a real browser, not just typecheck/tests/build.
• The final whole-branch review caught generateMeta's openGraph block still being commented out (a spec requirement that fell into a gap between tasks) and one unguarded shader-preset lookup in the blog list page (the only one of four consumers without a guard, in a server component with the widest blast radius).

Verification

• pnpm typecheck — clean
• pnpm vitest run — 82 files, 686 tests passing
• pnpm build — succeeds, 49 pages generate
• Manual end-to-end verification with a real browser: admin shader picker drawer opens with 4 visibly-animating previews, selection persists through publish+reload, frontend hero reflects the change and animates live; all OG image routes fetch and return valid 1200×630 PNGs.

Known follow-up (out of scope here, flagged for a separate PR)

app/(frontend)/blog/post/[slug]/page.tsx computes blogPostingSchema/breadcrumbSchema JSON-LD but never renders them into a <script> tag — a genuine pre-existing bug, not introduced by this branch. Fixing it properly also requires correcting postUrl (currently points at /posts/<slug>, but the real route is /blog/post/<slug>) — rendering the schema as-is first would publish worse structured data than not rendering it at all, so this needs its own change with its own verification (Rich Results Test), not a tail-end addition here.

Non-goals (per the design spec)

No per-prop shader customization in the admin, no StaticMeshGradient support (non-functional in this repo), no shader support for HeroMedia callers outside Pages/BlogPosts, no hero.background field added to BlogTopics/ResumeDocuments//blog.

🤖 Generated with Claude Code