kasy-cli 1.31.9 → 1.31.11

package/lib/commands/add.js

@@ -30,6 +30,33 @@ const { toPackageName, buildTokens } = require('../scaffold/backends/firebase/to
 
 const execAsync = promisify(exec);
 
+/**
+ * Ensure the target project's supabase/config.toml has a [functions.<name>] block
+ * with verify_jwt = false. `kasy new` already writes the full config, but a project
+ * created before 1.31.10 (or any project missing the block) needs it appended here —
+ * otherwise the deployed function keeps the platform JWT gate ON and the browser CORS
+ * preflight (OPTIONS, no auth header) is rejected => "Failed to fetch" on web. The
+ * deploy --no-verify-jwt flag is deprecated/ignored by recent CLIs, so config.toml is
+ * the authoritative setting. The function authenticates itself, so this stays secure.
+ */
+async function ensureSupabaseConfigNoVerifyJwt(projectDir, fnName) {
+  const configPath = path.join(projectDir, 'supabase', 'config.toml');
+  if (!(await fs.pathExists(configPath))) return;
+  const toml = await fs.readFile(configPath, 'utf8');
+  const safe = fnName.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
+  const block = toml.match(new RegExp(`\\[functions\\.${safe}\\]([\\s\\S]*?)(?=\\n\\[|$)`));
+  if (block && /verify_jwt\s*=\s*false/.test(block[1])) return; // already correct
+  let next;
+  if (block && /verify_jwt\s*=\s*true/.test(block[0])) {
+    next = toml.replace(block[0], block[0].replace(/verify_jwt\s*=\s*true/, 'verify_jwt = false'));
+  } else if (block) {
+    next = toml.replace(block[0], `${block[0].replace(/\s*$/, '')}\nverify_jwt = false`);
+  } else {
+    next = `${toml.replace(/\s*$/, '')}\n\n[functions.${fnName}]\nverify_jwt = false\n`;
+  }
+  await fs.writeFile(configPath, next, 'utf8');
+}
+
 /** URL do endpoint AI no app (espelha defineUpdates de ai_chat). */
 function resolveAiChatEndpoint(answers, kitSetup) {
   if (kitSetup?.backendProvider === 'api') {
@@ -513,6 +540,10 @@ async function postAddAiChat(projectDir, kitSetup, answers, t) {
     if (backend === 'firebase') {
       await execAsync('firebase deploy --only functions:aiChat', { cwd: projectDir, timeout: 180_000 });
     } else if (backend === 'supabase') {
+      // Authoritative JWT setting lives in config.toml; ensure it before deploying so
+      // ai-chat is reachable from the web (the --no-verify-jwt flag alone is ignored
+      // by recent Supabase CLIs).
+      await ensureSupabaseConfigNoVerifyJwt(projectDir, 'ai-chat');
       await execAsync(`supabase functions deploy ai-chat --no-verify-jwt${refFlag}`, { cwd: projectDir, timeout: 180_000 });
     }
     deploySpinner.stop(t('add.ai_chat.deployed'));

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';
@@ -575,20 +575,6 @@ async function promptSupabaseManual(tr, cancel) {
   return { supabaseUrl, supabaseAnonKey };
 }
 
-// ── Module presets ────────────────────────────────────────────────────────────
-
-function buildPresets(audience) {
-  const catalog = getVisibleFeatures({ audience });
-  const named = ['starter', 'saas', 'content', 'full'];
-  const result = { none: [], custom: null };
-  for (const name of named) {
-    result[name] = catalog.filter((f) => f.defaultInPresets.includes(name)).map((f) => f.id);
-  }
-  return result;
-}
-
-const MODULE_PRESETS = buildPresets(KASY_AUDIENCE);
-
 // ── Main wizard ───────────────────────────────────────────────────────────────
 
 /**
@@ -1436,15 +1422,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/backends/supabase/edge-functions/admin-list-users/index.ts

@@ -14,7 +14,9 @@
  *      users — the users/subscriptions RLS exposes only a user's own row, so a
  *      non-admin can never reach other people's data.
  *
- * Deployed WITH JWT verification (the default) — see deploy.js.
+ * Deployed WITHOUT the platform JWT gate (verify_jwt = false in config.toml) so the
+ * browser's CORS preflight passes; security is enforced by the two layers above (the
+ * handler verifies the caller's JWT and admin role itself). See config.toml / deploy.js.
  */
 
 import { createClient } from "https://esm.sh/@supabase/supabase-js@2.47.10";

package/lib/scaffold/backends/supabase/edge-functions/stripe-create-checkout-session/index.ts

@@ -6,7 +6,9 @@
  * verified JWT, never trusted from the request body, so a client cannot check
  * out on behalf of someone else.
  *
- * Deployed WITH JWT verification.
+ * Deployed WITHOUT the platform JWT gate (verify_jwt = false in config.toml) so the
+ * browser's CORS preflight passes; the handler still authenticates the user via the
+ * verified JWT (getUser), so it stays secure.
  *
  * Secrets required:
  *   - STRIPE_SECRET_KEY: sk_test_... / sk_live_...
@@ -32,7 +34,11 @@ function trialDaysFor(price: Stripe.Price, product: Stripe.Product): number | nu
   return meta ? Number(meta) : null;
 }
 
-async function getUid(req: Request, supabaseUrl: string, anonKey: string): Promise<string | null> {
+async function getAuthUser(
+  req: Request,
+  supabaseUrl: string,
+  anonKey: string,
+): Promise<{ id: string; email?: string } | null> {
   const authHeader = req.headers.get("Authorization");
   if (!authHeader?.startsWith("Bearer ")) return null;
   const token = authHeader.replace("Bearer ", "");
@@ -41,19 +47,30 @@ async function getUid(req: Request, supabaseUrl: string, anonKey: string): Promi
   });
   const { data: { user }, error } = await client.auth.getUser(token);
   if (error || !user) return null;
-  return user.id;
+  return { id: user.id, email: user.email ?? undefined };
 }
 
 // deno-lint-ignore no-explicit-any
-async function getOrCreateCustomer(stripe: Stripe, admin: any, uid: string): Promise<string> {
+async function getOrCreateCustomer(
+  stripe: Stripe,
+  admin: any,
+  uid: string,
+  email?: string,
+): Promise<string> {
   const { data } = await admin
     .from(CUSTOMERS_TABLE)
     .select("customer_id")
     .eq("user_id", uid)
     .maybeSingle();
   const existing = data?.customer_id as string | undefined;
-  if (existing) return existing;
-  const customer = await stripe.customers.create({ metadata: { supabaseUID: uid } });
+  if (existing) {
+    // Keep the Stripe customer email in sync so Checkout pre-fills it. The
+    // payment is bound to the app user by uid (customer + metadata.supabaseUID),
+    // never by the typed email, so this is purely UX / billing hygiene.
+    if (email) await stripe.customers.update(existing, { email });
+    return existing;
+  }
+  const customer = await stripe.customers.create({ email, metadata: { supabaseUID: uid } });
   await admin.from(CUSTOMERS_TABLE).upsert({ user_id: uid, customer_id: customer.id });
   return customer.id;
 }
@@ -74,10 +91,11 @@ Deno.serve(async (req: Request) => {
     return Response.json({ error: "Server configuration error" }, { status: 500, headers: corsHeaders });
   }
 
-  const uid = await getUid(req, supabaseUrl, anonKey);
-  if (!uid) {
+  const user = await getAuthUser(req, supabaseUrl, anonKey);
+  if (!user) {
     return Response.json({ error: "Sign in required" }, { status: 401, headers: corsHeaders });
   }
+  const uid = user.id;
 
   let body: { priceId?: string; successUrl?: string; cancelUrl?: string };
   try {
@@ -95,7 +113,7 @@ Deno.serve(async (req: Request) => {
   try {
     const stripe = new Stripe(secretKey);
     const admin = createClient(supabaseUrl, serviceRoleKey);
-    const customerId = await getOrCreateCustomer(stripe, admin, uid);
+    const customerId = await getOrCreateCustomer(stripe, admin, uid, user.email);
 
     const price = await stripe.prices.retrieve(priceId, { expand: ["product"] });
     const trialDays = trialDaysFor(price, price.product as Stripe.Product);

package/lib/scaffold/backends/supabase/edge-functions/stripe-create-portal-session/index.ts

@@ -5,7 +5,9 @@
  * authenticated user and returns its URL. The user is identified by the
  * verified JWT and the Stripe customer is looked up server-side.
  *
- * Deployed WITH JWT verification.
+ * Deployed WITHOUT the platform JWT gate (verify_jwt = false in config.toml) so the
+ * browser's CORS preflight passes; the handler still authenticates the user via the
+ * verified JWT (getUser), so it stays secure.
  *
  * Secrets required:
  *   - STRIPE_SECRET_KEY

package/lib/scaffold/backends/supabase/edge-functions/stripe-list-prices/index.ts

@@ -5,8 +5,9 @@
  * contract used by the Flutter client (mirrors the Firebase `listPrices`
  * callable). The Stripe secret key never leaves the server.
  *
- * Deployed WITH JWT verification (the platform checks the caller's token), so
- * only an authenticated app user can reach it.
+ * Deployed WITHOUT the platform JWT gate (verify_jwt = false in config.toml) so the
+ * browser's CORS preflight passes. This endpoint is public by design — it only
+ * returns the active prices (no user data) — so it does NOT authenticate the caller.
  *
  * Secrets required (set via `supabase secrets set`):
  *   - STRIPE_SECRET_KEY: sk_test_... / sk_live_...

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/lib/scaffold/shared/generator-utils.js

@@ -369,6 +369,9 @@ async function writeRouter(projectDir, modules, packageName, defaultPaywall = 'b
   if (withWidget) {
     lines.push(`import 'package:${pkg}/features/settings/ui/components/admin/admin_home_widgets.dart';`);
   }
+  // Admin console — always shipped (settings/ui/components/admin) and always routable;
+  // access is gated inside AdminPage (admin role || debug). The settings UI links to it.
+  lines.push(`import 'package:${pkg}/features/settings/ui/components/admin/admin_page.dart';`);
   if (withRevenuecat) {
     lines.push(`import 'package:${pkg}/features/settings/ui/components/admin/admin_paywalls.dart';`);
   }
@@ -534,6 +537,14 @@ async function writeRouter(projectDir, modules, packageName, defaultPaywall = 'b
   lines.push(`        ),`);
   lines.push(`      ),`);
 
+  // Admin console (always routable so the settings 'Admin console' tile works in
+  // release too; access is gated inside AdminPage by admin role || debug).
+  lines.push(`      GoRoute(`);
+  lines.push(`        name: 'admin',`);
+  lines.push(`        path: '/admin',`);
+  lines.push(`        builder: (context, state) => const AdminPage(),`);
+  lines.push(`      ),`);
+
   // Send push notification (admin tool — always routable; the entry point in
   // the settings admin sheet is itself debug-gated).
   lines.push(`      GoRoute(`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.31.9",
+  "version": "1.31.11",
   "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 && node test/backend-pubspec-local-reminders.test.js",
     "start": "node ./bin/kasy.js",
     "setup": "node ./bin/kasy.js setup",
     "doctor": "node ./bin/kasy.js doctor",

package/templates/firebase/functions/src/subscriptions/stripe_functions.ts

@@ -21,13 +21,27 @@ function stripeClient(): Stripe {
   return new Stripe(stripeSecretKey.value());
 }
 
-async function getOrCreateCustomer(stripe: Stripe, uid: string): Promise<string> {
+async function getOrCreateCustomer(
+  stripe: Stripe,
+  uid: string,
+  email?: string,
+): Promise<string> {
   const db = admin.firestore();
   const ref = db.collection(CUSTOMERS_COLLECTION).doc(uid);
   const snap = await ref.get();
   const existing = snap.data()?.customerId as string | undefined;
-  if (existing) return existing;
-  const customer = await stripe.customers.create({metadata: {firebaseUID: uid}});
+  if (existing) {
+    // Keep the Stripe customer email in sync so Checkout pre-fills it and the
+    // receipts carry the right address. The payment is bound to the app user by
+    // UID (customer + metadata.firebaseUID), never by the typed email, so this
+    // is purely UX / billing hygiene.
+    if (email) await stripe.customers.update(existing, {email});
+    return existing;
+  }
+  const customer = await stripe.customers.create({
+    email,
+    metadata: {firebaseUID: uid},
+  });
   await ref.set({customerId: customer.id, created_at: Timestamp.now()});
   return customer.id;
 }
@@ -86,9 +100,12 @@ export const createCheckoutSession = onCall(
     if (!priceId) throw new HttpsError("invalid-argument", "priceId is required");
     const successUrl = (request.data?.successUrl as string | undefined) ?? "";
     const cancelUrl = (request.data?.cancelUrl as string | undefined) ?? successUrl;
+    // Pre-fill Checkout with the signed-in user's email (UX only; the user is
+    // identified by uid, so paying with a different email still updates them).
+    const email = request.auth?.token?.email as string | undefined;
 
     const stripe = stripeClient();
-    const customerId = await getOrCreateCustomer(stripe, uid);
+    const customerId = await getOrCreateCustomer(stripe, uid, email);
 
     const price = await stripe.prices.retrieve(priceId, {expand: ["product"]});
     const trialDays = trialDaysFor(price, price.product as Stripe.Product);

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,60 @@ 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});
+
+  /// Fade zone below the status-bar strip (mobile only).
+  static const double _contentFade = 40.0;
+
+  @override
+  Widget build(BuildContext context) {
+    final double topInset = MediaQuery.paddingOf(context).top;
+    // On web topInset = 0; enforce a 6 px minimum so the topmost pixels are
+    // 100 % opaque even without a status bar.
+    final double solidHeight = topInset < 6 ? 6.0 : topInset;
+    final double totalHeight = solidHeight + _contentFade;
+    final double ss = solidHeight / totalHeight; // solidStop
+    final Color bg = context.colors.background;
+
+    // Whole wash is intentionally faint — even the very top peaks at ~0.32, then
+    // melts to nothing across the fade zone. "Quase transparente, bem suave."
+    // Read from bottom → top: invisible → ghost → a soft hint at the very top.
+    double p(double t) => ss + (1 - ss) * t;
+
+    return IgnorePointer(
+      child: SizedBox(
+        height: totalHeight,
+        child: DecoratedBox(
+          decoration: BoxDecoration(
+            gradient: LinearGradient(
+              begin: Alignment.topCenter,
+              end: Alignment.bottomCenter,
+              colors: <Color>[
+                bg.withValues(alpha: 0.32),
+                bg.withValues(alpha: 0.32),
+                bg.withValues(alpha: 0.16),
+                bg.withValues(alpha: 0.06),
+                bg.withValues(alpha: 0.01),
+                bg.withValues(alpha: 0.0),
+              ],
+              stops: <double>[0.0, ss, p(0.10), p(0.26), p(0.44), 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 +278,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 +296,7 @@ class KasyAppBar extends StatelessWidget {
     this.onThemeToggle,
     this.toolbarHeight,
     this.topInset,
+    this.hideOnScroll = false,
   });
 
   @override
@@ -312,11 +375,50 @@ 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 — mobile only (tablet/desktop
+    // use the sidebar/web header instead). Skipped for modal / page-sheet bars.
+    final bool isMobile =
+        MediaQuery.sizeOf(context).width < DeviceType.medium.breakpoint;
+    final bool standardBar =
+        useSafeArea && topInset == null && toolbarHeight == null;
+    if (!standardBar || !isMobile) 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 +480,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 +498,7 @@ class KasyOverlayScaffold extends StatelessWidget {
     this.backgroundColor,
     this.onRefresh,
     this.refreshIndicatorDisplacement = 48,
+    this.hideAppBarOnScroll = false,
   });
 
   @override
@@ -433,6 +540,7 @@ class KasyOverlayScaffold extends StatelessWidget {
               onBack: onBack,
               onThemeToggle: onThemeToggle,
               trailing: trailing,
+              hideOnScroll: hideAppBarOnScroll,
             ),
           ),
         ],