Fix table-of-contents page group's first item cut off after navigation (RND-11314)

[zenoachtig]

Linear issue: https://linear.app/gitbook-x/issue/RND-11314

Overview

• The first item of a table-of-contents page group in the sidebar could render cut off — its top faded out under the group header — most reliably after a client-side navigation (e.g. hitting a 404 route, then clicking the header logo to go home).
• The layout is correct; it's a stale compositing paint, which is why any DOM change makes the item snap back to normal.

Root cause

The collapsible-groups work (#4177) drives each sticky group header's fade gradient (an ::after band at top-full h-4, overlapping the group's first item) from an IntersectionObserver on a sentinel. It marked the header stuck whenever the sentinel stopped intersecting — but that also happens when:

• the group is simply below the fold, and
• transiently during a client-side navigation, before the sidebar's scroll container has laid out.

So the fade gradient switched on for groups that aren't actually pinned, and the compositor could leave it painted over the first item as a stale layer. It's always the first item because that's exactly what the gradient overlaps.

Fix

Mark the header stuck only once the sentinel has actually scrolled above the scroll area's top, instead of on any non-intersection:

const rootTop = entry.rootBounds?.top ?? 0;
setIsSticking(!entry.isIntersecting && entry.boundingClientRect.top < rootTop);

Verification

Verified against the live affected site by attaching a real IntersectionObserver with the new condition:

• At scroll 0 (nothing pinned): the old logic flags every below-fold group as stuck (fade on — the bug); the new logic reports all groups not-stuck (fade off).
• Scrolled so headers pin: genuinely-pinned headers still report stuck under the new logic (fade still works — no regression); below-fold groups correctly report not-stuck.

Typecheck and Biome format are clean on the change.

Manual check

1. Visit a 404 route on a docs site with page groups (e.g. …/asdf).
2. Click the header logo to return home.
3. The first item of each group (e.g. AI Features → Overview) should render fully — no faded/clipped top.
4. Scroll down and confirm items still fade softly as a group header pins to the top.

Changelog

• [Fix] The first item of a sidebar page group no longer appears cut off (faded under the group header) after navigating between pages.

— Authored by Claude

[linear-code]

RND-11314

[changeset-bot]

🦋 Changeset detected

Latest commit: 39bdbd0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
gitbook	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Summary of the deployments:

Version	URL	Status
Vercel	https://gitbook-v2-10vuphsoe-gitbook.vercel.app	✅
Cloudflare	https://ce71f095-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-10vuphsoe-gitbook.vercel.app/url/gitbook.com/docs	https://ce71f095-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-10vuphsoe-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://ce71f095-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.gitbook.io/test-gitbook-open

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
customers-v2-cloudflare (Inspect)	👍 Approved by Zeno Kapitein	4 changed, 2 ignored	Jul 14, 2026, 6:38 PM
customers-v2-vercel (Inspect)	👍 Approved by Zeno Kapitein	1 changed, 4 ignored	Jul 14, 2026, 6:37 PM
v2-cloudflare (Inspect)	⚠️ Changes detected (Review)	9 changed, 8 removed, 5 failures, 1 ignored	Jul 14, 2026, 6:43 PM
v2-vercel (Inspect)	⚠️ Changes detected (Review)	2 changed, 7 ignored	Jul 14, 2026, 6:39 PM