♻️ Reproduction Steps

1. Open https://docs.copilotkit.ai/quickstart in a fresh browser profile (banner not dismissed), at any width. It's most visible below 1280px, where the fixed MobileTopNav is shown.
2. Watch the first seconds of the load. DevTools network throttling makes it easier to see.

Measured with headless Chromium on the live site, iPhone 13 viewport (positions in CSS px):

• Unthrottled (3 runs): first paint at ~0.1 s with no banner, MobileTopNav at y = 8, page title at y = 136. At 2.2–3.5 s the banner appears, MobileTopNav moves to y = 40 and the title to y = 176.
• Throttled to 4 Mbit/s, 150 ms: the same, but the page sits in the no-banner layout for ~20 s before jumping. Most of that wait is the 40 MB chunk from 🐛 Bug: docs.copilotkit.ai ships the entire demo-content.json (40 MB of JS) to the browser on most pages, and re-downloads it on navigation #7821.
• At 890px wide: MobileTopNav y = 12 → 40.

✅ Expected Behavior

The first paint already has the final layout: the banner (or the space for it), with the header and content where they end up. A reader who dismissed the banner doesn't see it flash in.

❌ Actual Behavior

src/components/banners.tsx returns null until a useEffect has run (if (!hydrated || dismissed) return null), because it reads the dismissed state from localStorage. The same effect is what sets --fd-banner-height on (40px or 0px). So:

• Before hydration, there's no banner and --fd-banner-height is unset. MobileTopNav's top-(--fd-banner-height) has no fallback, so the fixed nav falls back to its static position (y = 8 below md, 12 at md).
• After hydration, the banner renders, the variable becomes 40px, and the header and everything below it move down by about 32–40px.

The jump happens on every page load for readers who haven't dismissed the banner. For readers who have, the variable goes from unset to 0px, which also moves the fixed nav by 8–12px.

Chrome's Layout Instability API reports no layout-shift entries for this jump (CLS 0 in the same runs, layout-shift supported), so Lighthouse and Web Vitals won't flag it. The positions above come from getBoundingClientRect sampling.

Possible fix:

• Render the banner on the server, so it's in the first paint.
• Decide dismissal before paint with a small inline script in that reads the localStorage flags and sets --fd-banner-height (or a class on that hides the banner). That's the same approach next-themes uses to avoid a theme flash.
• Give top-(--fd-banner-height) a fallback, e.g. top-[var(--fd-banner-height,0px)].

I'm happy to open a PR.

Screenshots

𝌚 CopilotKit Version

docs.copilotkit.ai (showcase/shell-docs @ main 500b40efb): next 16.2.6, fumadocs-core/ui 16.8.12, react 19.2

📄 Logs (Optional)

t≈100ms   MobileTopNav top=8   h1 top=136   --fd-banner-height unset   banner absent
t≈2800ms  MobileTopNav top=40  h1 top=176   --fd-banner-height 40px    banner 0–40