kasy-cli 1.31.9 → 1.31.10

package/lib/commands/new.js

@@ -34,7 +34,7 @@ const {
   runChecks,
   hasRequiredFailures,
 } = require('../utils/checks');
-const { normalizeBackend, getVisibleFeatures, FEATURE_CATALOG } = require('../scaffold/catalog');
+const { normalizeBackend, getVisibleFeatures, computeQuickModules, FEATURE_CATALOG } = require('../scaffold/catalog');
 
 // Audience gate: set KASY_INTERNAL=1 to reveal beta/internal features.
 const KASY_AUDIENCE = process.env.KASY_INTERNAL === '1' ? 'internal' : 'public';
@@ -1436,15 +1436,12 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
     // --with flag was passed: use those modules directly, skip preset prompt.
     modules = preselectedModules;
   } else if (isQuick) {
-    // Quick mode: ship all features the backend supports. Facebook is excluded
-    // because it requires App ID + token that we can't auto-generate — the user
-    // adds it later with `kasy add facebook` when they have the credentials.
-    // Filter by availableIn so backend-specific features (e.g. feedback needs a
-    // DB) don't leak into a backend that can't support them.
-    const quickAvailable = new Set(
-      getVisibleFeatures({ audience: KASY_AUDIENCE, backend }).map((f) => f.id)
-    );
-    modules = (MODULE_PRESETS.full || []).filter((m) => m !== 'facebook' && quickAvailable.has(m));
+    // Quick mode: ship everything this backend supports, minus Facebook (needs an
+    // App ID + token we can't auto-generate — added later via `kasy add facebook`).
+    // computeQuickModules is shared with the anti-drift guard test, so the preset
+    // can't silently drop a feature again. Dropping local_reminders is what used to
+    // remove its dir and force the trimmed router that lost /admin + transitions.
+    modules = computeQuickModules({ backend, audience: KASY_AUDIENCE });
   } else {
     section('new.advanced.section.features');
     // Advanced mode: full multiselect — built from catalog, filtered by audience + backend.

package/lib/scaffold/CHANGELOG.json

@@ -1,4 +1,13 @@
 {
+  "1.31.10": {
+    "modules": {
+      "core": {
+        "pt": "Web preview de dispositivo não lança mais o erro \"Not initialized\" no primeiro frame: ele espera o DevicePreview terminar de inicializar antes de ajustar a orientação.",
+        "en": "Device preview on web no longer throws \"Not initialized\" on the first frame: it waits for DevicePreview to finish initializing before syncing orientation.",
+        "es": "La vista previa de dispositivo en web ya no lanza \"Not initialized\" en el primer frame: espera a que DevicePreview termine de inicializar antes de ajustar la orientación."
+      }
+    }
+  },
   "1.22.0": {
     "modules": {
       "components": {

package/lib/scaffold/backends/supabase/config.toml

@@ -28,7 +28,44 @@ enable_anonymous_sign_ins = true
 enable_confirmations = false
 double_confirm_changes = false
 
+# Edge Functions — every function skips the platform JWT gate (verify_jwt = false)
+# and authenticates ITSELF inside the handler. This is the authoritative setting:
+# `supabase functions deploy` reads it (the legacy --no-verify-jwt flag is deprecated
+# and silently ignored by recent CLIs). Two reasons every function needs it:
+#   1. Browser-invoked functions receive a CORS preflight (OPTIONS, no Authorization
+#      header). With the gate ON the platform rejects the preflight before our CORS
+#      handler runs, so the web app sees "Failed to fetch".
+#   2. Webhooks (Stripe, RevenueCat) are called server-to-server with a provider
+#      signature/key, never a Supabase user JWT.
+# Security is preserved: each handler checks the user token (getUser) or the webhook
+# signature/key before doing any work. Keep this list in sync with edge-functions/ —
+# cli/test/supabase-verify-jwt.test.js fails the publish if a function is missing.
+[functions.admin-list-users]
+verify_jwt = false
+
+[functions.ai-chat]
+verify_jwt = false
+
+[functions.delete-user-account]
+verify_jwt = false
+
+[functions.meta-track-event]
+verify_jwt = false
+
 [functions.revenuecat-webhook]
-# Webhook receives requests from RevenueCat, not from authenticated users.
-# JWT verification must be disabled — auth is done via REVENUECAT_WEBHOOK_KEY.
+verify_jwt = false
+
+[functions.send-push-notification]
+verify_jwt = false
+
+[functions.stripe-create-checkout-session]
+verify_jwt = false
+
+[functions.stripe-create-portal-session]
+verify_jwt = false
+
+[functions.stripe-list-prices]
+verify_jwt = false
+
+[functions.stripe-webhook]
 verify_jwt = false

package/lib/scaffold/backends/supabase/deploy.js

@@ -570,26 +570,24 @@ async function deployFunctions(projectDir, functionNames = []) {
   }
   if (toDeploy.length === 0) return { ok: true, skipped: true };
 
-  // Functions deployed WITHOUT the platform JWT gate (--no-verify-jwt). Two cases:
-  //   1. Webhooks (Stripe, RevenueCat, push) — called server-to-server, no user JWT.
-  //   2. Browser-invoked functions that authenticate THEMSELVES inside the handler:
-  //      delete-user-account (checks the token), admin-list-users (token + admin
-  //      role), stripe-list-prices (public prices), ai-chat (checks the token).
-  //      With the platform gate ON, the browser's CORS preflight (an OPTIONS with
-  //      no Authorization header) gets rejected before our CORS handler runs, so the
-  //      web app sees "Failed to fetch". Letting the function do its own auth makes
-  //      the preflight pass while staying secure (the handler still 401s anon calls).
-  const NO_VERIFY_JWT = new Set([
-    'ai-chat', 'revenuecat-webhook', 'send-push-notification', 'stripe-webhook',
-    'delete-user-account', 'admin-list-users', 'stripe-list-prices',
-  ]);
-
+  // EVERY function in this kit skips the platform JWT gate. The authoritative
+  // setting lives in supabase/config.toml ([functions.<name>] verify_jwt = false),
+  // which `supabase functions deploy` reads; we ALSO pass --no-verify-jwt here as a
+  // belt-and-suspenders for older CLIs (the flag is deprecated but harmless). Why
+  // all of them:
+  //   1. Browser-invoked functions get a CORS preflight (OPTIONS, no Authorization
+  //      header). With the gate ON the platform rejects the preflight before our
+  //      CORS handler runs, so the web app sees "Failed to fetch".
+  //   2. Webhooks (Stripe, RevenueCat) are called server-to-server with a provider
+  //      signature/key, never a Supabase user JWT.
+  // It stays secure because each handler authenticates itself (getUser on the token,
+  // or the webhook signature/key) before doing any work. config.toml is the source
+  // of truth — cli/test/supabase-verify-jwt.test.js asserts it covers every function.
   const steps = [];
   for (const name of toDeploy) {
     const fnPath = path.join(functionsDir, name);
     if (!(await fs.pathExists(fnPath))) continue;
-    const noVerifyJwt = NO_VERIFY_JWT.has(name) ? ' --no-verify-jwt' : '';
-    const result = await run(`supabase functions deploy ${name}${noVerifyJwt}`, projectDir);
+    const result = await run(`supabase functions deploy ${name} --no-verify-jwt`, projectDir);
     steps.push({ name: `deploy ${name}`, ok: result.ok, error: result.error });
   }
   return steps.length > 0 ? steps : { ok: true, skipped: true };

package/lib/scaffold/catalog.js

@@ -93,6 +93,29 @@ function getVisibleFeatures({ audience = 'public', backend = null } = {}) {
   });
 }
 
+/**
+ * Modules shipped by `kasy new` Quick mode (the recommended path): EVERYTHING the
+ * backend supports, minus Facebook (needs an App ID + token we can't auto-generate;
+ * added later via `kasy add facebook`).
+ *
+ * Single source of truth — used by both new.js (the real wizard) and the anti-drift
+ * guard test (cli/test/generated-matches-kit.test.js). They MUST agree: if Quick
+ * silently drops a feature, the kit's router/main can't be kept verbatim and the
+ * generator falls back to the trimmed builder that historically lost /admin and the
+ * page transitions. Computing it in one place means the test exercises the exact set
+ * the user gets, so that regression can never ship unnoticed again.
+ *
+ * @param {object} opts
+ * @param {string|null} opts.backend  - filter by backend (availableIn), or null for all
+ * @param {'public'|'internal'} opts.audience
+ * @returns {string[]} feature ids
+ */
+function computeQuickModules({ backend = null, audience = 'public' } = {}) {
+  return getVisibleFeatures({ audience, backend })
+    .map((f) => f.id)
+    .filter((id) => id !== 'facebook');
+}
+
 // Flat list kept for backward-compatibility with code that uses feature ids as strings.
 const AVAILABLE_FEATURES = FEATURE_CATALOG.map((f) => f.id);
 
@@ -255,4 +278,5 @@ module.exports = {
   parseFeatureList,
   getVisibleFeatures,
   getBaseFeatures,
+  computeQuickModules,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.31.9",
+  "version": "1.31.10",
   "description": "CLI for scaffolding production-ready Flutter SaaS apps with Firebase, Supabase, or API REST backends.",
   "bin": {
     "kasy": "./bin/kasy.js"
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "scripts": {
-    "prepack": "node scripts/check-feature-patches.js && node scripts/bundle-template.js && node test/generated-matches-kit.test.js",
+    "prepack": "node scripts/check-feature-patches.js && node scripts/bundle-template.js && node test/generated-matches-kit.test.js && node test/supabase-verify-jwt.test.js",
     "start": "node ./bin/kasy.js",
     "setup": "node ./bin/kasy.js setup",
     "doctor": "node ./bin/kasy.js doctor",

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

@@ -28,6 +28,7 @@ import 'dart:ui' show ImageFilter;
 import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart' show SystemUiOverlayStyle;
+import 'package:kasy_kit/core/chrome/chrome_visibility.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
 import 'package:kasy_kit/core/widgets/responsive_layout.dart';
@@ -182,6 +183,59 @@ class KasyFrostedChromeBackground extends StatelessWidget {
   }
 }
 
+/// A soft top wash — the page [KasyColors.background] fading to transparent —
+/// sized to the app bar's height. Place it behind the [KasyAppBar] in overlay
+/// layouts: when the bar hides on scroll, content melts into the background at
+/// the top instead of hard-cutting under the status bar. Mirrors the wash under
+/// the bottom navigation bar.
+///
+/// It is invisible while the bar is shown (it sits directly behind it) and a
+/// no-op on desktop (there is no app bar there), so it is always safe to add.
+class KasyTopScrollFade extends StatelessWidget {
+  const KasyTopScrollFade({super.key});
+
+  /// Always-solid strong band at the very top, ON TOP of the status-bar inset.
+  /// Fixed (not derived from the inset) so the top reads 100% solid even on web,
+  /// where there is no status-bar inset.
+  static const double _solidBand = 20;
+
+  /// Smooth fade below the solid band before the wash is fully transparent.
+  static const double _fadeTail = 18;
+
+  @override
+  Widget build(BuildContext context) {
+    final double topInset = MediaQuery.paddingOf(context).top;
+    final double solidHeight = topInset + _solidBand;
+    final double height = solidHeight + _fadeTail;
+    final Color bg = context.colors.background;
+    // Fully solid (100%) from the very top through the status-bar strip and the
+    // fixed band, then an eased fade to transparent — strong at the top, soft at
+    // the bottom. The middle stop curves the fade so it is gradual, not linear.
+    final double solidStop = (solidHeight / height).clamp(0.0, 1.0);
+    final double midStop = solidStop + (1 - solidStop) * 0.5;
+    return IgnorePointer(
+      child: SizedBox(
+        height: height,
+        child: DecoratedBox(
+          decoration: BoxDecoration(
+            gradient: LinearGradient(
+              begin: Alignment.topCenter,
+              end: Alignment.bottomCenter,
+              colors: <Color>[
+                bg,
+                bg,
+                bg.withValues(alpha: 0.4),
+                bg.withValues(alpha: 0),
+              ],
+              stops: <double>[0.0, solidStop, midStop, 1.0],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
 /// Layout preset for [KasyAppBar] (pick one; avoids composing many public pieces).
 enum KasyAppBarStyle {
   /// Back + centred title + light/dark theme toggle (dashboard sub-routes).
@@ -223,6 +277,13 @@ class KasyAppBar extends StatelessWidget {
   /// where there is no status-bar inset to provide natural breathing room.
   final double? topInset;
 
+  /// When true, the bar slides up and fades out as the user scrolls down and
+  /// returns on scroll up / at the top, in lock-step with the bottom menu (see
+  /// [KasyChromeVisibility]). Opt-in: only safe for pages that lay the bar over
+  /// full-height scroll content (the overlay pattern), so an empty gap never
+  /// appears where the bar was.
+  final bool hideOnScroll;
+
   const KasyAppBar({
     super.key,
     required this.title,
@@ -234,6 +295,7 @@ class KasyAppBar extends StatelessWidget {
     this.onThemeToggle,
     this.toolbarHeight,
     this.topInset,
+    this.hideOnScroll = false,
   });
 
   @override
@@ -312,11 +374,49 @@ class KasyAppBar extends StatelessWidget {
             children: [SizedBox(height: inset), bar],
           )
         : bar;
-    return KasyFrostedChromeBackground(
+    final Widget chrome = KasyFrostedChromeBackground(
       blurSigma: frostBlurSigma,
       padForStatusBar: useSafeArea,
       child: barContent,
     );
+
+    Widget animatedChrome = chrome;
+    if (hideOnScroll) {
+      // Slide up + fade as the chrome collapses; the same notifier drives the
+      // bottom bar, so the two move together.
+      final double barHeight = kasyAppBarBodyTopOverlap(context);
+      animatedChrome = ValueListenableBuilder<double>(
+        valueListenable: KasyChromeVisibility.instance.reveal,
+        builder: (BuildContext context, double reveal, Widget? child) {
+          final double hidden = 1 - reveal;
+          return Transform.translate(
+            offset: Offset(0, -barHeight * hidden),
+            child: Opacity(opacity: reveal, child: child),
+          );
+        },
+        child: chrome,
+      );
+    }
+
+    // A top wash sits BEHIND the bar (and stays put even when the bar hides) so
+    // content melts into the background at the top — the same pattern on every
+    // screen that has an app bar. Skipped for modal / page-sheet bars (custom
+    // height or inset), where nothing scrolls behind the bar.
+    final bool standardBar =
+        useSafeArea && topInset == null && toolbarHeight == null;
+    if (!standardBar) return animatedChrome;
+    return Stack(
+      clipBehavior: Clip.none,
+      children: <Widget>[
+        const Positioned(
+          top: 0,
+          left: 0,
+          right: 0,
+          child: KasyTopScrollFade(),
+        ),
+        animatedChrome,
+      ],
+    );
   }
 
   Widget _buildTrailing(BuildContext context, Color iconFg, Color orbFill) {
@@ -378,6 +478,10 @@ class KasyOverlayScaffold extends StatelessWidget {
   final Future<void> Function()? onRefresh;
   final double refreshIndicatorDisplacement;
 
+  /// Forwarded to [KasyAppBar.hideOnScroll]. Safe here because this scaffold is
+  /// the overlay pattern (bar floats over full-height scroll content).
+  final bool hideAppBarOnScroll;
+
   const KasyOverlayScaffold({
     super.key,
     required this.title,
@@ -392,6 +496,7 @@ class KasyOverlayScaffold extends StatelessWidget {
     this.backgroundColor,
     this.onRefresh,
     this.refreshIndicatorDisplacement = 48,
+    this.hideAppBarOnScroll = false,
   });
 
   @override
@@ -433,6 +538,7 @@ class KasyOverlayScaffold extends StatelessWidget {
               onBack: onBack,
               onThemeToggle: onThemeToggle,
               trailing: trailing,
+              hideOnScroll: hideAppBarOnScroll,
             ),
           ),
         ],

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/chrome/chrome_visibility.dart';
 import 'package:kasy_kit/core/data/models/user.dart';
 import 'package:kasy_kit/core/states/logout_action.dart';
 import 'package:kasy_kit/core/states/user_state_notifier.dart';
@@ -20,6 +21,9 @@ import 'package:kasy_kit/i18n/translations.g.dart';
 /// [bart.BartScaffold.onRouteChanged]. See [activeTabRouteNotifier].
 void _rememberActiveTab(bart.BartMenuRoute route) {
   activeTabRouteNotifier.value = route.path;
+  // A fresh tab always starts with the chrome shown (it may have been hidden by
+  // scrolling on the previous tab).
+  KasyChromeVisibility.instance.resetShown();
 }
 
 /// Bottom navigation host powered by Bart (https://pub.dev/packages/bart).
@@ -106,13 +110,28 @@ class BottomMenu extends StatelessWidget {
         Brightness.light => SystemUiOverlayStyle.dark,
       },
       child: ResponsiveLayout(
-        small: bart.BartScaffold(
-          routesBuilder: subRoutes,
-          bottomBar: kasyPaddedSurfaceBottomBar(),
-          initialRoute: resolvedInitialRoute,
-          showBottomBarOnStart: showBottomBarOnStart,
-          scaffoldOptions: scaffoldOptions,
-          onRouteChanged: _rememberActiveTab,
+        small: Consumer(
+          builder: (context, ref, _) {
+            // Watching the provider here keeps the persisted on/off setting in
+            // sync with the controller, and scopes scroll tracking to the
+            // mobile shell only (detail screens push on the root navigator, so
+            // their scrolls never reach this listener).
+            ref.watch(hideChromeOnScrollProvider);
+            return NotificationListener<ScrollUpdateNotification>(
+              onNotification: (notification) {
+                KasyChromeVisibility.instance.handleScrollUpdate(notification);
+                return false; // let the notification keep bubbling
+              },
+              child: bart.BartScaffold(
+                routesBuilder: subRoutes,
+                bottomBar: kasyPaddedSurfaceBottomBar(),
+                initialRoute: resolvedInitialRoute,
+                showBottomBarOnStart: showBottomBarOnStart,
+                scaffoldOptions: scaffoldOptions,
+                onRouteChanged: _rememberActiveTab,
+              ),
+            );
+          },
         ),
         medium: connectedScaffold(),
         large: connectedScaffold(),

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

@@ -3,6 +3,7 @@ import 'package:bart/bart/bart_model.dart';
 import 'package:bart/bart/router_delegate.dart';
 import 'package:bart/bart/widgets/bottom_bar/styles/bottom_bar_custom.dart';
 import 'package:flutter/material.dart';
+import 'package:kasy_kit/core/chrome/chrome_visibility.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 
@@ -159,42 +160,30 @@ final class KasyPaddedSurfaceBottomBarFactory extends BartBottomBarFactory {
       ),
     );
 
-    // Low bottom-up fade in the page background color: opaque at the very bottom
-    // (hides content scrolling under the bar), fully transparent again around the
-    // pill's mid-height so it stays a discreet wash low on the bar rather than a
-    // tall veil. Follows light/dark via the background token; same RGB at both
-    // ends so there is no grey halo.
-    final Widget fade = IgnorePointer(
-      child: DecoratedBox(
-        decoration: BoxDecoration(
-          gradient: LinearGradient(
-            begin: Alignment.bottomCenter,
-            end: Alignment.topCenter,
-            colors: [
-              colors.background,
-              colors.background,
-              colors.background.withValues(alpha: 0),
-            ],
-            stops: const [0.0, 0.33, 0.66],
-          ),
+    // Slide the pill down as the chrome collapses, in lock-step with the top
+    // app bar (same notifier). Travel covers the whole floating height so the
+    // pill fully clears the screen edge when hidden. No bottom wash: the pill
+    // just slides off (and never goes translucent).
+    final double travel = _kFloatingTopGap + _kBarHeight + bottomGap;
+    return ValueListenableBuilder<double>(
+      valueListenable: KasyChromeVisibility.instance.reveal,
+      builder: (BuildContext context, double reveal, Widget? child) {
+        final double hidden = 1 - reveal;
+        return Transform.translate(
+          offset: Offset(0, travel * hidden),
+          child: child,
+        );
+      },
+      child: Padding(
+        padding: EdgeInsets.only(
+          left: _kFloatingSideMargin,
+          right: _kFloatingSideMargin,
+          top: _kFloatingTopGap,
+          bottom: bottomGap,
         ),
+        child: pill,
       ),
     );
-
-    return Stack(
-      children: [
-        Positioned.fill(child: fade),
-        Padding(
-          padding: EdgeInsets.only(
-            left: _kFloatingSideMargin,
-            right: _kFloatingSideMargin,
-            top: _kFloatingTopGap,
-            bottom: bottomGap,
-          ),
-          child: pill,
-        ),
-      ],
-    );
   }
 }
 

package/templates/firebase/lib/core/chrome/chrome_visibility.dart

@@ -0,0 +1,119 @@
+import 'package:flutter/widgets.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/shared_preferences/shared_preferences.dart';
+
+/// Single source of truth for how much of the app's "chrome" — the top
+/// [KasyAppBar] and the bottom navigation bar — is revealed while the user
+/// scrolls. `1` = fully shown, `0` = fully hidden; both bars interpolate on
+/// this value so they slide away and come back together.
+///
+/// Behaviour (mobile only — tablet/desktop use the sidebar, which never hides):
+/// - Scrolling DOWN collapses the chrome glued to the gesture: a fast flick
+///   hides it fast, a slow drag hides it gradually.
+/// - Scrolling UP slowly keeps it hidden; only a fast fling up brings it back.
+/// - Reaching the top always brings it back.
+///
+/// Exposed as a global singleton (same pattern as `activeTabRouteNotifier` /
+/// `kasyContentFocusTarget`) because both the app bar component and the bottom
+/// bar factory need the same value without threading it through every page.
+class KasyChromeVisibility {
+  KasyChromeVisibility._();
+
+  static final KasyChromeVisibility instance = KasyChromeVisibility._();
+
+  /// `1` = chrome fully visible, `0` = fully hidden.
+  final ValueNotifier<double> reveal = ValueNotifier<double>(1);
+
+  bool _enabled = true;
+
+  /// Whether the "hide on scroll" feature is on. Off → the chrome stays pinned.
+  bool get enabled => _enabled;
+  set enabled(bool value) {
+    _enabled = value;
+    if (!value) reveal.value = 1; // pin the chrome back when turned off
+  }
+
+  /// Distance (logical px) over which the chrome fully collapses while scrolling
+  /// down. Small, so it feels glued to the gesture.
+  static const double _collapseDistance = 90;
+
+  /// An upward scroll delta at least this large in a single update counts as a
+  /// fast fling up and snaps the chrome back into view, even mid-page.
+  static const double _flingUpThreshold = 14;
+
+  /// Within this many px of the top, the chrome is always fully shown.
+  static const double _topThreshold = 6;
+
+  /// Bring the chrome fully back. Call on tab changes so a new screen never
+  /// starts with hidden chrome.
+  void resetShown() => reveal.value = 1;
+
+  /// Feed every vertical scroll update here (from a [NotificationListener] in
+  /// the shell). Updates [reveal] in place.
+  void handleScrollUpdate(ScrollUpdateNotification notification) {
+    if (!_enabled) return;
+    if (notification.metrics.axis != Axis.vertical) return;
+    final double delta = notification.scrollDelta ?? 0;
+    final double pixels = notification.metrics.pixels;
+
+    if (pixels <= _topThreshold) {
+      reveal.value = 1; // at the top → always shown
+      return;
+    }
+    if (delta > 0) {
+      // Scrolling down: collapse proportionally — fast scroll (big delta) hides
+      // fast, slow scroll hides gradually. Glued to the gesture.
+      reveal.value = (reveal.value - delta / _collapseDistance).clamp(0.0, 1.0);
+    } else if (delta < 0 && -delta >= _flingUpThreshold) {
+      // Scrolling up: a slow drag keeps it hidden; only a fast fling reveals.
+      reveal.value = 1;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Configuration — edit these to change the experience your app ships with.
+// ---------------------------------------------------------------------------
+
+/// Whether the Settings screen shows the "hide bars when scrolling" toggle to
+/// the END USER.
+///
+/// - `true`  → the toggle appears in Settings → Preferences and the user
+///   decides; its initial value is [kHideChromeOnScrollDefault].
+/// - `false` → the toggle is hidden and the behaviour is LOCKED to
+///   [kHideChromeOnScrollDefault] (the user cannot change it).
+const bool kShowHideChromeOnScrollSetting = true;
+
+/// The default behaviour: `true` = the app bar and bottom menu hide while
+/// scrolling down (and come back on scroll up / at the top); `false` = they
+/// stay fixed. Used as the toggle's initial value when shown, and as the locked
+/// value when [kShowHideChromeOnScrollSetting] is `false`.
+const bool kHideChromeOnScrollDefault = true;
+
+/// Persisted on/off for the hide-on-scroll behaviour. Wires the effective value
+/// into [KasyChromeVisibility] so the bars react immediately.
+final hideChromeOnScrollProvider =
+    NotifierProvider<HideChromeOnScrollNotifier, bool>(
+  HideChromeOnScrollNotifier.new,
+);
+
+class HideChromeOnScrollNotifier extends Notifier<bool> {
+  @override
+  bool build() {
+    // When the user toggle is hidden, the behaviour is locked to the default
+    // and any previously saved preference is ignored.
+    final bool enabled = kShowHideChromeOnScrollSetting
+        ? (ref.read(sharedPreferencesProvider).getHideChromeOnScroll() ??
+            kHideChromeOnScrollDefault)
+        : kHideChromeOnScrollDefault;
+    KasyChromeVisibility.instance.enabled = enabled;
+    return enabled;
+  }
+
+  Future<void> toggle() async {
+    final bool next = !state;
+    state = next;
+    KasyChromeVisibility.instance.enabled = next;
+    await ref.read(sharedPreferencesProvider).setHideChromeOnScroll(next);
+  }
+}

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

@@ -52,6 +52,18 @@ class SharedPreferencesBuilder implements OnStartService {
     return prefs.getBool('haptic_feedback_enabled') ?? true;
   }
 
+  /// Whether the top app bar and bottom menu hide while scrolling down and come
+  /// back on scroll up / at the top. Defaults to on.
+  Future<void> setHideChromeOnScroll(bool enabled) async {
+    await prefs.setBool('hide_chrome_on_scroll', enabled);
+  }
+
+  /// Null when the user has never set it — the caller applies the configured
+  /// default ([kHideChromeOnScrollDefault]).
+  bool? getHideChromeOnScroll() {
+    return prefs.getBool('hide_chrome_on_scroll');
+  }
+
   Future<void> setBiometricEnabled(bool enabled) async {
     await prefs.setBool('biometric_enabled', enabled);
   }