feat(layout)!: the shell's content box no longer scrolls; pages scroll themselves

[anilcancakir]

What

• Breaking: MagicStarterLayoutTheme.contentClassName defaults to 'flex-1 min-h-0' and contentScrollPrimary to false (previously 'flex-1 overflow-y-auto' and true). The shell's content box no longer scrolls, and each routed page scrolls itself.
• The notification screens take the host page geometry through their contentClassName, inside their own scroll view, rather than wrapped in MSPageContainer.
• The starter:install dashboard stub gets its own scroll view.
• The theme docs, doc/basics/views-and-layouts.md and three comments now describe the new shape. The CHANGELOG has a ### Breaking entry with migration steps and one known loss.

Why

In a go_router shell the route child is the nested Navigator, so the old default scrolled the Navigator and laid its Overlay out under an unbounded height. A page left under a .stacked() route was then never laid out again, and its second rebuild while hidden failed _debugRelayoutBoundaryAlreadyMarkedNeedsLayout in debug and left the tree inconsistent. Closes #160; upstream is flutter/flutter#193247, reproduced in a fresh app, with a SizedBox.expand control that stays clean.

Testing

• New test: a go_router ShellRoute on MagicStarterAppLayout, with a list and a pushed detail, and the hidden list rebuilt three times. Red on the old default with the assertion, green on the new one.
• New notification-routes test: each screen's scroll view fills the page, so the padding scrolls with the content. Red before the geometry move (a 32px inset), green after. The width cap is now measured on the capped column.
• Three tests that pinned the old default now exercise the scrolling box as an explicit opt-in.
• flutter analyze clean, 1552 tests green, dart format --set-exit-if-changed . clean.

Downstream

• uptizm is unaffected: it registers its own layout.app.
• magic_example uses the default shell, and its DashboardView has no scroll view of its own. A matching PR in that repository wraps it.
• Lost: tapping the iOS status bar no longer scrolls a shell page to the top, because nothing is attached to the primary controller above the nested Navigator any more. This is noted in the CHANGELOG; restoring it is a separate change.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[kodizm]

Note

Kodizm (AI-generated). May contain mistakes; verify before acting.

The change looks correct. I found nothing to fix before merging. The break is deliberate, and the CHANGELOG, the docs and the tests all cover it.

I checked these points:

• Starter screens still scroll. MSPageScaffold screens already scroll themselves, and so does the invitation card (fix(teams): the invitation-accept screen scrolls itself #164). The two notification screens now get the geometry from pageContainerRecipe(hostClassName: …) and apply it inside their own scroll view. So the non-scrolling flex-1 min-h-0 box doesn't leave any shipped screen without a scroll.
• Dropping MSPageContainer from the notification mount loses nothing. That wrapper added a horizontal-only SafeArea. The shell's body already sits in a SafeArea(bottom: false) (lib/src/ui/layouts/magic_starter_app_layout.dart:244), and those routes never use the immersive branch, so the left and right insets are still handled.
• The starter:install stub still compiles. dashboard_view.stub already imports package:flutter/material.dart, so its new SingleChildScrollView(primary: false) resolves. Only the indentation and the new outer wrapper changed.
• Repo rules are followed. The CLAUDE.md post-change checklist (CHANGELOG under [Unreleased] and a doc/ update) is met. The README doesn't mention these fields.
• Known loss. The PR says tapping the iOS status bar no longer scrolls a shell page to the top, and the CHANGELOG says so too. That is a product decision, not a defect.

The downstream magic_example DashboardView depends on the companion PR the description mentions. Until that PR lands, the example renders cut off at the window. It lives in another repository, so it is outside this review.

Tests

There is a new go_router ShellRoute regression test in which a hidden page is rebuilt three times under a pushed route. A new test checks that each notification screen's scroll view fills the page. The three earlier tests of the old default now opt into the scrolling box explicitly, and the default-value test now expects flex-1 min-h-0 / false.

CI

• Lint & Test: success
• Published graph: success
• codecov/patch: success
• Auto-merge low-risk Dependabot PRs: skipped