fix: resolve sidebar overflow when browser height is insufficient

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file.
 
 ### 🐛 Bug Fixes
 - **MagicStarterUserProfileDropdown**: Fixed menu overflow when many profile menu items are registered — wrapped menu items in scrollable `overflow-y-auto` WDiv, keeping header and logout footer fixed (#28)
+- **Sidebar Navigation**: Fixed overflow when many nav items exceed viewport height — added `overflow-y-auto` to navigation WDiv so items scroll while brand, team selector, and user menu remain fixed (#29)
 
 ## [0.0.1-alpha.11] - 2026-04-07
 

lib/src/ui/layouts/magic_starter_app_layout.dart

@@ -325,7 +325,7 @@ class _MagicStarterAppLayoutState extends State<MagicStarterAppLayout> {
 
     // Default fallback: Dashboard + Profile.
     return WDiv(
-      className: 'flex flex-col gap-1 py-2',
+      className: 'flex flex-col gap-1 py-2 overflow-y-auto',
       children: [
         _navItem(
           context,
@@ -354,7 +354,7 @@ class _MagicStarterAppLayoutState extends State<MagicStarterAppLayout> {
     VoidCallback? onItemTap,
   }) {
     return WDiv(
-      className: 'flex flex-col py-2 gap-1 w-full',
+      className: 'flex flex-col py-2 gap-1 w-full overflow-y-auto',
       children: [
         // Main navigation items
         ...config.mainItems.map(

test/ui/layouts/magic_starter_app_layout_test.dart

@@ -343,4 +343,43 @@ void main() {
       },
     );
   });
+
+  group('MagicStarterAppLayout sidebar navigation scroll', () {
+    testWidgets(
+      'sidebar does not overflow with many nav items in short viewport',
+      (tester) async {
+        // Short viewport to trigger overflow scenario.
+        tester.view.physicalSize = const Size(1200, 500);
+        tester.view.devicePixelRatio = 1.0;
+
+        addTearDown(() {
+          tester.view.resetPhysicalSize();
+          tester.view.resetDevicePixelRatio();
+        });
+
+        // Register 10+ nav items to exceed viewport height.
+        MagicStarter.useNavigation(
+          mainItems: [
+            for (int i = 0; i < 12; i++)
+              MagicStarterNavItem(
+                icon: Icons.circle,
+                labelKey: 'Nav $i',
+                path: '/nav-$i',
+              ),
+          ],
+        );
+
+        await tester.pumpWidget(
+          createApp(
+            child: const SizedBox(),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        // No overflow error means the navigation area scrolls correctly.
+        // Verify that the layout rendered without exceptions.
+        expect(find.text('Nav 0'), findsOneWidget);
+      },
+    );
+  });
 }