kasy-cli 1.32.0 → 1.35.0

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

@@ -3,6 +3,8 @@ import 'dart:async';
 import 'package:flutter/material.dart';
 import 'package:kasy_kit/components/kasy_button.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_brand_logo.dart';
+import 'package:kasy_kit/i18n/translations.g.dart';
 import 'package:universal_io/io.dart';
 
 // ---------------------------------------------------------------------------
@@ -45,35 +47,38 @@ class KasyToast extends StatelessWidget {
   Widget build(BuildContext context) {
     final KasyColors c = context.colors;
     final bool isDark = context.isDark;
-    final _Palette pal = _palette(c, tone);
+    final _ToastStyle style = _resolveStyle(c, tone);
+
+    // A toast must never render an empty title line. If a caller passes a blank
+    // title (e.g. a short confirmation that only has a body), promote the
+    // message to the title so it always reads as a clean single-line toast.
+    final bool hasTitle = title.trim().isNotEmpty;
+    final String shownTitle = hasTitle ? title : (message ?? '');
+    final String? shownMessage = hasTitle ? message : null;
 
     return DecoratedBox(
       decoration: BoxDecoration(
         color: c.surface,
         borderRadius: KasyRadius.lgBorderRadius,
-        border: Border.all(
-          color: c.outline.withValues(alpha: isDark ? 0.22 : 0.28),
-        ),
+        border: Border.all(color: c.outline.withValues(alpha: 0.20)),
         boxShadow: [
           BoxShadow(
-            color: Colors.black.withValues(alpha: isDark ? 0.12 : 0.04),
-            blurRadius: 10,
-            offset: const Offset(0, 4),
+            color: Colors.black.withValues(alpha: isDark ? 0.22 : 0.06),
+            blurRadius: 18,
+            offset: const Offset(0, 6),
           ),
         ],
       ),
       child: Padding(
-        padding: const EdgeInsets.symmetric(
-          horizontal: KasySpacing.md,
-          vertical: 14,
-        ),
+        padding: const EdgeInsets.all(KasySpacing.smd),
         child: Row(
-          crossAxisAlignment: CrossAxisAlignment.start,
+          // Center everything for a single-line toast (no message) so nothing
+          // sits low; top-align when a longer message wraps.
+          crossAxisAlignment: shownMessage != null
+              ? CrossAxisAlignment.start
+              : CrossAxisAlignment.center,
           children: [
-            Padding(
-              padding: const EdgeInsets.only(top: 2),
-              child: icon ?? Icon(pal.icon, size: KasyIconSize.xl, color: pal.accent),
-            ),
+            _buildLeading(style),
             const SizedBox(width: KasySpacing.smd),
             Expanded(
               child: Column(
@@ -81,45 +86,68 @@ class KasyToast extends StatelessWidget {
                 mainAxisSize: MainAxisSize.min,
                 children: [
                   Text(
-                    title,
-                    style: context.textTheme.titleMedium?.copyWith(
-                      color: pal.accent,
-                      fontWeight: FontWeight.w700,
+                    shownTitle,
+                    style: context.textTheme.titleSmall?.copyWith(
+                      color: c.onSurface,
+                      fontWeight: FontWeight.w600,
                     ),
                   ),
-                  if (message != null) ...[
-                    const SizedBox(height: 4),
+                  if (shownMessage != null) ...[
+                    const SizedBox(height: 2),
                     Text(
-                      message!,
+                      shownMessage,
                       style: context.textTheme.bodyMedium?.copyWith(
-                        // Slightly darker than muted in light, slightly lighter in dark.
-                        color: Color.lerp(
-                          c.muted,
-                          isDark ? Colors.white : Colors.black,
-                          0.18,
-                        ),
+                        color: c.muted,
+                        height: 1.35,
                       ),
                     ),
                   ],
                 ],
               ),
             ),
-            const SizedBox(width: KasySpacing.smd),
-            Padding(
-              padding: const EdgeInsets.only(top: 1),
-              child: KasyButton(
-                label: 'Close',
-                size: KasyButtonSize.small,
-                backgroundColor: pal.buttonBg,
-                foregroundColor: pal.buttonFg,
-                onPressed: onClose,
-              ),
+            const SizedBox(width: KasySpacing.sm),
+            // A real "Close" text button (HeroUI-style), not a bare X. Always
+            // neutral (black in light / white in dark), since the bar itself is
+            // never coloured. Fully rounded (pill). Localised in every language.
+            KasyButton(
+              label: Translations.of(context).common.close,
+              variant: KasyButtonVariant.ghost,
+              size: KasyButtonSize.small,
+              backgroundColor:
+                  c.onSurface.withValues(alpha: isDark ? 0.14 : 0.06),
+              foregroundColor: c.onSurface,
+              fontWeight: FontWeight.w600,
+              borderRadius: BorderRadius.circular(KasyRadius.full),
+              onPressed: onClose,
             ),
           ],
         ),
       ),
     );
   }
+
+  /// The leading slot. A fully custom [icon] wins; otherwise the neutral tone
+  /// shows the app brand logo (so it always matches the splash / current brand)
+  /// and the semantic tones show a tone-coloured icon bubble.
+  Widget _buildLeading(_ToastStyle style) {
+    if (icon != null) return icon!;
+    if (style.useBrandLogo) {
+      return const SizedBox(
+        height: 32,
+        child: Center(child: KasyBrandLogo(height: 24)),
+      );
+    }
+    return Container(
+      width: 32,
+      height: 32,
+      alignment: Alignment.center,
+      decoration: BoxDecoration(
+        color: style.iconBubbleColor,
+        shape: BoxShape.circle,
+      ),
+      child: Icon(style.icon, size: KasyIconSize.sm, color: style.iconColor),
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -705,63 +733,70 @@ class _AnimatedToastState extends State<_AnimatedToast>
 // Palette resolution
 // ---------------------------------------------------------------------------
 
-class _Palette {
-  const _Palette({
-    required this.accent,
+/// Fully-resolved visual style for a toast tone.
+///
+/// Every toast shares the same plain surface bar, neutral title/message and a
+/// neutral "Close" button — the toast is never flooded with colour. The tone is
+/// carried *only by the leading icon bubble*:
+/// - **neutral** shows the app brand logo (no bubble).
+/// - **accent / danger** get a solid coloured bubble with a white icon inside
+///   (the "white inside the blue / red").
+/// - **success / warning** get a soft tinted bubble with a coloured icon.
+class _ToastStyle {
+  const _ToastStyle({
     required this.icon,
-    required this.buttonBg,
-    required this.buttonFg,
+    required this.iconColor,
+    required this.iconBubbleColor,
+    this.useBrandLogo = false,
   });
 
-  final Color accent;
   final IconData icon;
-  final Color buttonBg;
-  final Color buttonFg;
+  final Color iconColor;
+  final Color iconBubbleColor;
+
+  /// When true the leading slot shows the app brand logo (neutral tone).
+  final bool useBrandLogo;
 }
 
-_Palette _palette(KasyColors c, KasyToastTone tone) {
+_ToastStyle _resolveStyle(KasyColors c, KasyToastTone tone) {
   switch (tone) {
     case KasyToastTone.neutral:
-      return _Palette(
-        accent: c.onSurface,
+      return _ToastStyle(
         icon: KasyIcons.notification,
-        buttonBg: c.surfaceNeutralSoft,
-        buttonFg: c.onSurface,
+        iconColor: c.onSurface,
+        iconBubbleColor: Colors.transparent,
+        useBrandLogo: true,
       );
+    // Solid bubble, white icon inside.
     case KasyToastTone.accent:
-      return _Palette(
-        accent: c.primary,
+      return _ToastStyle(
         icon: KasyIcons.info,
-        buttonBg: c.primary,
-        // The Close button sits on a solid, vivid tone color — keep its label
-        // white for reliable contrast regardless of the brand "on" token.
-        buttonFg: Colors.white,
+        iconColor: c.onPrimary,
+        iconBubbleColor: c.primary,
+      );
+    case KasyToastTone.danger:
+      return _ToastStyle(
+        icon: KasyIcons.error,
+        iconColor: c.onError,
+        iconBubbleColor: c.error,
       );
+    // Soft tinted bubble, coloured icon.
     case KasyToastTone.success:
       final Color successDark = HSLColor.fromColor(c.success)
           .withLightness(
             (HSLColor.fromColor(c.success).lightness - 0.09).clamp(0.0, 1.0),
           )
           .toColor();
-      return _Palette(
-        accent: successDark,
+      return _ToastStyle(
         icon: KasyIcons.checkCircle,
-        buttonBg: successDark,
-        buttonFg: Colors.white,
+        iconColor: successDark,
+        iconBubbleColor: c.success.withValues(alpha: 0.14),
       );
     case KasyToastTone.warning:
-      return _Palette(
-        accent: c.warning,
+      return _ToastStyle(
         icon: KasyIcons.privacy,
-        buttonBg: c.warning,
-        buttonFg: Colors.white,
-      );
-    case KasyToastTone.danger:
-      return _Palette(
-        accent: c.error,
-        icon: KasyIcons.error,
-        buttonBg: c.error,
-        buttonFg: Colors.white,
+        iconColor: c.warning,
+        iconBubbleColor: c.warning.withValues(alpha: 0.16),
       );
   }
 }

package/templates/firebase/lib/core/app_update/app_update_repository.dart

@@ -0,0 +1,54 @@
+import 'package:flutter/foundation.dart' show kIsWeb;
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/app_update/app_update_status.dart';
+import 'package:kasy_kit/core/data/api/remote_config_api.dart';
+import 'package:logger/logger.dart';
+import 'package:package_info_plus/package_info_plus.dart';
+import 'package:pub_semver/pub_semver.dart';
+
+final appUpdateRepositoryProvider = Provider<AppUpdateRepository>(
+  (ref) => AppUpdateRepository(
+    remoteConfig: ref.read(remoteConfigApiProvider),
+  ),
+);
+
+/// Decides whether the user should be prompted to update, by comparing the
+/// installed version ([PackageInfo]) against the remote `app_latest_version` /
+/// `app_min_version` keys.
+///
+/// Backend-agnostic: the config is read from Firebase Remote Config, which is
+/// available on every backend (Firebase / Supabase / API all initialize
+/// Firebase Core for push). It is also native-only — the web build is never
+/// considered "behind a store".
+class AppUpdateRepository {
+  final RemoteConfigApi _remoteConfig;
+
+  AppUpdateRepository({required RemoteConfigApi remoteConfig})
+      : _remoteConfig = remoteConfig;
+
+  Future<AppUpdateStatus> check() async {
+    if (kIsWeb) return AppUpdateStatus.upToDate;
+    try {
+      final info = await PackageInfo.fromPlatform();
+      final Version installed = Version.parse(info.version);
+      final Version? latest = _tryParse(_remoteConfig.appUpdate.latestVersion.value);
+      final Version? min = _tryParse(_remoteConfig.appUpdate.minVersion.value);
+
+      if (min != null && installed < min) return AppUpdateStatus.forced;
+      if (latest != null && installed < latest) return AppUpdateStatus.optional;
+      return AppUpdateStatus.upToDate;
+    } catch (e) {
+      // Never block the app because of a missing/bad config or a parse error.
+      Logger().e('AppUpdateRepository.check failed: $e');
+      return AppUpdateStatus.upToDate;
+    }
+  }
+
+  Version? _tryParse(String raw) {
+    try {
+      return Version.parse(raw.trim());
+    } catch (_) {
+      return null;
+    }
+  }
+}

package/templates/firebase/lib/core/app_update/app_update_status.dart

@@ -0,0 +1,14 @@
+/// Result of comparing the installed app version against the remote config
+/// (`app_latest_version` / `app_min_version`).
+enum AppUpdateStatus {
+  /// Installed version is current — nothing to show.
+  upToDate,
+
+  /// A newer version exists; the update sheet is dismissible ("update now"
+  /// vs "not now").
+  optional,
+
+  /// Installed version is below the minimum allowed; the sheet blocks the app
+  /// until the user updates.
+  forced,
+}

package/templates/firebase/lib/core/app_update/update_available_sheet.dart

@@ -0,0 +1,70 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/components/components.dart';
+import 'package:kasy_kit/core/rating/api/rating_api.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/i18n/translations.g.dart';
+import 'package:logger/logger.dart';
+
+/// Shows the "update available" bottom sheet. Native-only: the caller already
+/// guards `kIsWeb`.
+///
+/// [forced] makes the sheet blocking — it cannot be dismissed (no drag, no
+/// barrier tap, back is blocked), so the user must update. When false the sheet
+/// is dismissible with a "not now" action.
+Future<void> showUpdateAvailableSheet(
+  BuildContext context, {
+  required bool forced,
+}) async {
+  await showKasyBottomSheet<void>(
+    context: context,
+    isDismissible: !forced,
+    enableDrag: !forced,
+    isScrollControlled: true,
+    builder: (_) => _UpdateAvailableSheet(forced: forced),
+  );
+}
+
+class _UpdateAvailableSheet extends ConsumerWidget {
+  final bool forced;
+
+  const _UpdateAvailableSheet({required this.forced});
+
+  Future<void> _openStore(WidgetRef ref) async {
+    try {
+      await ref.read(ratingApiProvider).openStoreListing();
+    } catch (e) {
+      // iOS needs a configured App Store ID; never crash the prompt.
+      Logger().e('openStoreListing failed: $e');
+    }
+  }
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final tr = context.t.update_available;
+
+    return PopScope(
+      canPop: !forced,
+      child: KasyBottomSheet(
+        icon: KasyIcons.download,
+        title: forced ? tr.forced_title : tr.title,
+        message: forced ? tr.forced_description : tr.description,
+        showDragHandle: !forced,
+        actions: [
+          KasyButton(
+            label: tr.update_button,
+            expand: true,
+            onPressed: () => _openStore(ref),
+          ),
+          if (!forced)
+            KasyButton(
+              label: tr.later_button,
+              variant: KasyButtonVariant.soft,
+              expand: true,
+              onPressed: () => Navigator.of(context).pop(),
+            ),
+        ],
+      ),
+    );
+  }
+}

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

@@ -6,9 +6,46 @@ import 'package:flutter/foundation.dart';
 /// phone-width frame). Persisting it lets the bottom bar restore the tab instead
 /// of snapping back to the first one on remount or hard reload (F5).
 ///
-/// It lives in its own dependency-free file so both [BottomMenu] and the logout
-/// flow can touch it without an import cycle. Cleared on logout so a fresh login
-/// always lands on the default tab. Null until the user opens a tab.
+/// It lives in its own dependency-free file so both [BottomMenu] and the auth
+/// flow can touch it without an import cycle. Null until the user opens a tab.
 final ValueNotifier<String?> activeTabRouteNotifier = ValueNotifier<String?>(
   null,
 );
+
+/// Forgets the remembered tab so the next [BottomMenu] mount starts on the
+/// default tab (Home). Call this on any session boundary — sign-in and logout —
+/// via the single helpers that own those transitions ([goHomeAfterLogin] and
+/// [UserStateNotifier.onLogout]); never poke [activeTabRouteNotifier] directly
+/// from feature code, so the reset stays in one obvious place.
+void forgetActiveTab() => activeTabRouteNotifier.value = null;
+
+/// One-shot flag: the next [BottomMenu] mount must land on Home, ignoring BOTH
+/// the remembered tab and the (possibly stale) web URL.
+///
+/// A fresh login navigates to `/`, but on web the previous session's URL may
+/// still read e.g. `/settings`, and [BottomMenu] falls back to that URL when no
+/// tab is remembered — so clearing the notifier alone isn't enough to guarantee
+/// Home (the URL fallback re-opens the old tab, then Bart rewrites the URL back
+/// to it). This flag forces Home for exactly one mount, regardless of timing
+/// between the login navigation and the auth page's own redirect. Set by
+/// [goHomeAfterLogin]; consumed once by [BottomMenu].
+bool _forceHomeOnNextMount = false;
+
+/// Forgets the tab AND forces the next [BottomMenu] mount to Home. Use on a
+/// fresh login (see [goHomeAfterLogin]) so the user never lands on whatever tab
+/// or URL the previous session left behind.
+void requestHomeOnNextMount() {
+  activeTabRouteNotifier.value = null;
+  _forceHomeOnNextMount = true;
+}
+
+/// Reads and clears the [requestHomeOnNextMount] flag. Returns true only for the
+/// first [BottomMenu] mount after a login; false otherwise (so web reload / the
+/// responsive remount keep restoring the tab normally).
+bool consumeForceHomeOnNextMount() {
+  if (!_forceHomeOnNextMount) {
+    return false;
+  }
+  _forceHomeOnNextMount = false;
+  return true;
+}

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

@@ -8,6 +8,7 @@ import 'package:kasy_kit/core/bottom_menu/active_tab_notifier.dart';
 import 'package:kasy_kit/core/bottom_menu/bottom_router.dart';
 import 'package:kasy_kit/core/bottom_menu/kasy_bottom_bar_factory.dart';
 import 'package:kasy_kit/core/bottom_menu/web_content_wrapper.dart';
+import 'package:kasy_kit/core/bottom_menu/web_url.dart';
 import 'package:kasy_kit/core/chrome/chrome_visibility.dart';
 import 'package:kasy_kit/core/data/models/user.dart';
 import 'package:kasy_kit/core/states/logout_action.dart';
@@ -25,6 +26,13 @@ void _rememberActiveTab(bart.BartMenuRoute route) {
   // A fresh tab always starts with the chrome shown (it may have been hidden by
   // scrolling on the previous tab).
   KasyChromeVisibility.instance.resetShown();
+  // Home is the app root: GoRouter serves it at '/', but Bart writes the bare
+  // tab path ('/home') like every other tab. Normalize so Home always reads as
+  // '/' — matching the post-login URL and the real GoRouter route (reload-safe)
+  // — instead of leaving two URLs for the same screen.
+  if (route.path == subRoutes().first.path) {
+    syncBrowserUrl('/');
+  }
 }
 
 /// Bottom navigation host powered by Bart (https://pub.dev/packages/bart).
@@ -149,6 +157,13 @@ class BottomMenu extends StatelessWidget {
     if (route != null) {
       return route;
     }
+    // A fresh login forced Home: ignore the remembered tab AND the (possibly
+    // stale) web URL for this one mount, so signing in never reopens whatever
+    // the previous session left behind. Reload (F5) and the responsive remount
+    // don't set this flag, so they keep restoring the tab below.
+    if (consumeForceHomeOnNextMount()) {
+      return null;
+    }
     // Restore the last tab across a remount. This is the reliable source: the
     // browser URL is contended by both GoRouter and Bart, but this notifier is
     // owned solely by the bottom bar and lives above the rebuilt subtree.
@@ -282,9 +297,16 @@ class _FocusableSidebarState extends State<_FocusableSidebar> {
     super.dispose();
   }
 
-  // "Skip to content" moves the primary focus into the routed content, so the
-  // next Tab steps to the first real control there instead of the sidebar.
-  void _skipToContent() => kasyContentFocusTarget?.requestFocus();
+  // "Skip to content" jumps focus straight to the FIRST real control in the
+  // routed content. The content target is a skipTraversal region (tabindex=-1
+  // style), so stepping once past it lands on a visible control immediately,
+  // instead of focusing the invisible region and needing a second Tab. Falls
+  // back to the region itself if the page has no focusable control.
+  void _skipToContent() {
+    final FocusNode? target = kasyContentFocusTarget;
+    if (target == null) return;
+    if (!target.nextFocus()) target.requestFocus();
+  }
 
   @override
   Widget build(BuildContext context) {
@@ -329,6 +351,8 @@ class _SkipToContentLink extends StatefulWidget {
 
 class _SkipToContentLinkState extends State<_SkipToContentLink> {
   bool _show = false;
+  final OverlayPortalController _overlay = OverlayPortalController();
+  final LayerLink _link = LayerLink();
 
   static const Map<ShortcutActivator, Intent> _shortcuts =
       <ShortcutActivator, Intent>{
@@ -337,9 +361,31 @@ class _SkipToContentLinkState extends State<_SkipToContentLink> {
     SingleActivator(LogicalKeyboardKey.space): ActivateIntent(),
   };
 
+  void _setShown(bool show) {
+    if (!mounted || show == _show) return;
+    setState(() => _show = show);
+    show ? _overlay.show() : _overlay.hide();
+  }
+
   @override
   Widget build(BuildContext context) {
+    // Colours/text are resolved here, in the sidebar's context, and passed into
+    // the overlay below — an overlay context doesn't reliably inherit the app
+    // theme (same reason the collapsed-rail tooltip in this file does it).
     final KasyColors c = context.colors;
+    final String label = context.t.navigation.skip_to_content;
+    final TextStyle? labelStyle = context.textTheme.bodyMedium?.copyWith(
+      color: c.onSurface,
+      fontWeight: FontWeight.w600,
+    );
+
+    // The focusable node lives here so the link stays the first Tab stop, but
+    // the visible card is painted in the root Overlay, anchored to this spot via
+    // [_link]. The collapsed sidebar is narrower than the card, so an inline
+    // card would be clipped at the rail's edge; the overlay floats above
+    // everything and is never clipped. The inline child is zero-size, so the
+    // detector also no longer overflows onto the panel toggle (dismiss-on-click
+    // is handled globally by FocusVisibility).
     return FocusableActionDetector(
       shortcuts: _shortcuts,
       actions: <Type, Action<Intent>>{
@@ -350,42 +396,44 @@ class _SkipToContentLinkState extends State<_SkipToContentLink> {
           },
         ),
       },
-      onShowFocusHighlight: (bool show) {
-        if (mounted && show != _show) setState(() => _show = show);
-      },
-      child: IgnorePointer(
-        ignoring: !_show,
-        child: AnimatedOpacity(
-          opacity: _show ? 1 : 0,
-          duration: const Duration(milliseconds: 120),
-          child: GestureDetector(
-            onTap: widget.onSkip,
-            child: Container(
-              padding: const EdgeInsets.symmetric(
-                horizontal: KasySpacing.md,
-                vertical: KasySpacing.sm,
-              ),
-              decoration: BoxDecoration(
-                color: c.surface,
-                borderRadius: BorderRadius.circular(KasyRadius.md),
-                border: Border.all(color: c.primary, width: 1.5),
-                boxShadow: <BoxShadow>[
-                  BoxShadow(
-                    color: c.onSurface.withValues(alpha: 0.18),
-                    blurRadius: 16,
-                    offset: const Offset(0, 4),
+      onShowFocusHighlight: _setShown,
+      child: CompositedTransformTarget(
+        link: _link,
+        child: OverlayPortal(
+          controller: _overlay,
+          overlayChildBuilder: (_) => CompositedTransformFollower(
+            link: _link,
+            showWhenUnlinked: false,
+            child: Align(
+              alignment: Alignment.topLeft,
+              child: Material(
+                color: Colors.transparent,
+                child: GestureDetector(
+                  onTap: widget.onSkip,
+                  child: Container(
+                    padding: const EdgeInsets.symmetric(
+                      horizontal: KasySpacing.md,
+                      vertical: KasySpacing.sm,
+                    ),
+                    decoration: BoxDecoration(
+                      color: c.surface,
+                      borderRadius: BorderRadius.circular(KasyRadius.md),
+                      border: Border.all(color: c.primary, width: 1.5),
+                      boxShadow: <BoxShadow>[
+                        BoxShadow(
+                          color: c.onSurface.withValues(alpha: 0.18),
+                          blurRadius: 16,
+                          offset: const Offset(0, 4),
+                        ),
+                      ],
+                    ),
+                    child: Text(label, style: labelStyle),
                   ),
-                ],
-              ),
-              child: Text(
-                context.t.navigation.skip_to_content,
-                style: context.textTheme.bodyMedium?.copyWith(
-                  color: c.onSurface,
-                  fontWeight: FontWeight.w600,
                 ),
               ),
             ),
           ),
+          child: const SizedBox.shrink(),
         ),
       ),
     );

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

@@ -28,9 +28,10 @@ class WebContentWrapper extends StatefulWidget {
 }
 
 class _WebContentWrapperState extends State<WebContentWrapper> {
-  // skipTraversal: the "skip to content" link focuses this node directly, but it
-  // stays out of the Tab order (like a tabindex="-1" skip target on the web) so
-  // the next Tab lands on the first real control inside the content.
+  // skipTraversal: a tabindex="-1" style region. The "skip to content" link
+  // steps past it to the first real control in the content (see
+  // BottomMenu._skipToContent), and normal Tab order skips it too — so it never
+  // becomes a focus stop of its own.
   final FocusNode _contentFocus = FocusNode(
     debugLabel: 'skipToContentTarget',
     skipTraversal: true,
@@ -83,9 +84,8 @@ class _WebContentWrapperState extends State<WebContentWrapper> {
             child: FocusTraversalOrder(
               order: const NumericFocusOrder(3),
               child: FocusTraversalGroup(
-                // Focus target for "skip to content": focusing it moves the
-                // primary focus into the content; the next Tab then steps to the
-                // first real control here.
+                // Focus target for "skip to content": the link steps past this
+                // region straight to the first real control inside it.
                 child: Focus(focusNode: _contentFocus, child: child),
               ),
             ),