Skip to content

perf(core): a scroll region reads no layout while it attaches - #13013

Draft
vjeux wants to merge 1 commit into
meta:mainfrom
vjeux:perf/scroll-region-first-measure-after-layout
Draft

vjeux wants to merge 1 commit into
meta:mainfrom
vjeux:perf/scroll-region-first-measure-after-layout

Conversation

@vjeux

@vjeux vjeux commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Primary intent

Performance: a scroll region stops forcing a style and layout pass as it attaches. Nothing renders wrong (not a bug fix), and one product timing moves (not maintenance).

User or maintainer impact

A tap can mount a scrolling LayoutContent, LayoutPanel or StackItem, or AppShell's main under height="fill". The overflow observer then forces a style recalc and a layout inside React's commit. A product app's panel-open trace showed this pass.

Chromium, production Storybook builds, 4× CPU, 390×844 (test; median of 10 runs; stack-attributed):

A tap mounts Observer's forced work Tap task
a scrolling region on the page 8.5 → 0 ms 55.0 → 45.6 ms
AppShell with a fill main 15.8 → 0 ms 81.1 → 70.9 ms
a Dialog with a scrolling body 25.0 → 0 ms 150.6 → 148.9 ms

In the Dialog case, Dialog's own trigger read before showModal() then pays most of that pass (22.6 ms). This PR leaves Dialog unchanged.

Problem and solution fit

  • Why is there a forced pass? observeMainOverflow measured synchronously in the ref callback: getComputedStyle(main) and scroll geometry. It also read document.fonts.ready, which updates style and layout in Chromium.
  • Why does it harm? The commit leaves style dirty, so the read updates style and layout before the browser's own frame. In a closed dialog the result is "unknown" anyway.
  • Why does it matter? The pass delays the frame that shows the new content.

The change:

  • The first measurement waits for the first resize notification after layout (observeResizeAfterLayout on main and each direct child). No signal reads layout before it.
  • The fonts.ready read goes. The loadingdone listener still catches a late font.
  • Without a ResizeObserver, main is measured at once, as before.
  • One exception: when another subscriber already observes main, the helper calls back at once in a microtask. That first measurement can then still force a pass. No current caller observes main twice.

Authority

  • architecture:react-component-runtime INV18: with observeResizeAfterLayout, "a caller's first read comes from the browser's own first notification after layout".
  • The role, name and tab stop are "while" invariants: component:LayoutContent AR3, component:LayoutPanel AR3, component:Stack AR2, and component:AppShell FR4 through spec:AST-025 FR12. No record requires them at mount, first paint or hydration, so no record changes.
  • observeMainOverflow is internal. Its signature is unchanged.

Behavior change

The role and name, and AppShell main's tab stop, arrive 2–3 frames after the tap (median 2), after first paint, in 10 of 10 runs.

Owner question (proposed; pending owner review)

AppShell main's tab stop also moves to the first notification, because AppShell and the scroll regions share observeMainOverflow. Is that acceptable? If not, a variant limits the new timing to useScrollRegionProps.

Follow-up (not in this PR)

useScrollableArea also reads fonts.ready in a layout effect. For dialogs, Dialog's trigger read remains.

Scope

Components: AppShell (observeMainOverflow), LayoutContent, LayoutPanel, StackItem (through useScrollRegionProps)

  • This PR has one primary intent.
  • Independently removable deltas were removed or split.
  • Public text and artifacts contain no internal Meta context.

Testing

  • Red first: observeMainOverflow.test.ts gains three cases. On main all three fail: it reads getComputedStyle as it starts, it reads layout on a signal before the first notification, and it reads fonts.ready. With this change all 10 cases pass. AppShell's keyboard tests now send the browser's notification before they expect the tab stop.
  • pnpm test:ui: 1,091 files, 26,585 tests pass. pnpm -F @astryxdesign/core typecheck passes.
  • Chromium a11y specs, 66 of 66 (the audits on a SHA-stamped build): scrollRegionName, ContainerBlockBleed, MobileNavLandmark, AppShellMainKeyboard, AppShellSafeArea, LayoutContentAudit, LayoutPanelAudit.
  • Interaction specs collapsedPanel and AppShellLayoutRoot: Chromium 4 of 4, WebKit 4 of 4. AppShellMainKeyboard in WebKit: 15 pass, 1 skipped.
  • pnpm review:pre: 0 findings. Lint, Prettier and check:changesets pass.
  • Trace method: a scratch story taps to mount each case. A CDP trace records every forced style recalc and layout with its stack. A pass counts as the observer's when its stack includes the observer's code. Main and this head alternate, 10 runs per case.
Case (median ms, test) Observer's forced work Dialog's trigger read All forced work in the tap Tap task
Dialog mounted on open 25.0 → 0 0 → 22.6 49.1 → 45.8 150.6 → 148.9
Dialog body mounted on open 25.0 → 0 0 → 22.8 48.2 → 46.5 149.2 → 142.5
Region on the page 8.5 → 0 — 9.8 → 3.2 55.0 → 45.6
AppShell fill main 15.8 → 0 — 17.4 → 5.0 81.1 → 70.9
Dialog already mounted (control) 0 → 0 20.8 → 21.5 42.3 → 43.5 110.4 → 114.3

observeMainOverflow starts where a scroll container's ref attaches,
inside React's commit. It measured there at once, and it read
document.fonts.ready, which updates style and layout in Chromium. When
a Dialog mounts its body as it opens, both reads forced a style and
layout pass on the closed dialog, before showModal() restyles it.

The first measurement now waits for the first resize notification,
which comes after the browser lays main or a child out
(observeResizeAfterLayout). Until then no other signal reads layout.
A font that loads later still starts a measurement through the
loadingdone event. Where no ResizeObserver exists, main is measured
at once, as before.

The region's group role and name, and AppShell main's tab stop, now
arrive with that first notification instead of during the commit.
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 19, 2026 9:48pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 19, 2026, 9:41 PM UTC

@github-actions

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@cixzhang cixzhang added ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) labels Nov 19, 2026
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 667d520

This branch was successfully deployed

1 active deployment
Preview — 667d520d Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants