feat(background): film strip background, frosted glass, hero under the navbar

[kris1027]

What

This PR swaps the old ambient background for the film strip scene from the v2 Claude Design file: three coiled film strips and rising bokeh over a teal gradient, drawn in hand written WebGL2. It also makes controls, panels and overlays frosted glass, so the scene shows through them, blurred. On title pages, the backdrop image now reaches up behind the navbar.

Why

You asked for the new background design and for glass surfaces that let it show through. The decisions are recorded in three plans:

• prompts/film-strip-background.md: the scene, how it is delivered, budgets, contrast cap
• prompts/film-scene-continuity.md: the intro plays once per tab
• prompts/frosted-glass.md: which surfaces frost, which stay solid, and the AA math

Changes

Film strip background

• New lib/film-scene/ module (budget, layout, palette, matrices, shaders, scene, clock, run, messages, worker, start, continuity). It replaces lib/backdrop/ and adds no new dependency (no three.js).
• Each frame takes two WebGL2 programs and strips + 1 draw calls. The film frame is drawn procedurally in the fragment shader, and the bokeh motion runs in the vertex shader.
• PageBackground (Server Component) paints the gradient and vignette as CSS, so they are the first paint and the fallback. PageBackgroundCanvas imports the scene only when the browser is idle.
• The scene runs in a worker where OffscreenCanvas supports WebGL2, and on the main thread otherwise. Worker messages are validated with Zod.
• Budgets: the pixel ratio is capped at 1.5. Below 768px or with a coarse pointer, it draws 2 strips and 35 bokeh, otherwise 3 strips and 70 bokeh.
• Reduced motion draws one still frame. A hidden tab pauses the loop and resumes without a jump. Without WebGL2, or after a context loss, only the CSS layers remain, with nothing thrown.
• Every fragment is clamped so text-muted-foreground keeps 4.5:1. The bokeh uses MAX blending, so overlapping discs cannot add up past that cap.
• The design's cursor parallax is gone: the camera is fixed and no pointer listener is added.
• The intro plays once per tab. The clock time is kept in sessionStorage (bestats:film-scene), so a reload or a rebuild across the breakpoint carries on without the fade. The /showcase still frame never touches that key.
• The gradient was later retuned: brighter along the top, with a vignette that also deepens the bottom half.

Frosted glass

• New --frost-* opacity tokens and --blur-control/panel/overlay tokens. The glass-plate* utilities now blend the plate colour with transparency and set backdrop-filter, with the -webkit- prefix included.
• New glass-plate-float for the popover, quick search and toasts. New plate-solid for slots over poster artwork, missing poster tiles and skeletons, which stay opaque.
• Selected surfaces keep an opaque plate. The glass sheen drops from 18% to 12% white.
• Reduced transparency, higher contrast, and no backdrop-filter support all bring back the opaque plates with no blur.
• New app/glass-contrast.test.ts composites each plate over its worst background and fails on any text token below 4.5:1.

Title hero and chrome

• On title pages, the backdrop extends up behind the navbar (--navbar-height). A backdrop-scrim keeps the bar readable, and the navbar gets relative z-20.
• The hero fades into the page with a CSS mask instead of --background gradients, so it dissolves into the film background rather than ending in a black band. The skeleton matches the new geometry.
• The footer loses the hairline above the icon key.

Docs and showcase

• /showcase gets a Page background section (token swatches and the still frame) and an updated plate rule section showing frosted, solid and fallback surfaces.
• components/AGENTS.md rewrites the background, plate and blur rules and ends the personal cyan exception for the background.

How to test / verify

• Run pnpm typecheck && pnpm lint && pnpm test && pnpm build.
• Check that rg -i "lib/backdrop|ambient-(canvas|background)|backdrop-wave|backdrop-dust" finds nothing outside prompts/.
• In pnpm dev, open /shows. The gradient paints first, then the strips and bokeh fade in. Moving the mouse changes nothing.
• Reload the same tab: the strips appear with no fade, in a later pose. A new tab fades in once.
• Emulate prefers-reduced-motion: reduce: the scene freezes. Hide the tab and come back: it resumes without a jump.
• Disable WebGL and reload: only the gradient and vignette show, with no console errors.
• Check the navbar tabs, search field, buttons and panels: they show the scene blurred behind them. Poster badges and round buttons look as they did before.
• Emulate prefers-reduced-transparency: reduce, then prefers-contrast: more: the surfaces turn solid.
• Open a movie or show: the backdrop sits behind the navbar, the bar text is readable, and the image fades into the film background.
• Open /showcase and look at the Page background and plate rule sections.

Risk & rollout

No migrations, no environment values, no flags, and no new runtime dependency. Every change is client side visuals or CSS.

• Performance: the scene and worker are separate chunks loaded after idle. The plan measured about 7.5 KB and 5.7 KB gzipped. Blur cost is limited by the nesting rule and by the solid slots on poster grids.
• Layout: backdrop-filter creates a containing block and a stacking context, which could affect fixed children inside plated elements. Base UI portals its popups.
• Rollback: revert the PR.

Notes for reviewers

• Look closely at lib/film-scene/scene.ts. gl.clear respects depthMask, and the bokeh pass leaves it off. Without turning it back on before each clear, strips flickered and a redrawn still frame lost them. scene.test.ts guards this.
• The frost values in globals.css (control 65%, panel 60%, sheet 75%, float 90%, score 65%) come from glass-contrast.test.ts. Please don't lower them without rerunning it.
• prompts/ambient-background.md is kept as history, with a pointer to the new plan.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
bestats	Ready	Preview	Oct 11, 2026 1:28pm UTC