kasy-cli 1.22.0 → 1.24.0

package/bin/kasy.js

@@ -463,9 +463,15 @@ function buildProgram(language) {
           if (p[p.length - 1] === 'lib') p = p.slice(0, -1);
           prefix = p.join(path.sep) || null;
         }
-        const args = ['install', '-g', 'kasy-cli@latest'];
-        if (prefix) args.push('--prefix', prefix);
-        const result = spawnSync('npm', args, { stdio: 'inherit', shell: true });
+        // Build a single, pre-quoted command string. Passing a quoted string
+        // (instead of an args array) with shell:true keeps a prefix that contains
+        // spaces intact — e.g. C:\Users\John Silva\.kasy — which the array form
+        // splits into a broken path (npm reads "Silva\.kasy" as a second package).
+        // It also avoids Node's DEP0190 arg-concatenation warning.
+        const quote = (s) => `"${s}"`;
+        let cmd = 'npm install -g kasy-cli@latest';
+        if (prefix) cmd += ` --prefix ${quote(prefix)}`;
+        const result = spawnSync(cmd, { stdio: 'inherit', shell: true });
         if (result.status === 0) {
           const after = readVersion();
           let msg;
@@ -486,9 +492,25 @@ function buildProgram(language) {
       .description(t('cli.command.uninstall.description'))
       .action(() => {
         const { spawnSync } = require('node:child_process');
+        const path = require('node:path');
         printCompactHeader(t);
         console.log(kleur.cyan(t('cli.command.uninstall.running')) + '\n');
-        const result = spawnSync('npm', ['uninstall', '-g', 'kasy-cli'], { stdio: 'inherit', shell: true });
+        // Remove from the SAME prefix the CLI was installed into (~/.kasy), the
+        // way `kasy upgrade` derives it — otherwise npm targets its default global
+        // prefix and leaves the real copy in place. Quote it so a path with
+        // spaces (C:\Users\John Silva\.kasy) survives shell:true.
+        const segs = __dirname.split(path.sep);
+        const nm = segs.lastIndexOf('node_modules');
+        let prefix = null;
+        if (nm > 0) {
+          let p = segs.slice(0, nm);
+          if (p[p.length - 1] === 'lib') p = p.slice(0, -1);
+          prefix = p.join(path.sep) || null;
+        }
+        const quote = (s) => `"${s}"`;
+        let cmd = 'npm uninstall -g kasy-cli';
+        if (prefix) cmd += ` --prefix ${quote(prefix)}`;
+        const result = spawnSync(cmd, { stdio: 'inherit', shell: true });
         if (result.status === 0) {
           console.log('\n' + kleur.green('✓ ' + t('cli.command.uninstall.done')) + '\n');
         } else {

package/lib/utils/checks.js

@@ -5,6 +5,7 @@ const ui = require('./ui');
 const { createTranslator, detectDefaultLanguage } = require('./i18n');
 const { augmentedEnv, pubCacheBin } = require('./env-tools');
 const { promptOpenBrowser } = require('./browser');
+const { installFlutterWindows } = require('./flutter-install');
 
 const execAsync = promisify(exec);
 
@@ -66,6 +67,12 @@ const BASE_CHECKS = [
     minVersion: MIN_FLUTTER_VERSION,
     installGuide: () => getInstallGuide('flutter'),
     confirmInstall: true,
+    // Windows has no clean winget path for Flutter, so we run a custom installer
+    // (download SDK zip + Git) instead of a package-manager command. macOS/Linux
+    // keep using installGuide().cmd (brew). See flutter-install.js.
+    installFn: process.platform === 'win32' ? installFlutterWindows : null,
+    installFnDescKey: 'checks.install.flutterWinDesc',
+    installFnNoteKey: 'checks.install.flutterWinNote',
   },
   {
     name: 'Dart SDK',
@@ -268,16 +275,25 @@ async function recoverCheckInteractively(check, t) {
   // The step list already flagged this tool as missing; go straight to fixing it.
   const guide = typeof check.installGuide === 'function' ? check.installGuide() : null;
 
-  // 1) Offer auto-install for heavy tools that have a package-manager command.
-  if (guide && guide.cmd && check.confirmInstall) {
+  // 1) Offer auto-install for heavy tools. Most use a package-manager command
+  // (brew/winget); Flutter on Windows uses a custom installer (check.installFn)
+  // because winget ships no stable Flutter package.
+  if (check.confirmInstall && (check.installFn || (guide && guide.cmd))) {
+    const cmdLabel = check.installFn
+      ? (check.installFnDescKey ? t(check.installFnDescKey) : check.name)
+      : guide.cmd;
     const doInstall = await ui.confirm({
-      message: t('checks.install.confirm', { name: check.name, cmd: guide.cmd }),
+      message: t('checks.install.confirm', { name: check.name, cmd: cmdLabel }),
       initialValue: true,
     });
     if (doInstall) {
+      // Heads-up for the custom installer: it's a big download and may pop a UAC.
+      if (check.installFn && check.installFnNoteKey) ui.log.info(t(check.installFnNoteKey));
       const spinner = ui.timedSpinner();
       spinner.start(t('checks.install.running', { name: check.name }));
-      const installed = await execTool(guide.cmd, INSTALL_TIMEOUT);
+      const installed = check.installFn
+        ? await check.installFn({})
+        : await execTool(guide.cmd, INSTALL_TIMEOUT);
       spinner.stop(t('checks.install.running', { name: check.name }));
       if (installed.ok && (await revalidate(check, t))) return true;
       ui.log.warn(t('checks.install.failedManual', { name: check.name }));

package/lib/utils/env-tools.js

@@ -105,6 +105,13 @@ function extraToolDirs() {
     process.env.LOCALAPPDATA && path.win32.join(process.env.LOCALAPPDATA, 'Google', 'Cloud SDK', 'google-cloud-sdk', 'bin'),
     process.env.ProgramFiles && path.win32.join(process.env.ProgramFiles, 'Google', 'Cloud SDK', 'google-cloud-sdk', 'bin'),
     process.env['ProgramFiles(x86)'] && path.win32.join(process.env['ProgramFiles(x86)'], 'Google', 'Cloud SDK', 'google-cloud-sdk', 'bin'),
+    // Flutter SDK auto-installed by `kasy new` (archive unzipped into %LOCALAPPDATA%\flutter).
+    // Putting its bin here lets the same run's flutter pub get / build_runner /
+    // flutterfire find both `flutter` and `dart` without a new terminal.
+    process.env.LOCALAPPDATA && path.win32.join(process.env.LOCALAPPDATA, 'flutter', 'bin'),
+    // Git (a Flutter prerequisite) installed via winget Git.Git — default locations.
+    process.env.ProgramFiles && path.win32.join(process.env.ProgramFiles, 'Git', 'cmd'),
+    process.env.LOCALAPPDATA && path.win32.join(process.env.LOCALAPPDATA, 'Programs', 'Git', 'cmd'),
   ].filter(Boolean);
   return candidates.filter((dir) => fs.existsSync(dir));
 }

package/lib/utils/flutter-install.js

@@ -0,0 +1,114 @@
+/**
+ * Auto-install the Flutter SDK on Windows, the only OS where there is no clean
+ * package-manager path (winget ships no stable Flutter package — the official
+ * route is the SDK archive). We mirror what the Flutter docs tell a human to do,
+ * but do it for the user so `kasy new` can prepare a bare machine end to end:
+ *
+ *   1. Install Git via winget if missing (Flutter refuses to run without it).
+ *   2. Download the current stable Flutter SDK zip and unzip it into
+ *      %LOCALAPPDATA%\flutter (a per-user dir that never needs admin rights).
+ *   3. Persist %LOCALAPPDATA%\flutter\bin on the User PATH for future terminals.
+ *
+ * The freshly-installed dirs are added to `augmentedEnv()` (see env-tools), so
+ * the rest of THIS `kasy new` run — flutter pub get, build_runner, flutterfire —
+ * finds the SDK immediately, without the user opening a new terminal.
+ *
+ * macOS/Linux don't need this: there Flutter installs via `brew install --cask
+ * flutter` (handled by the generic install path in checks.js).
+ */
+const { exec } = require('node:child_process');
+const path = require('node:path');
+
+const isWindows = process.platform === 'win32';
+
+// Where the SDK archive is unzipped. Must stay in sync with env-tools
+// extraToolDirs() so the recheck and the build steps look in the same place.
+function flutterWinHome() {
+  const base =
+    process.env.LOCALAPPDATA ||
+    path.win32.join(process.env.USERPROFILE || '', 'AppData', 'Local');
+  return path.win32.join(base, 'flutter');
+}
+
+// The PowerShell that does the actual work. Kept as a script (not a one-liner)
+// because it has to download ~1 GB, unzip it, and edit the persistent PATH —
+// none of which fits a single shell command cleanly.
+const PS_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+# Silencing the progress bar makes Invoke-WebRequest dramatically faster and
+# keeps our spinner the only thing the user sees.
+$ProgressPreference = 'SilentlyContinue'
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+$dest = Join-Path $env:LOCALAPPDATA 'flutter'
+$bin = Join-Path $dest 'bin'
+
+# 1. Git — Flutter uses it internally and won't run without it.
+if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+  if (Get-Command winget -ErrorAction SilentlyContinue) {
+    winget install --id Git.Git -e --source winget --silent --accept-source-agreements --accept-package-agreements --disable-interactivity | Out-Null
+  }
+}
+
+# 2. Flutter SDK — download + unzip, unless it's already there.
+if (-not (Test-Path (Join-Path $bin 'flutter.bat'))) {
+  if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }
+  $json = Invoke-RestMethod 'https://storage.googleapis.com/flutter_infra_release/releases/releases_windows.json'
+  $hash = $json.current_release.stable
+  $rel = $json.releases | Where-Object { $_.hash -eq $hash } | Select-Object -First 1
+  if (-not $rel) { throw 'Could not find the current stable Flutter release.' }
+  $url = $json.base_url + '/' + $rel.archive
+  $zip = Join-Path $env:TEMP ('flutter_sdk_' + $rel.version + '.zip')
+  Invoke-WebRequest -Uri $url -OutFile $zip
+  # ZipFile.ExtractToDirectory is much faster than Expand-Archive for a SDK-sized
+  # archive. The zip contains a top-level 'flutter\\' folder, so extracting into
+  # %LOCALAPPDATA% yields exactly %LOCALAPPDATA%\flutter.
+  Add-Type -AssemblyName System.IO.Compression.FileSystem
+  [System.IO.Compression.ZipFile]::ExtractToDirectory($zip, $env:LOCALAPPDATA)
+  Remove-Item $zip -Force -ErrorAction SilentlyContinue
+}
+
+# 3. Persist flutter\\bin on the User PATH so every future terminal finds it.
+$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+if (-not $userPath) { $userPath = '' }
+if (($userPath -split ';') -notcontains $bin) {
+  $newPath = if ($userPath.Length -gt 0) { $userPath.TrimEnd(';') + ';' + $bin } else { $bin }
+  [Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
+}
+
+Write-Output ('FLUTTER_BIN=' + $bin)
+`;
+
+/**
+ * Run the installer. Resolves to the same shape as checks.execTool
+ * ({ ok, stdout, stderr, error }) so the caller can treat it uniformly.
+ *
+ * @param {{ timeout?: number }} [opts]
+ * @returns {Promise<{ ok: boolean, stdout: string, stderr: string, error: string|null }>}
+ */
+function installFlutterWindows({ timeout = 1_800_000 } = {}) {
+  return new Promise((resolve) => {
+    if (!isWindows) {
+      resolve({ ok: false, stdout: '', stderr: '', error: 'not windows' });
+      return;
+    }
+    // -EncodedCommand (UTF-16LE base64) sidesteps every quoting headache of
+    // passing a multi-line script through a shell.
+    const encoded = Buffer.from(PS_SCRIPT, 'utf16le').toString('base64');
+    const cmd = `powershell -NoProfile -ExecutionPolicy Bypass -EncodedCommand ${encoded}`;
+    exec(
+      cmd,
+      { timeout, maxBuffer: 50 * 1024 * 1024, windowsHide: true },
+      (error, stdout, stderr) => {
+        resolve({
+          ok: !error,
+          stdout: stdout || '',
+          stderr: stderr || '',
+          error: error ? error.message : null,
+        });
+      }
+    );
+  });
+}
+
+module.exports = { installFlutterWindows, flutterWinHome };

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

@@ -134,6 +134,8 @@ module.exports = {
     'checks.thenRun': 'Then run',
     'checks.recheck': 'After installing {name}, press Enter to check again',
     'checks.install.confirm': 'Install {name} now? ({cmd})',
+    'checks.install.flutterWinDesc': 'downloads the official Flutter SDK + Git, ~1.8 GB',
+    'checks.install.flutterWinNote': 'This can take a few minutes (large download). If a Windows approval popup appears, click Yes.',
     'checks.install.running': 'Installing {name}…',
     'checks.install.failedManual': 'Could not install {name} automatically. Do it manually:',
     'checks.install.openDocs': 'Open the install page in the browser?',

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

@@ -134,6 +134,8 @@ module.exports = {
     'checks.thenRun': 'Luego ejecuta',
     'checks.recheck': 'Tras instalar {name}, presiona Enter para verificar de nuevo',
     'checks.install.confirm': '¿Instalar {name} ahora? ({cmd})',
+    'checks.install.flutterWinDesc': 'descarga el SDK oficial de Flutter + Git, ~1,8 GB',
+    'checks.install.flutterWinNote': 'Esto puede tardar unos minutos (descarga grande). Si aparece una ventana de permiso de Windows, haz clic en Sí.',
     'checks.install.running': 'Instalando {name}…',
     'checks.install.failedManual': 'No pude instalar {name} automáticamente. Hazlo manualmente:',
     'checks.install.openDocs': '¿Abrir la página de instalación en el navegador?',

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

@@ -134,6 +134,8 @@ module.exports = {
     'checks.thenRun': 'Depois rode',
     'checks.recheck': 'Após instalar {name}, pressione Enter para verificar novamente',
     'checks.install.confirm': 'Instalar {name} agora? ({cmd})',
+    'checks.install.flutterWinDesc': 'baixa o SDK oficial do Flutter + Git, ~1,8 GB',
+    'checks.install.flutterWinNote': 'Pode levar alguns minutos (download grande). Se aparecer um popup do Windows pedindo permissão, clique em Sim.',
     'checks.install.running': 'Instalando {name}…',
     'checks.install.failedManual': 'Não consegui instalar {name} automaticamente. Faça manualmente:',
     'checks.install.openDocs': 'Abrir a página de instalação no navegador?',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "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.dart

@@ -308,8 +308,15 @@ class _KasySidebarState extends State<KasySidebar> {
       setState(() => _userChoseCollapsed = !_userChoseCollapsed);
 
   /// Navigates to a real route via Bart and clears any static-item highlight.
+  /// Moving to another screen also collapses an open submenu (e.g. Income) and
+  /// drops its selected sub-item, so the sidebar always reflects the active
+  /// screen rather than a left-over expanded menu.
   void _navigateTo(int index) {
-    setState(() => _activeItemId = '');
+    setState(() {
+      _activeItemId = '';
+      _incomeExpanded = false;
+      _activeSubItem = '';
+    });
     widget.onTapItem!(index);
   }
 
@@ -738,6 +745,8 @@ class _KasySidebarState extends State<KasySidebar> {
         borderRadius: BorderRadius.circular(_kItemRadius),
         hoverColor: c.activeBg,
         pressColor: c.textActive,
+        focusable: true,
+        focusGapColor: c.bg,
         onTap: widget.onProfileTap ?? () {},
         child: Padding(
           padding: const EdgeInsets.symmetric(horizontal: 4, vertical: 8),
@@ -868,6 +877,8 @@ class _KasySidebarState extends State<KasySidebar> {
         borderRadius: BorderRadius.circular(_kItemRadius),
         hoverColor: c.activeBg,
         pressColor: c.textActive,
+        focusable: true,
+        focusGapColor: c.bg,
         onTap: onTap,
         child: Container(
           constraints: const BoxConstraints(minHeight: _kItemMinH),
@@ -937,6 +948,8 @@ class _KasySidebarState extends State<KasySidebar> {
           borderRadius: BorderRadius.circular(_kItemRadius),
           hoverColor: c.activeBg,
           pressColor: c.textActive,
+          focusable: true,
+          focusGapColor: c.bg,
           onTap: () => _activateItem(item.id),
           child: Container(
             constraints: const BoxConstraints(minHeight: _kItemMinH),

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

@@ -38,6 +38,59 @@ class BottomMenu extends StatelessWidget {
       extendBody: true,
     );
 
+    // Desktop/tablet sidebar, marked as the FIRST stop in the keyboard Tab
+    // order. Together with the header/content orders set in WebContentWrapper
+    // and the OrderedTraversalPolicy below, every screen tabs the same way:
+    // sidebar → header → content. (Touch/mobile has no Tab, so the `small`
+    // layout below is left untouched.)
+    bart.CustomSideBarOptions connectedSidebar() => bart.CustomSideBarOptions(
+          sideBarBuilder: (routes, onTap, current) => FocusTraversalOrder(
+            order: const NumericFocusOrder(1),
+            child: _FocusableSidebar(
+              currentItem: current,
+              child: Consumer(
+                builder: (context, ref, _) {
+                  final User user =
+                      ref.watch(userStateNotifierProvider).user;
+                  final (String name, String email) = switch (user) {
+                    final AuthenticatedUserData u => (
+                      (u.name?.isNotEmpty ?? false)
+                          ? u.name!
+                          : u.email.split('@').first,
+                      u.email,
+                    ),
+                    _ => (context.t.settings.my_account, ''),
+                  };
+                  return KasySidebar(
+                    routes: routes,
+                    onTapItem: onTap,
+                    currentItem: current,
+                    onLogout: () => confirmLogout(context, ref),
+                    profileName: name,
+                    profileEmail: email,
+                    profileAvatar: const KasyUserAvatar(),
+                  );
+                },
+              ),
+            ),
+          ),
+        );
+
+    // medium and large are identical here — the sidebar collapses itself by
+    // viewport width. The OrderedTraversalPolicy turns the numbered orders
+    // (sidebar=1, header=2, content=3) into the actual Tab sequence.
+    Widget connectedScaffold() => FocusTraversalGroup(
+          policy: OrderedTraversalPolicy(),
+          child: bart.BartScaffold(
+            routesBuilder: subRoutes,
+            bottomBar: kasyPaddedSurfaceBottomBar(),
+            initialRoute: resolvedInitialRoute,
+            showBottomBarOnStart: showBottomBarOnStart,
+            scaffoldOptions: scaffoldOptions,
+            sideBarOptions: connectedSidebar(),
+          ),
+        );
+
     return AnnotatedRegion<SystemUiOverlayStyle>(
       value: switch (Theme.brightnessOf(context)) {
         Brightness.dark => SystemUiOverlayStyle.light,
@@ -51,72 +104,8 @@ class BottomMenu extends StatelessWidget {
           showBottomBarOnStart: showBottomBarOnStart,
           scaffoldOptions: scaffoldOptions,
         ),
-        // medium (768–1024 px): KasySidebar 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) => Consumer(
-              builder: (context, ref, _) {
-                final User user = ref.watch(userStateNotifierProvider).user;
-                final (String name, String email) = switch (user) {
-                  final AuthenticatedUserData u => (
-                    (u.name?.isNotEmpty ?? false)
-                        ? u.name!
-                        : u.email.split('@').first,
-                    u.email,
-                  ),
-                  _ => (context.t.settings.my_account, ''),
-                };
-                return KasySidebar(
-                  routes: routes,
-                  onTapItem: onTap,
-                  currentItem: current,
-                  onLogout: () => confirmLogout(context, ref),
-                  profileName: name,
-                  profileEmail: email,
-                  profileAvatar: const KasyUserAvatar(),
-                );
-              },
-            ),
-          ),
-        ),
-        // 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) => Consumer(
-              builder: (context, ref, _) {
-                final User user = ref.watch(userStateNotifierProvider).user;
-                final (String name, String email) = switch (user) {
-                  final AuthenticatedUserData u => (
-                    (u.name?.isNotEmpty ?? false)
-                        ? u.name!
-                        : u.email.split('@').first,
-                    u.email,
-                  ),
-                  _ => (context.t.settings.my_account, ''),
-                };
-                return KasySidebar(
-                  routes: routes,
-                  onTapItem: onTap,
-                  currentItem: current,
-                  onLogout: () => confirmLogout(context, ref),
-                  profileName: name,
-                  profileEmail: email,
-                  profileAvatar: const KasyUserAvatar(),
-                );
-              },
-            ),
-          ),
-        ),
+        medium: connectedScaffold(),
+        large: connectedScaffold(),
       ),
     );
   }
@@ -162,3 +151,86 @@ class BottomMenu extends StatelessWidget {
     return segments.length < 2;
   }
 }
+
+/// Keeps the initial keyboard Tab focus anchored on the sidebar — on every
+/// screen, like Stripe/Linear.
+///
+/// Why this exists: Bart renders each page inside a nested [Navigator]
+/// (see bart's nested_navigator.dart), which has its OWN FocusScope and claims
+/// the primary focus the moment a route mounts. A plain `autofocus` on a sidebar
+/// item loses that race — the Navigator overwrites it in the same frame.
+///
+/// The fix is a tiny non-traversable [Focus] anchor inside the sidebar. A
+/// post-frame callback (runs AFTER the Navigator has claimed focus) moves focus
+/// to that anchor, pulling the primary focus out of the Navigator's scope and
+/// back onto the sidebar. Because the anchor sets `skipTraversal: true`, it is
+/// skipped by Tab, so the very first Tab lands on the first real sidebar item
+/// and then flows on to the header and content — nothing is trapped. (A
+/// [FocusScope] would have worked for the anchoring, but it adds a traversal
+/// boundary that wraps Tab back to the sidebar's start instead of moving on to
+/// the content, which is the opposite of what we want.)
+///
+/// It re-anchors whenever [currentItem] changes (a tab navigation) so a fresh
+/// screen also starts at the sidebar. The ring still only paints during keyboard
+/// navigation, so this is invisible to mouse/touch users.
+class _FocusableSidebar extends StatefulWidget {
+  final Widget child;
+  final ValueNotifier<int> currentItem;
+
+  const _FocusableSidebar({required this.child, required this.currentItem});
+
+  @override
+  State<_FocusableSidebar> createState() => _FocusableSidebarState();
+}
+
+class _FocusableSidebarState extends State<_FocusableSidebar> {
+  final FocusNode _anchor = FocusNode(
+    debugLabel: 'sidebarFocusAnchor',
+    skipTraversal: true,
+  );
+
+  @override
+  void initState() {
+    super.initState();
+    widget.currentItem.addListener(_anchorFocus);
+    _anchorFocus();
+  }
+
+  @override
+  void didUpdateWidget(_FocusableSidebar oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    if (oldWidget.currentItem != widget.currentItem) {
+      oldWidget.currentItem.removeListener(_anchorFocus);
+      widget.currentItem.addListener(_anchorFocus);
+    }
+  }
+
+  // Defer to after the frame so we win the race against the nested Navigator,
+  // which claims focus for its own scope while the route is mounting.
+  void _anchorFocus() {
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (mounted) _anchor.requestFocus();
+    });
+  }
+
+  @override
+  void dispose() {
+    widget.currentItem.removeListener(_anchorFocus);
+    _anchor.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return FocusTraversalGroup(
+      // The anchor is a zero-size sibling so it never affects the sidebar's
+      // layout; it exists only to hold the initial keyboard focus (see above).
+      child: Stack(
+        children: [
+          widget.child,
+          Focus(focusNode: _anchor, child: const SizedBox.shrink()),
+        ],
+      ),
+    );
+  }
+}

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

@@ -20,6 +20,9 @@ class WebContentWrapper extends StatelessWidget {
         MediaQuery.sizeOf(context).width >= DeviceType.large.breakpoint;
     if (!isDesktop) return child;
 
+    // Keyboard Tab order across the whole app: sidebar (1, set in BottomMenu) →
+    // header (2) → content (3). Each block is its own FocusTraversalGroup so its
+    // internal order stays natural (e.g. header: search → theme → … → create).
     return ColoredBox(
       color: context.colors.background,
       child: Column(
@@ -27,13 +30,23 @@ class WebContentWrapper extends StatelessWidget {
         children: [
           // The sidebar carries the user profile here, so the header drops its
           // avatar (showAvatar: false) to avoid duplicating the account chip.
-          KasyWebHeader(
-            onToggleTheme: () => ThemeProvider.of(context).toggle(),
-            onNotifications: () {},
-            onCreate: () {},
-            showAvatar: false,
+          FocusTraversalOrder(
+            order: const NumericFocusOrder(2),
+            child: FocusTraversalGroup(
+              child: KasyWebHeader(
+                onToggleTheme: () => ThemeProvider.of(context).toggle(),
+                onNotifications: () {},
+                onCreate: () {},
+                showAvatar: false,
+              ),
+            ),
+          ),
+          Expanded(
+            child: FocusTraversalOrder(
+              order: const NumericFocusOrder(3),
+              child: FocusTraversalGroup(child: child),
+            ),
           ),
-          Expanded(child: child),
         ],
       ),
     );

package/templates/firebase/lib/core/widgets/kasy_focus_ring.dart

@@ -27,12 +27,20 @@ class KasyFocusRing extends StatefulWidget {
   /// When false the ring never takes focus or paints (disabled controls).
   final bool enabled;
 
+  /// Colour of the hair-line gap between the control and the ring. Defaults to
+  /// [KasyColors.background] (correct on full-page backgrounds). Pass the actual
+  /// surface colour the control sits on (e.g. the sidebar/header `surface`) so
+  /// the gap blends in instead of painting a visible halo — this matters in dark
+  /// mode, where `background` is darker than `surface`.
+  final Color? gapColor;
+
   const KasyFocusRing({
     super.key,
     required this.child,
     required this.borderRadius,
     this.onActivate,
     this.enabled = true,
+    this.gapColor,
   });
 
   @override
@@ -57,7 +65,7 @@ class _KasyFocusRingState extends State<KasyFocusRing> {
     // A hair-line gap in the canvas colour lifts the ring just off the control
     // so it reads as a crisp outline (same focus language as KasyTextField) and
     // stays visible even on primary-coloured buttons (e.g. the chat send orb).
-    final Color gapColor = context.colors.background;
+    final Color gapColor = widget.gapColor ?? context.colors.background;
     final VoidCallback? onActivate = widget.onActivate;
 
     return FocusableActionDetector(

package/templates/firebase/lib/core/widgets/kasy_hover.dart

@@ -6,6 +6,7 @@ import 'package:flutter/services.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:kasy_kit/core/haptics/haptic_feedback_notifier.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
 
 /// Universal hover/press wrapper — works on any widget shape, any platform.
 ///
@@ -48,6 +49,8 @@ class KasyHover extends ConsumerStatefulWidget {
     this.pressEnabled = true,
     this.hoverColor,
     this.pressColor,
+    this.focusable = false,
+    this.focusGapColor,
   });
 
   final Widget child;
@@ -103,6 +106,19 @@ class KasyHover extends ConsumerStatefulWidget {
   /// background is already tinted so the feedback stays on-palette.
   final Color? pressColor;
 
+  /// When true, the control becomes a keyboard tab-stop by wrapping its visual
+  /// in the kit's [KasyFocusRing]: a focus ring appears during keyboard
+  /// navigation (never on pointer/touch) and Enter/Space triggers [onTap].
+  /// Pointer and touch behaviour are unchanged. Defaults to false so existing
+  /// call sites stay plain, non-focusable rows.
+  final bool focusable;
+
+  /// Gap colour forwarded to the focus ring (only used when [focusable]). Pass
+  /// the surface colour the row sits on so the keyboard ring's hair-line gap
+  /// blends in instead of showing a darker halo (notably in dark mode). When
+  /// null the ring falls back to [KasyColors.background].
+  final Color? focusGapColor;
+
   @override
   ConsumerState<KasyHover> createState() => _KasyHoverState();
 }
@@ -194,13 +210,24 @@ class _KasyHoverState extends ConsumerState<KasyHover> {
       child: widget.child,
     );
 
+    // Keyboard focus is owned by the kit's single focus indicator so Tab +
+    // Enter/Space behave identically to login, signup and the chat send button.
+    final Widget focusContent = widget.focusable
+        ? KasyFocusRing(
+            borderRadius: widget.borderRadius,
+            onActivate: widget.onTap,
+            gapColor: widget.focusGapColor,
+            child: content,
+          )
+        : content;
+
     Widget interactive = GestureDetector(
       behavior: HitTestBehavior.opaque,
       onTap: _handleTap,
       onTapDown: _onTapDown,
       onTapUp: _onTapUp,
       onTapCancel: _onTapCancel,
-      child: content,
+      child: focusContent,
     );
 
     // MouseRegion is active on all platforms:

package/templates/firebase/lib/features/authentication/ui/widgets/auth_card_scaffold.dart

@@ -5,6 +5,7 @@ import 'package:kasy_kit/components/kasy_card.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 import 'package:kasy_kit/core/widgets/kasy_brand_logo.dart';
 import 'package:kasy_kit/core/widgets/page_background.dart';
+import 'package:kasy_kit/core/widgets/responsive_layout.dart';
 import 'package:kasy_kit/features/authentication/ui/widgets/auth_page_back_button.dart';
 
 /// Premium shell shared by the auth screens (sign in / sign up / recover).
@@ -54,6 +55,49 @@ class AuthCardScaffold extends StatelessWidget {
         builder: (context, constraints) {
           final double minHeight = (constraints.maxHeight - padding.vertical)
               .clamp(0.0, double.infinity);
+          // On the mobile breakpoint (small, < 768) the card container is
+          // dropped: the form sits directly over the page background,
+          // edge‑to‑edge minus the page gutter. The elevated card stays on
+          // tablet/desktop (medium and up).
+          final bool isMobile =
+              DeviceType.fromWidth(constraints.maxWidth) == DeviceType.small;
+          final Widget content = Column(
+            crossAxisAlignment: CrossAxisAlignment.stretch,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              if (showLogo) ...[
+                Center(
+                  child: KasyBrandLogo(height: logoHeight)
+                      .animate()
+                      .fadeIn(
+                        duration: const Duration(milliseconds: 420),
+                        curve: Curves.easeOut,
+                      ),
+                ),
+                const SizedBox(height: KasySpacing.lg),
+              ],
+              Text(
+                title,
+                textAlign: TextAlign.center,
+                style: context.textTheme.headlineSmall?.copyWith(
+                  fontWeight: FontWeight.w700,
+                ),
+              ),
+              const SizedBox(height: KasySpacing.xs),
+              Text(
+                subtitle,
+                textAlign: TextAlign.center,
+                style: context.textTheme.bodyMedium?.copyWith(
+                  color: context.colors.onSurface.withValues(
+                    alpha: 0.62,
+                  ),
+                  fontWeight: FontWeight.w500,
+                ),
+              ),
+              const SizedBox(height: KasySpacing.xl),
+              ...children,
+            ],
+          );
           return SingleChildScrollView(
             physics: const ClampingScrollPhysics(),
             keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag,
@@ -64,49 +108,15 @@ class AuthCardScaffold extends StatelessWidget {
                 alignment: kIsWeb ? Alignment.center : Alignment.topCenter,
                 child: ConstrainedBox(
                   constraints: BoxConstraints(maxWidth: maxContentWidth),
-                  child: KasyCard(
-                    padding: const EdgeInsets.symmetric(
-                      horizontal: KasySpacing.lg,
-                      vertical: KasySpacing.xl,
-                    ),
-                    child: Column(
-                      crossAxisAlignment: CrossAxisAlignment.stretch,
-                      mainAxisSize: MainAxisSize.min,
-                      children: [
-                        if (showLogo) ...[
-                          Center(
-                            child: KasyBrandLogo(height: logoHeight)
-                                .animate()
-                                .fadeIn(
-                                  duration: const Duration(milliseconds: 420),
-                                  curve: Curves.easeOut,
-                                ),
-                          ),
-                          const SizedBox(height: KasySpacing.lg),
-                        ],
-                        Text(
-                          title,
-                          textAlign: TextAlign.center,
-                          style: context.textTheme.headlineSmall?.copyWith(
-                            fontWeight: FontWeight.w700,
+                  child: isMobile
+                      ? content
+                      : KasyCard(
+                          padding: const EdgeInsets.symmetric(
+                            horizontal: KasySpacing.lg,
+                            vertical: KasySpacing.xl,
                           ),
+                          child: content,
                         ),
-                        const SizedBox(height: KasySpacing.xs),
-                        Text(
-                          subtitle,
-                          textAlign: TextAlign.center,
-                          style: context.textTheme.bodyMedium?.copyWith(
-                            color: context.colors.onSurface.withValues(
-                              alpha: 0.62,
-                            ),
-                            fontWeight: FontWeight.w500,
-                          ),
-                        ),
-                        const SizedBox(height: KasySpacing.xl),
-                        ...children,
-                      ],
-                    ),
-                  ),
                 ),
               ),
             ),

package/templates/firebase/pubspec.yaml

@@ -16,7 +16,7 @@ publish_to: 'none' # Remove this line if you wish to publish to pub.dev
 # https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
 # In Windows, build-name is used as the major, minor, and patch parts
 # of the product and file versions while build-number is used as the build suffix.
-version: 1.0.0+33
+version: 1.0.0+34
 
 environment:
   sdk: ^3.11.0