kasy-cli 1.20.0 → 1.20.1

package/lib/utils/i18n/messages-pt.js

@@ -524,7 +524,7 @@ module.exports = {
     'new.firebase.module.sentry': '🚨 Crash Reports (Sentry)',
     'new.firebase.module.analytics': '📊 Analytics (Mixpanel)',
     'new.firebase.module.facebook': '👤 Facebook (Login + Ads)',
-    'new.firebase.module.web': '🌐 Web Support (PWA, somente Firebase)',
+    'new.firebase.module.web': '🌐 Web Support (PWA)',
     'new.firebase.module.widget': '📱 Home Widget (iOS/Android)',
     'new.firebase.module.llm_chat': '🤖 AI Chat (OpenAI/Gemini)',
     'new.firebase.module.local_notifications': '🔔 Local Reminders (sem servidor)',
@@ -692,6 +692,10 @@ module.exports = {
     'new.google.refreshConfigs': 'Atualizando google-services.json e GoogleService-Info.plist com Client IDs do Google…',
     'new.google.manualHint': 'Login com Google: ative manualmente no Console (provedor Google):',
     'new.google.manualHint.noEmail': 'Login com Google: não consegui detectar um e-mail de suporte (gcloud sem conta). Ative manualmente no Console:',
+    'new.google.supabaseManual': 'Login com Google: client criado, mas o secret ainda não estava disponível. Ative depois no painel do Supabase (Authentication > Providers > Google).',
+    'new.fcm.ok': 'gerada automaticamente',
+    'new.fcm.failSupabase': 'não gerada (permissão do GCP ainda propagando); defina FIREBASE_SERVICE_ACCOUNT_JSON nos secrets do Supabase',
+    'new.fcm.failApi': 'não gerada (permissão do GCP ainda propagando); rode o comando de novo em alguns minutos',
     'new.sha1.registering': 'Registrando SHA-1 para Google Sign-In (Android)…',
     'new.sha1.failed': 'SHA-1 não adicionado automaticamente: {error}',
     'new.sha1.manual': 'Adicione manualmente para o Google Sign-In funcionar no Android:',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.20.0",
+  "version": "1.20.1",
   "description": "CLI for scaffolding production-ready Flutter SaaS apps with Firebase, Supabase, or API REST backends.",
   "bin": {
     "kasy": "./bin/kasy.js"

package/templates/firebase/lib/components/kasy_sidebar_pro.dart

@@ -309,7 +309,9 @@ class _KasySidebarProState extends State<KasySidebarPro> {
     // Use a Column that fills the sidebar height.
     // Top section scrolls if content overflows; bottom items (Help + Logout)
     // stay pinned to the bottom via Spacer in the outer Column.
-    return Positioned.fill(
+    // SizedBox.expand (not Positioned.fill) because the parent here is a
+    // DecoratedBox, not a Stack — Positioned only works as a direct Stack child.
+    return SizedBox.expand(
       child: Column(
         crossAxisAlignment: CrossAxisAlignment.start,
         children: [

package/templates/firebase/lib/core/bottom_menu/bottom_menu.dart

@@ -1,5 +1,4 @@
 import 'package:bart/bart.dart' as bart;
-import 'package:bart/bart/bart_bottombar_actions.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
@@ -11,79 +10,18 @@ import 'package:kasy_kit/core/widgets/responsive_layout.dart';
 
 /// Bottom navigation host powered by Bart (https://pub.dev/packages/bart).
 ///
-/// Bart's [bart.BartScaffold] owns a [ValueNotifier<bool>] for bottom-bar
-/// visibility, created in its constructor. Two issues fall out of that:
-///
-///   1. [ResponsiveLayout] swaps between three [bart.BartScaffold]s (small /
-///      medium / large). Any rebuild (theme toggle, locale switch,
-///      device-preview resize) instantiates a fresh notifier with the initial
-///      value, dropping whatever visibility we had set.
-///   2. Bart's [bart.BartScaffold.onRouteChanged] only fires when the active
-///      *tab index* changes — pushing an inner route inside the same tab
-///      (e.g. `home → home/components`) is silent. We can't drive visibility
-///      from that callback alone.
-///
-/// We solve both by treating inner-route presence as the source of truth.
-/// [BottomBarVisibilityScope] exposes a counter; the [HomeInnerRoute] wrapper
-/// increments while mounted and decrements on dispose. This widget reacts to
-/// the counter (and to lifecycle resume + every rebuild) and re-asserts the
-/// matching [BottomBarIntent] on Bart.
-class BottomMenu extends StatefulWidget {
+/// [ResponsiveLayout] swaps between three [bart.BartScaffold]s (small / medium /
+/// large) based on width. The bottom bar shows on every tab; detail screens
+/// (Features, Components, …) are pushed on the root navigator from the pages
+/// themselves, so they cover this menu and there's nothing to toggle here.
+class BottomMenu extends StatelessWidget {
   final String? initialRoute;
 
   const BottomMenu({super.key, this.initialRoute});
 
-  @override
-  State<BottomMenu> createState() => _BottomMenuState();
-}
-
-class _BottomMenuState extends State<BottomMenu>
-    with WidgetsBindingObserver, BartNotifier {
-  final ValueNotifier<int> _innerRouteDepth = ValueNotifier<int>(0);
-
-  @override
-  void initState() {
-    super.initState();
-    WidgetsBinding.instance.addObserver(this);
-    _innerRouteDepth.addListener(_scheduleSync);
-  }
-
-  @override
-  void dispose() {
-    _innerRouteDepth.removeListener(_scheduleSync);
-    _innerRouteDepth.dispose();
-    WidgetsBinding.instance.removeObserver(this);
-    super.dispose();
-  }
-
-  @override
-  void didChangeAppLifecycleState(AppLifecycleState state) {
-    super.didChangeAppLifecycleState(state);
-    if (state == AppLifecycleState.resumed) {
-      _scheduleSync();
-    }
-  }
-
-  void _scheduleSync() {
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      if (!mounted) return;
-      if (_innerRouteDepth.value > 0) {
-        hideBottomBar(context);
-      } else {
-        showBottomBar(context);
-      }
-    });
-  }
-
   @override
   Widget build(BuildContext context) {
-    // Re-assert visibility after every rebuild: the BartScaffold underneath
-    // may have been freshly instantiated (see class doc).
-    _scheduleSync();
-
-    final String? resolvedInitialRoute = _resolveInitialRoute(
-      widget.initialRoute,
-    );
+    final String? resolvedInitialRoute = _resolveInitialRoute(initialRoute);
     final bool showBottomBarOnStart = _shouldShowBottomBarOnStart(
       resolvedInitialRoute,
     );
@@ -91,44 +29,39 @@ class _BottomMenuState extends State<BottomMenu>
       backgroundColor: context.colors.background,
     );
 
-    return BottomBarVisibilityScope(
-      innerRouteDepth: _innerRouteDepth,
-      child: AnnotatedRegion<SystemUiOverlayStyle>(
-        value: switch (Theme.brightnessOf(context)) {
-          Brightness.dark => SystemUiOverlayStyle.light,
-          Brightness.light => SystemUiOverlayStyle.dark,
-        },
-        child: ResponsiveLayout(
-          small: bart.BartScaffold(
-            routesBuilder: subRoutes,
-            bottomBar: kasyPaddedSurfaceBottomBar(),
-            initialRoute: resolvedInitialRoute,
-            showBottomBarOnStart: showBottomBarOnStart,
-            scaffoldOptions: scaffoldOptions,
-          ),
-          // medium (768–1024 px): KasySidebarPro auto-collapses at this width
-          medium: bart.BartScaffold(
-            routesBuilder: subRoutes,
-            bottomBar: kasyPaddedSurfaceBottomBar(),
-            initialRoute: resolvedInitialRoute,
-            showBottomBarOnStart: showBottomBarOnStart,
-            scaffoldOptions: scaffoldOptions,
-            sideBarOptions: bart.CustomSideBarOptions(
-              sideBarBuilder: (routes, onTap, current) =>
-                  const KasySidebarPro(),
-            ),
+    return AnnotatedRegion<SystemUiOverlayStyle>(
+      value: switch (Theme.brightnessOf(context)) {
+        Brightness.dark => SystemUiOverlayStyle.light,
+        Brightness.light => SystemUiOverlayStyle.dark,
+      },
+      child: ResponsiveLayout(
+        small: bart.BartScaffold(
+          routesBuilder: subRoutes,
+          bottomBar: kasyPaddedSurfaceBottomBar(),
+          initialRoute: resolvedInitialRoute,
+          showBottomBarOnStart: showBottomBarOnStart,
+          scaffoldOptions: scaffoldOptions,
+        ),
+        // medium (768–1024 px): KasySidebarPro auto-collapses at this width
+        medium: bart.BartScaffold(
+          routesBuilder: subRoutes,
+          bottomBar: kasyPaddedSurfaceBottomBar(),
+          initialRoute: resolvedInitialRoute,
+          showBottomBarOnStart: showBottomBarOnStart,
+          scaffoldOptions: scaffoldOptions,
+          sideBarOptions: bart.CustomSideBarOptions(
+            sideBarBuilder: (routes, onTap, current) => const KasySidebarPro(),
           ),
-          // large (1024 px+): full expanded sidebar
-          large: bart.BartScaffold(
-            routesBuilder: subRoutes,
-            bottomBar: kasyPaddedSurfaceBottomBar(),
-            initialRoute: resolvedInitialRoute,
-            showBottomBarOnStart: showBottomBarOnStart,
-            scaffoldOptions: scaffoldOptions,
-            sideBarOptions: bart.CustomSideBarOptions(
-              sideBarBuilder: (routes, onTap, current) =>
-                  const KasySidebarPro(),
-            ),
+        ),
+        // large (1024 px+): full expanded sidebar
+        large: bart.BartScaffold(
+          routesBuilder: subRoutes,
+          bottomBar: kasyPaddedSurfaceBottomBar(),
+          initialRoute: resolvedInitialRoute,
+          showBottomBarOnStart: showBottomBarOnStart,
+          scaffoldOptions: scaffoldOptions,
+          sideBarOptions: bart.CustomSideBarOptions(
+            sideBarBuilder: (routes, onTap, current) => const KasySidebarPro(),
           ),
         ),
       ),
@@ -176,26 +109,3 @@ class _BottomMenuState extends State<BottomMenu>
     return segments.length < 2;
   }
 }
-
-/// Shared counter that inner home routes increment while mounted. The host
-/// [BottomMenu] observes it and toggles Bart's bottom-bar accordingly.
-class BottomBarVisibilityScope extends InheritedWidget {
-  final ValueNotifier<int> innerRouteDepth;
-
-  const BottomBarVisibilityScope({
-    super.key,
-    required this.innerRouteDepth,
-    required super.child,
-  });
-
-  static ValueNotifier<int>? maybeOf(BuildContext context) {
-    final scope = context
-        .getInheritedWidgetOfExactType<BottomBarVisibilityScope>();
-    return scope?.innerRouteDepth;
-  }
-
-  @override
-  bool updateShouldNotify(covariant BottomBarVisibilityScope oldWidget) {
-    return innerRouteDepth != oldWidget.innerRouteDepth;
-  }
-}

package/templates/firebase/lib/core/bottom_menu/bottom_router.dart

@@ -1,22 +1,20 @@
 import 'package:bart/bart.dart';
 import 'package:flutter/material.dart';
 import 'package:kasy_kit/components/kasy_app_bar.dart';
-import 'package:kasy_kit/core/bottom_menu/bart_inner_paths.dart';
-import 'package:kasy_kit/core/bottom_menu/bottom_menu.dart';
 import 'package:kasy_kit/core/bottom_menu/notification_bottom_item.dart';
 import 'package:kasy_kit/core/navigation/kasy_navigation_config.dart';
 import 'package:kasy_kit/core/navigation/kasy_route_transition.dart';
 import 'package:kasy_kit/core/rating/widgets/rate_banner.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
-import 'package:kasy_kit/features/home/design_system_page.dart';
-import 'package:kasy_kit/features/home/home_components_page.dart';
-import 'package:kasy_kit/features/home/home_components_preview_page.dart';
-import 'package:kasy_kit/features/home/home_features_page.dart';
 import 'package:kasy_kit/features/home/home_page.dart';
 import 'package:kasy_kit/features/notifications/ui/notifications_page.dart';
 import 'package:kasy_kit/features/settings/settings_page.dart';
 import 'package:kasy_kit/i18n/translations.g.dart';
 
+/// Bart tab routes (bottom bar). Detail screens reachable from a tab — Features,
+/// Components, Design System, component previews — are NOT inner routes here:
+/// they're pushed on the ROOT navigator (see home_page.dart / home_components_page.dart)
+/// so they open full-screen without the bottom bar and return to the tab intact.
 List<BartMenuRoute> subRoutes() {
   return [
     BartMenuRoute.bottomBar(
@@ -51,101 +49,9 @@ List<BartMenuRoute> subRoutes() {
       transitionDuration: bottomBarTransitionDuration,
       transitionsBuilder: bottomBarTransition,
     ),
-    BartMenuRoute.innerRoute(
-      path: bartInnerPath('home', 'features'),
-      showBottomBar: false,
-      pageBuilder: (_, _, _) =>
-          const _HomeInnerRoute(child: HomeFeaturesPage()),
-      transitionDuration: bottomBarTransitionDuration,
-      transitionsBuilder: bottomBarTransition,
-    ),
-    BartMenuRoute.innerRoute(
-      path: bartInnerPath('home', 'components'),
-      showBottomBar: false,
-      pageBuilder: (_, _, _) =>
-          const _HomeInnerRoute(child: HomeComponentsPage()),
-      transitionDuration: bottomBarTransitionDuration,
-      transitionsBuilder: bottomBarTransition,
-    ),
-    BartMenuRoute.innerRoute(
-      path: bartInnerPath('home', 'design-system'),
-      showBottomBar: false,
-      pageBuilder: (_, _, _) =>
-          const _HomeInnerRoute(child: DesignSystemPage()),
-      transitionDuration: bottomBarTransitionDuration,
-      transitionsBuilder: bottomBarTransition,
-    ),
-    BartMenuRoute.innerRoute(
-      path: bartInnerPath('home', 'components-preview'),
-      showBottomBar: false,
-      pageBuilder: (_, _, settings) {
-        final extra = settings?.arguments;
-        if (extra is! HomeComponentPreviewRouteExtra) {
-          return const PageFake();
-        }
-        return _HomeInnerRoute(
-          child: HomeComponentsPreviewPage(
-            title: extra.title,
-            variants: extra.variants,
-          ),
-        );
-      },
-      transitionDuration: bottomBarTransitionDuration,
-      transitionsBuilder: bottomBarTransition,
-    ),
-    BartMenuRoute.innerRoute(
-      path: bartInnerPath('home', 'search'),
-      showBottomBar: false,
-      pageBuilder: (_, _, _) => const _HomeInnerRoute(child: PageFake()),
-      transitionDuration: bottomBarTransitionDuration,
-      transitionsBuilder: bottomBarTransition,
-    ),
-    BartMenuRoute.innerRoute(
-      path: bartInnerPath('home', 'search/subscribe'),
-      showBottomBar: false,
-      pageBuilder: (_, _, _) => const _HomeInnerRoute(child: PageFake()),
-      transitionDuration: bottomBarTransitionDuration,
-      transitionsBuilder: bottomBarTransition,
-    ),
   ];
 }
 
-/// Wrapper for inner home routes. While mounted, it bumps a shared counter
-/// exposed by [BottomBarVisibilityScope] so [BottomMenu] knows to hide the
-/// bottom bar — covering cases Bart's tab-only `onRouteChanged` misses (e.g.
-/// pushing inside the same tab) and surviving scaffold rebuilds.
-class _HomeInnerRoute extends StatefulWidget {
-  final Widget child;
-
-  const _HomeInnerRoute({required this.child});
-
-  @override
-  State<_HomeInnerRoute> createState() => _HomeInnerRouteState();
-}
-
-class _HomeInnerRouteState extends State<_HomeInnerRoute> {
-  ValueNotifier<int>? _depth;
-
-  @override
-  void didChangeDependencies() {
-    super.didChangeDependencies();
-    final next = BottomBarVisibilityScope.maybeOf(context);
-    if (identical(_depth, next)) return;
-    _depth?.value -= 1;
-    _depth = next;
-    _depth?.value += 1;
-  }
-
-  @override
-  void dispose() {
-    _depth?.value -= 1;
-    super.dispose();
-  }
-
-  @override
-  Widget build(BuildContext context) => widget.child;
-}
-
 /// Placeholder page for the wishlist tab.
 /// Replace this with your own implementation.
 class WishlistPage extends StatelessWidget {
@@ -159,8 +65,8 @@ class WishlistPage extends StatelessWidget {
         crossAxisAlignment: CrossAxisAlignment.stretch,
         children: [
           KasyAppBar(
-          title: context.t.navigation.wishlist,
-          style: KasyAppBarStyle.rootTab,
+            title: context.t.navigation.wishlist,
+            style: KasyAppBarStyle.rootTab,
           ),
           Expanded(
             child: Padding(
@@ -224,31 +130,6 @@ class WishlistPage extends StatelessWidget {
   }
 }
 
-/// This is a fake page to show how to use Bart
-/// You can replace it with your own pages
-class PageFake extends StatelessWidget {
-  final Color? color;
-
-  const PageFake({this.color, super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return SafeArea(
-      // ignore: use_colored_box
-      child: Container(
-        color: color ?? context.colors.background,
-        child: Column(
-          children: [
-            const RateBanner(forceInDebug: true),
-            const SizedBox(height: 100),
-            Opacity(opacity: 0.5, child: Text(context.t.bottom_router.fake_page_text)),
-          ],
-        ),
-      ),
-    );
-  }
-}
-
 Widget bottomBarTransition(
   BuildContext context,
   Animation<double> animation,

package/templates/firebase/lib/core/states/user_state_notifier.dart

@@ -267,19 +267,17 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
       }
       if (user == null) {
         // User document not found after login. Possible causes:
-        // - Firebase: onUserRegistration Cloud Function not deployed or failed
-        // - Supabase: handle_new_user trigger not run yet (race) or failed
-        // - User was deleted but session was still cached
-        // Logout to clear invalid session, then create new anonymous user if applicable.
+        // - Cloud Functions not deployed yet (run `kasy deploy` to fix)
+        // - onUserRegistration Cloud Function failed
+        // - Supabase handle_new_user trigger not run yet (race) or failed
+        // Fall back to keeping the user authenticated with their auth ID so
+        // the app works locally before `kasy deploy` is run.
         _logger.e(
           '⚠️  User profile not found in database after sign-in.\n'
-          '    Logging out and creating new anonymous user.',
+          '    If this is a new project, run: kasy deploy\n'
+          '    to deploy the backend and create the user document.',
         );
-        await _authenticationRepository.logout();
-        state = state.copyWith(user: const User.anonymous());
-        if (mode == AuthenticationMode.anonymous) {
-          await _loadAnonymousState();
-        }
+        state = state.copyWith(user: User.anonymous(id: credentials.id));
         return;
       }
       // If the Firestore document is anonymous (no email) but Firebase Auth

package/templates/firebase/lib/features/home/home_components_page.dart

@@ -1,11 +1,10 @@
 import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
 import 'package:kasy_kit/components/kasy_app_bar.dart';
-import 'package:kasy_kit/core/bottom_menu/bart_inner_paths.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 import 'package:kasy_kit/core/widgets/kasy_hover.dart';
 import 'package:kasy_kit/core/widgets/kasy_scroll_behavior.dart';
-import 'package:kasy_kit/features/home/home_components_preview_page.dart';
 import 'package:kasy_kit/features/home/home_components_preview_registry.dart';
 
 /// UI-kit catalog, reachable from the home dashboard.
@@ -66,22 +65,17 @@ class HomeComponentsPage extends StatelessWidget {
                           onTap: () {
                             KasyHaptics.selection(context);
                             if (row.name == 'Design System') {
-                              Navigator.of(context).pushNamed(
-                                bartInnerPath('home', 'design-system'),
-                              );
+                              context.push('/design-system');
                               return;
                             }
-                            final ComponentPreviewDefinition? definition =
-                                getComponentPreviewDefinition(row.name);
-                            if (definition == null) {
+                            // Skip rows without a preview yet (registry returns
+                            // null); otherwise open /components/:name, which the
+                            // router resolves back to this component's preview.
+                            if (getComponentPreviewDefinition(row.name) == null) {
                               return;
                             }
-                            Navigator.of(context).pushNamed(
-                              bartInnerPath('home', 'components-preview'),
-                              arguments: HomeComponentPreviewRouteExtra(
-                                title: definition.title,
-                                variants: definition.variants,
-                              ),
+                            context.push(
+                              '/components/${Uri.encodeComponent(row.name)}',
                             );
                           },
                           child: Padding(

package/templates/firebase/lib/features/home/home_page.dart

@@ -1,7 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:kasy_kit/components/kasy_app_bar.dart';
-import 'package:kasy_kit/core/bottom_menu/bart_inner_paths.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
 import 'package:kasy_kit/core/states/components/maybe_ask_rating.dart';
 import 'package:kasy_kit/core/states/components/maybe_show_update_bottom_sheet.dart';
@@ -13,7 +13,7 @@ import 'package:kasy_kit/features/notifications/shared/att_permission.dart';
 import 'package:kasy_kit/features/subscription/shared/maybeshow_premium.dart';
 import 'package:kasy_kit/i18n/translations.g.dart';
 
-/// Home hub with dashboard cards; features live under [HomeFeaturesPage].
+/// Home hub with dashboard cards linking to the Features and Components screens.
 class HomePage extends ConsumerWidget {
   const HomePage({super.key});
 
@@ -59,9 +59,10 @@ class HomePage extends ConsumerWidget {
                             gradient: _featuresGradient(context, isDark),
                             onOpen: () {
                               KasyHaptics.medium(context);
-                              Navigator.of(context).pushNamed(
-                                bartInnerPath('home', 'features'),
-                              );
+                              // Top-level go_router route: opens full-screen on the
+                              // root navigator (above the BottomMenu, no bottom bar)
+                              // and pops back to home with the menu intact.
+                              context.push('/features');
                             },
                           );
                           final componentsCard = _DashboardGradientCard(
@@ -74,9 +75,7 @@ class HomePage extends ConsumerWidget {
                             gradient: _componentsGradient(context, isDark),
                             onOpen: () {
                               KasyHaptics.medium(context);
-                              Navigator.of(context).pushNamed(
-                                bartInnerPath('home', 'components'),
-                              );
+                              context.push('/components');
                             },
                           );
                           if (isWide) {

package/templates/firebase/lib/router.dart

@@ -15,6 +15,11 @@ import 'package:kasy_kit/features/authentication/ui/recover_password_page.dart';
 import 'package:kasy_kit/features/authentication/ui/signin_page.dart';
 import 'package:kasy_kit/features/authentication/ui/signup_page.dart';
 import 'package:kasy_kit/features/feedbacks/ui/feedback_page.dart';
+import 'package:kasy_kit/features/home/design_system_page.dart';
+import 'package:kasy_kit/features/home/home_components_page.dart';
+import 'package:kasy_kit/features/home/home_components_preview_page.dart';
+import 'package:kasy_kit/features/home/home_components_preview_registry.dart';
+import 'package:kasy_kit/features/home/home_features_page.dart';
 import 'package:kasy_kit/features/llm_chat/llm_chat_page.dart';
 import 'package:kasy_kit/features/local_reminder/ui/reminder_page.dart';
 import 'package:kasy_kit/features/onboarding/ui/onboarding_page.dart';
@@ -73,6 +78,61 @@ GoRouter generateRouter({
           ),
         ),
       ),
+      // Home showcase detail screens. These are TOP-LEVEL routes (siblings of
+      // '/', not children of the BottomMenu shell), so go_router renders them on
+      // the root navigator: full-screen, above the bottom bar, URL-addressable.
+      // Returning pops back to the tab with its menu intact.
+      GoRoute(
+        name: 'features',
+        path: '/features',
+        pageBuilder: (context, state) => kasyTransitionPage(
+          key: state.pageKey,
+          child: const HomeFeaturesPage(),
+        ),
+      ),
+      GoRoute(
+        name: 'design_system',
+        path: '/design-system',
+        pageBuilder: (context, state) => kasyTransitionPage(
+          key: state.pageKey,
+          child: const DesignSystemPage(),
+        ),
+      ),
+      GoRoute(
+        name: 'components',
+        path: '/components',
+        pageBuilder: (context, state) => kasyTransitionPage(
+          key: state.pageKey,
+          child: const HomeComponentsPage(),
+        ),
+        routes: [
+          // /components/:name — a single component's preview, looked up from the
+          // registry so the URL alone restores the screen on web reload.
+          GoRoute(
+            name: 'component_preview',
+            path: ':name',
+            pageBuilder: (context, state) {
+              final ComponentPreviewDefinition? definition =
+                  getComponentPreviewDefinition(
+                state.pathParameters['name'] ?? '',
+              );
+              if (definition == null) {
+                return kasyTransitionPage(
+                  key: state.pageKey,
+                  child: const PageNotFound(),
+                );
+              }
+              return kasyTransitionPage(
+                key: state.pageKey,
+                child: HomeComponentsPreviewPage(
+                  title: definition.title,
+                  variants: definition.variants,
+                ),
+              );
+            },
+          ),
+        ],
+      ),
       GoRoute(
         name: 'onboarding',
         path: '/onboarding',

package/templates/firebase/test/core/bottom_menu/detail_route_menu_test.dart

@@ -0,0 +1,57 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:go_router/go_router.dart';
+
+/// Regression test for the Features/Components navigation.
+///
+/// These detail screens are TOP-LEVEL go_router routes (siblings of the home
+/// shell, not children of it), so pushing them renders full-screen on the root
+/// navigator: the bottom bar is gone while the detail is open, and it returns
+/// intact when the user pops back to the tab.
+void main() {
+  testWidgets('a top-level route opens full-screen over the bottom bar, '
+      'and the bar returns on pop', (tester) async {
+    final router = GoRouter(
+      routes: [
+        // Home shell — owns the bottom bar (like BottomMenu).
+        GoRoute(
+          path: '/',
+          builder: (context, state) => Scaffold(
+            bottomNavigationBar: const Text('MENU'),
+            body: Center(
+              child: ElevatedButton(
+                onPressed: () => context.push('/features'),
+                child: const Text('open'),
+              ),
+            ),
+          ),
+        ),
+        // Detail screen — sibling of '/', so it renders on the root navigator.
+        GoRoute(
+          path: '/features',
+          builder: (context, state) => const Scaffold(
+            body: Center(child: Text('DETAIL')),
+          ),
+        ),
+      ],
+    );
+
+    await tester.pumpWidget(MaterialApp.router(routerConfig: router));
+
+    // Home tab: bottom bar visible, no detail.
+    expect(find.text('MENU'), findsOneWidget);
+    expect(find.text('DETAIL'), findsNothing);
+
+    // Open Features.
+    await tester.tap(find.text('open'));
+    await tester.pumpAndSettle();
+    expect(find.text('DETAIL'), findsOneWidget);
+    expect(find.text('MENU'), findsNothing); // covered — no bottom bar here
+
+    // Back: the bottom bar is intact.
+    Navigator.of(tester.element(find.text('DETAIL'))).maybePop();
+    await tester.pumpAndSettle();
+    expect(find.text('DETAIL'), findsNothing);
+    expect(find.text('MENU'), findsOneWidget);
+  });
+}