[AKnassa]

Step 2 of #5392. Fixes #5470.

What this does

Keeps the home page hero pinned exactly as it is today, but without the CSS rule that switched off the browser's native overscroll. On a Mac trackpad the page rubber-bands again at the top and bottom, like every other page on the web. Nothing changes visually.

Why

The hero's three pinned layers (the aurora glow, the floating cards and the headline block) were position: fixed. A fixed layer is glued to the screen rather than to the page, so when the page rubber-bands past its own end the layer sits in the gap that opens up. #3032 hid that by turning overscroll off for the whole site, and #5415 narrowed the rule to desktop widths to give mobile its pull-to-refresh back. This finishes the job: the layers are now position: sticky inside full-height rails, so they lift with the page and physically cannot paint past its end. That is structural, which is why the rule can be deleted instead of narrowed further.

What changed

• Each pinned layer rides its own rail: a position: absolute; inset: 0 box that is a direct child of heroScope, spans the hero band and the showcase, and sits ahead of the showcase overlay so tree order still equals paint order (backdrop, cards, hero text, then the showcase covering them). A rail inside the 760px band alone releases its layer after about 48px, which is the trap the issue calls out.
• backdropGlow, the cards stage and heroContent go fixed -> sticky; top: var(--appshell-header-height) at 1024px and up. Narrow widths are untouched: the glow stays absolute and the hero text stays in flow.
• Centering moves from left: 50% + translateX(-50%) to auto margins in the full-width rail (on a sticky box left is an inset, not an offset). The 1200px box is capped to the rail's width rather than 100vw: with a classic scrollbar 100vw is wider than the rail, which zeroes the auto margins and shoves the box left.
• HeroReelProvider renders no DOM any more. Its hover / focus / touch surface is the new HeroReelSwipeArea, which page.tsx uses as the hero text's rail, so the band and its gutters still pause the reel and the phone collage still swipes. HeroReelCards is split into HeroReelBackdrop (fills + glow) and HeroReelCards (stage).
• The @media (min-width: 1024px) { html { overscroll-behavior-y: none } } block is deleted from globals.css.
• Sticky also needs AppShell's main area to stay a non-scroll container (overflow: clip in LayoutContent; hidden or auto there would silently un-pin the landing page). That is recorded on the hero's rail style and enforced by the test below; core is untouched.
• New home-hero-overscroll.test.ts. The docsite suite is node-only with StyleX untransformed, so these are source invariants in the shape of component-preview-theme.test.ts: globals.css never sets overscroll-behavior on html, :root, body or * away from auto, at any width (a contain on a nested scroller is fine; the guard has its own fixtures for @media and @supports wrappers, :is() / :where() and upper-case selectors); none of the three layers is ever fixed in any media arm; the rails are bounded by heroScope and precede the showcase; the boxes are sized against the rail, not 100vw; and the AppShell / LayoutContent links that keep the main area a non-scroll container (overflow: clip, isScrollable={isFill}, the landing layout's height="auto") hold. It is red on main today, and single-line mutations (a fixed behind a trailing comment, double quotes, a computed [BREAKPOINT] key, an overflowY longhand, isScrollable unconditional, height="fill", the width back to 100vw, heroScope static, a rail moved after the showcase, the old @media root rule, :root { overscroll-behavior: contain }, an upper-case HTML rule, a minified root rule, a root rule inside @supports) each turn it red again.

How to see it

Nothing should look different; that is the point. Run the docsite with the canary banner off so the header is the production 48px (NEXT_PUBLIC_DOCS_TARGET=latest pnpm -F @astryxdesign/docsite dev), open the home page on a Mac and rubber-band at the bottom: the page bounces and the footer stays clean. The Vercel preview on this PR shows the same page.

Measured against an untouched main checkout with Playwright + pixelmatch, both served with the banner hidden, prefers-reduced-motion: reduce so the reel holds its first slide, and transitions frozen, at ten scroll offsets per viewport (0, 100, 200, 400, 712, 760, 800, 1400, 2200, max):

viewport	pixels differing from main	overscroll-behavior-y	fixed layers reaching the viewport bottom at page end
1280 x 900	0	none -> auto	2 -> 0
1280 x 600	0	none -> auto	3 -> 0
1440 x 1400	0	none -> auto	0 -> 0
1024 x 768	0	none -> auto	2 -> 0
900 x 1200	0	auto -> auto	0 -> 0
390 x 844	0	auto -> auto	0 -> 0

Layer geometry matches fixed at every offset (hero text at y=48 and 712px tall, glow and stage at x=40 and 1200px wide at 1280) until max scroll, where sticky releases behind the opaque showcase. Document height is unchanged (3540px). elementFromPoint on the "Get started" button still returns the button.

Also checked on both trees: hover in the gutter, on the CTA and over the pinned hero while scrolled pauses the reel, hover on the showcase does not, keyboard focus on a dot pauses and blur resumes, a phone swipe steps the reel left and right and a vertical drag does not (11 checks, identical results before and after); resize while scrolled (1280 -> 1440 -> 1100 at scroll 400) and a theme swap mid-scroll with transitions running, 0 pixels differing; and a forced 15px classic scrollbar, where the old fixed box sat at x=-7.5 overflowing both sides and the new one sits centered inside the rail.

pnpm -F @astryxdesign/docsite test (29 files, 434 tests), tsc --noEmit, strict eslint and prettier are green.

Not verified here

Safari and WebKit, and a real rubber-band gesture, which cannot be driven headlessly. That is the careful visual pass the issue budgets for.

Related

• fix(docsite): bound the hero's pin so overscroll works everywhere #5431 takes the other route the issue mentions (a zero-height sticky pin with absolute children) and has been conflicting since fix(docsite): restore pull-to-refresh on mobile, scope the overscroll suppression to desktop #5415 landed; this follows the rails design written up in docsite: contain the desktop-pinned hero layers so overscroll suppression can be removed entirely #5470 instead.
• docs(docsite): correct two stale backdropGlow comments left by #5415 #5467 (merged) corrected the backdropGlow comment's causal chain; this branch carries that wording and updates its tail for the deleted rule.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Error		Sep 26, 2026 4:25am UTC

[github-actions]

PR Analysis Report

Current run: The current CI run completed, but its trusted analysis is unavailable.

The exact-head preview is not available yet.

---

_{Generated by PR Enrichment workflow | View current CI run}

[xinzi-bot]

Thanks for finishing the desktop half of #5392. The separate rails, rail-relative 100% sizing, dedicated interaction surface, and regression coverage all look good.

Before merging, could you please make three changes?

1. Rebase onto current main and resolve the HeroThemeReel.tsx conflict. Please preserve docs(docsite): correct two stale backdropGlow comments left by #5415 #5467’s corrected causal explanation: the glow did not itself disable pull-to-refresh; the global overscroll-behavior-y: none rule did.
2. Drop the comment-only change to packages/core/src/Layout/LayoutContent.tsx. It makes this docsite fix appear to modify a published core component and triggers the full core review/CI path. The warning is better kept in the hero source and regression test, which already enforce overflow: clip.
3. Narrow the globals.css regression assertion. It currently rejects every non-auto overscroll-behavior declaration anywhere in the file. That would also reject a legitimate future contain rule on a nested scroller. Please target suppression on html, :root, or another page-wide selector instead.

After the rebase, please rerun CI and verify the preview. The current Vercel and visual failures appear to be preview/infrastructure issues rather than evidence of a problem with the sticky-rail approach.

[AKnassa]

Done, thanks. Rebased onto current main and resolved HeroThemeReel.tsx keeping #5467's causal chain, with its tail updated for the deleted rule. Dropped the LayoutContent change; the clip note now sits on the hero's rail style and the test still enforces it in core. The globals.css guard now only reports overscroll-behavior on html, :root, body or * (looking through :is() and :where()), with its own fixtures, so a contain on a nested scroller passes.

[astracat-bot]

Thanks for finishing this — the sticky-rail approach is the right structural fix: bounding the glow, cards, and hero text inside full-height rails preserves the pinned hero while letting the root overscroll rule be deleted instead of narrowed again. The provider/swipe-surface split and the rail ordering also look sound in static review, and the hosted docsite tests pass.

One focused change is needed before this is ready:

• Fix the selector classifier in home-hero-overscroll.test.ts. isPageWide currently treats any final * as page-wide, so legitimate nested rules such as body .dialog * or .dialog * with overscroll-behavior: contain would be rejected. It also only unwraps :is() / :where() when the wrapper is the whole selector compound, so composed root rules such as :is(html, body).mode or :is(html, body):hover would be missed and could bring back the site-wide overscroll suppression undetected. Please classify the actual root/body subject, handle wrappers with following class or pseudo-class suffixes, and add fixtures for both directions.

Safari/WebKit and a real trackpad rubber-band gesture remain unverified, as noted in the PR; please keep that manual check in view, but it is not the reason for this request. No change to the sticky hero runtime is being requested for this finding.

[Automated review]

[AKnassa]

Thanks, both directions reproduced on eef4fd2. I pushed two test-only commits. The sticky hero runtime is unchanged.

• Nested * rules (16d7e27, 8b68a13): a trailing * now counts as page-wide only when it can land on html or body. That means on its own, under the root, or after head (*, html *, :root > *, * + *, head + *). With contain, .dialog *, body .dialog *, .sheet > * and .stack > * + * now pass.
• Composed root rules (16d7e27): the splitter keeps (), [] and quoted strings whole. The subject compound counts as page-wide when any top-level part is html, body or :root, or is an :is()/:where() whose list is page-wide. :not()/:has() arguments are ignored. :is(html, body).mode, :is(html, body):hover, :where(html)[data-hero-dark], [data-x]:where(html), html[class~='dark'] and body[data-mode='a b'] are now reported.
• New fixtures cover both directions and failed before the change. The file passes 21/21, including the assertion against the real globals.css.

Left out on purpose: CSS nesting isn't resolved, because globals.css doesn't nest. A * after a compound made only of classes or pseudo-classes (:first-child + *) isn't treated as root, and neither are namespace forms (*|*).

The Safari/WebKit trackpad rubber-band check is still manual, and I haven't done it yet.

[astracat-bot]

This looks ready to merge: the sticky rails keep the home hero pixel-identical at rest and while scrolling, release the pinned layers before the footer at the page end, and so let the root overscroll-behavior-y: none rule go, and the new guard fails without the fix and passes with it. Before landing, please do the Safari trackpad pass you flagged at both ends of the home page, including a pull at the very top on a non-default slide: navBackdrop is still position: fixed, and a simulated 40px pull leaves its tint at the top while the nav slides over the white page canvas. The branch merges cleanly with current main and the guard passes on that merge, but CI has not run against today's AppShell, so a fresh CI run on the updated branch is worth having.

[Automated review]

[astracat-bot]

The sticky rails keep the home hero pixel-identical at rest and while scrolling, release the pinned layers before the footer, and the new guard fails without the fix and passes with it, so no code change is requested. Approval now waits on a maintainer decision: no current spec covers the docsite root's overscroll, so a maintainer needs to provide or identify the governing spec for restoring native overscroll on every docsite route at 1024px and wider (for example a claim in spec:AST-033), or explicitly accept it without one. The Safari trackpad pass you flagged is still worth doing at both ends of the home page, including a pull at the very top, where the still-fixed navBackdrop may stay behind while the nav moves.

[Automated review]