kasy-cli 1.37.0 → 1.38.0

package/lib/scaffold/CHANGELOG.json

@@ -1,4 +1,13 @@
 {
+  "1.38.0": {
+    "modules": {
+      "components": {
+        "pt": "Sidebar agora suporta submenus expansíveis (grupos com sub-itens, como o menu suspenso de Configurações na Home): clicar no grupo abre/fecha os filhos, o item ativo do submenu fica em negrito forte (sem pílula) e o submenu fecha sozinho ao navegar para outra tela.",
+        "en": "Sidebar now supports expandable submenus (groups with sub-items, like the Settings dropdown on Home): tapping the group opens/closes its children, the active sub-item shows in strong bold (no pill) and the submenu closes on its own when you navigate to another screen.",
+        "es": "La sidebar ahora admite submenús expansibles (grupos con subítems, como el menú desplegable de Ajustes en la Home): tocar el grupo abre/cierra sus hijos, el ítem activo del submenú se muestra en negrita fuerte (sin píldora) y el submenú se cierra solo al navegar a otra pantalla."
+      }
+    }
+  },
   "1.37.0": {
     "modules": {
       "components": {

package/lib/scaffold/backends/api/patch/lib/core/data/api/user_api.dart

@@ -44,6 +44,24 @@ class UserApi {
     }
   }
 
+  /// Watches the user's role so an admin promotion/demotion is picked up at
+  /// runtime (the shared user state refreshes when it changes). A REST backend
+  /// has no realtime channel, so this polls: it emits the current role at once
+  /// (mirroring the immediate snapshot of the Firebase/Supabase streams, which
+  /// the state notifier skips) and then re-checks periodically. The notifier
+  /// cancels the subscription on logout/dispose, which ends this generator.
+  Stream<String?> watchRole(String id) async* {
+    while (true) {
+      try {
+        final user = await get(id);
+        yield user?.role;
+      } catch (_) {
+        // Ignore transient network errors and keep polling.
+      }
+      await Future<void>.delayed(const Duration(seconds: 30));
+    }
+  }
+
   Future<void> update(UserEntity user) async {
     try {
       final data = user.toJson()..removeWhere((_, v) => v == null);

package/lib/scaffold/backends/patch-base-hashes.json

@@ -2,7 +2,7 @@
   "api/android/app/src/main/AndroidManifest.xml": "0579c57068ee50d43837ef9c7bee884b6232e92975301c8305ce389282f68291",
   "api/ios/Runner/AppDelegate.swift": "9f1027a03ad1fef2dab45464fbd7e98364b6a9cb6d2a6abe770ee9c45fa19122",
   "api/lib/core/data/api/storage_api.dart": "d77fecc6923ea9544b6ec20571dcab5c8f3d38be81ec618b0cf4f1b08be7bbae",
-  "api/lib/core/data/api/user_api.dart": "06f491ebf4548b87431e2d6983148f4082e120ec7d6a928108cba954d16d8c56",
+  "api/lib/core/data/api/user_api.dart": "0e7d984dceada025b7e998c217c39da9b781de430fd0f4d2267aaa6439391d5f",
   "api/lib/core/data/entities/json_converters.dart": "92a5efd595a03a862fa03e77ab3ca3d556523d0c9e0daca6e296e35d24b760a8",
   "api/lib/core/data/entities/user_entity.dart": "5c1e56e4be3ba2ed95cdcd276112a02b526f2a3fa7ee5bba08a3ec2b51153688",
   "api/lib/environments.dart": "c41f0843a4d627b717579eec5607b7ff5c16369bdd4b2a82e081058a20ffb7a5",
@@ -30,11 +30,11 @@
   "api/lib/features/subscriptions/api/entities/subscription_entity.dart": "20c1d75ed9d88acb96e94a592dcb4de0f63c792302ea07df53cebbdeb6d0cf7e",
   "api/lib/features/subscriptions/api/stripe_backend_api.dart": "e370bd05211462f2fc94c69af1749eb5330f997e9ec5e73e5c4e119999bf666f",
   "api/lib/features/subscriptions/api/subscription_api.dart": "c7484c9301d16245748025a3d420a89397e9e956b2211b7ed001c073ff2e4449",
-  "api/README.md": "1f30fc1ebf8fe02df6f3ee2f94c17f4bb4952abd5b125312d2c43eb6374eb354",
+  "api/README.md": "3c3e4b7731ac6eb86f8fdce202ed7b7d681246bcf76fdb87b389e4c9dfdeac08",
   "supabase/android/app/src/main/AndroidManifest.xml": "0579c57068ee50d43837ef9c7bee884b6232e92975301c8305ce389282f68291",
   "supabase/ios/Runner/AppDelegate.swift": "9f1027a03ad1fef2dab45464fbd7e98364b6a9cb6d2a6abe770ee9c45fa19122",
   "supabase/lib/core/data/api/storage_api.dart": "d77fecc6923ea9544b6ec20571dcab5c8f3d38be81ec618b0cf4f1b08be7bbae",
-  "supabase/lib/core/data/api/user_api.dart": "06f491ebf4548b87431e2d6983148f4082e120ec7d6a928108cba954d16d8c56",
+  "supabase/lib/core/data/api/user_api.dart": "0e7d984dceada025b7e998c217c39da9b781de430fd0f4d2267aaa6439391d5f",
   "supabase/lib/core/data/entities/json_converters.dart": "92a5efd595a03a862fa03e77ab3ca3d556523d0c9e0daca6e296e35d24b760a8",
   "supabase/lib/core/data/entities/user_entity.dart": "5c1e56e4be3ba2ed95cdcd276112a02b526f2a3fa7ee5bba08a3ec2b51153688",
   "supabase/lib/environments.dart": "c41f0843a4d627b717579eec5607b7ff5c16369bdd4b2a82e081058a20ffb7a5",
@@ -62,5 +62,5 @@
   "supabase/lib/features/subscriptions/api/stripe_backend_api.dart": "e370bd05211462f2fc94c69af1749eb5330f997e9ec5e73e5c4e119999bf666f",
   "supabase/lib/features/subscriptions/api/subscription_api.dart": "c7484c9301d16245748025a3d420a89397e9e956b2211b7ed001c073ff2e4449",
   "supabase/lib/google_auth_options.dart": "9d3ab9be5928f3100b9b217864d916edd1223d186e60ed130c35628812cace66",
-  "supabase/README.md": "1f30fc1ebf8fe02df6f3ee2f94c17f4bb4952abd5b125312d2c43eb6374eb354"
+  "supabase/README.md": "3c3e4b7731ac6eb86f8fdce202ed7b7d681246bcf76fdb87b389e4c9dfdeac08"
 }

package/lib/scaffold/backends/supabase/patch/lib/core/data/api/user_api.dart

@@ -40,6 +40,14 @@ class UserApi {
     }
   }
 
+  Stream<String?> watchRole(String id) {
+    return _client
+        .from('users')
+        .stream(primaryKey: ['id'])
+        .eq('id', id)
+        .map((rows) => rows.isEmpty ? null : rows.first['role'] as String?);
+  }
+
   Future<void> update(UserEntity user) async {
     try {
       final data = user.toJson()..removeWhere((_, v) => v == null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.37.0",
+  "version": "1.38.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/.firebase/hosting.YnVpbGQvd2Vi.cache

@@ -1,12 +1,10 @@
 stripe_success.html,1781195415353,677b2fb430839866f32a33a751aae85b4c4819123be820f3f5b2f689b8eed00e
 manifest.json,1779810782774,1b929ac7267ff738d05646106a0fac3591082b6f365051928a62518af30b3fd5
 local_notifications.js,1772398909034,0b44b177c4b8a705ad1b0e3d7532537aad7b230e9472f93c820742b7548797b8
-index.html,1781388256310,bb8142eb84e9e44049957c3edf86006e1ae5f194c397a8326ce505b68fdf58f4
-flutter_bootstrap.js,1781388256056,25f49550b20f234b84194d9e067725abdc33590343251086f6c7d147325dfb41
 flutter.js,1777393608000,b42e549a02f5c1428b0ad85dbdc663d400a6d2db10cb8aefcc0fddd592fd6ceb
 firebase-messaging-sw.js,1772484605561,dba3c939f7c240e62f63d06408d5f70e45f1168d00df98726e6a7a20cbd3b0df
 favicon.png,1779810782545,c967afd3c3d4dd165ef2e5cf3f203c3982dfff6a95881859ed163d9c38d75512
-.last_build_id,1781388166126,fb2a0536078d7023bcc9d41eb14cc00d74532f9465fac7aa9b88dae42e4a249c
+.last_build_id,1781393235997,3217b88fca927fa7fc5a6d9c24dee562336c5b14ad2c6e8b9b7b1bacff2e4a42
 splash/img/light-4x.png,1780546027751,abf0e55345e532a4645fe14b01c2948b07c78df50cc6da23648837dfb6271c74
 splash/img/light-3x.png,1780546027699,5f02c94032cb7053807ce89603b109f14ea2740eaa3145dc76c924cbe1d534a9
 splash/img/light-2x.png,1780546027647,3c073b9da154ac8be530f8beefa3579246f223acd819e856a2db000fdabcb67e
@@ -36,6 +34,15 @@ canvaskit/chromium/canvaskit.js.symbols,1777393830000,60722421e56edacbeb674cc3ef
 canvaskit/chromium/canvaskit.js,1777393830000,10ea3badcf26e29aba851699c03e09bc35fea65cdc440a035bac263d6d02d665
 assets/.env,1781370223435,777e85eb4de226724b28db8664404d0b73ae37f63fd66c955ac90c89cd491e7e
 assets/packages/mixpanel_flutter/assets/mixpanel.js,1779806094332,1915455df317dd1a9f42c6f3ea5bbe3ee357614f89d994f157a2e821f37956c3
+assets/packages/lucide_icons_flutter/assets/lucide.ttf,1779809590216,3813e3eb113e8be4c36c2082397dc3397d0ea7cd3a3b43eaecd61100b0256513
+assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w600.ttf,1779809590200,095ae41c43f72ec2997fa59fd91a0c83a36b345915e705f292f414cae6240dab
+assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w500.ttf,1779809590211,59d94414e1a3dd1732ff0b3ea50389c3e8b3915fe5a9b6163ba256a825e1e05b
+assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w400.ttf,1779809590202,9342632d6521314eb2ab7e902a8a6fe6c3d62a110f682bcc123e244e12c4a695
+assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w300.ttf,1779809590205,3bd1b359793f74027dada0e359d7d9dc712afd721db5ef30b095592e2e03e865
+assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w200.ttf,1779809590198,8026f9e7a751a47ace3ec60fdb7c6843a1d8051699fb28eb0a9fb1bd53904a66
+assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w100.ttf,1779809590208,1d81fb594eb42c3e8e43a36b89120a0a8a4c2dd858dec1a0c94de0e5b2208388
+assets/packages/cupertino_icons/assets/CupertinoIcons.ttf,1779806141382,010d647b6cab4e1a9b4398957353f43589903ce8dc760d05d894944b664e29bd
+assets/fonts/MaterialIcons-Regular.otf,1662569016000,3a631b0761788d7cf2a71e8732a5b31288d6e7aa996c671c70d53a251bbd3848
 assets/assets/images/splash_logo_light_android12.png,1779867497377,da2caee4f16230230dbb04d84913f0a9df2eae6bcb8f9d1ce83ed556cee6d094
 assets/assets/images/splash_logo_light.png,1779867497286,643a1f45d6ef9458c4c0eed9f4889cc2adbdf1db616913215be66673a05a0066
 assets/assets/images/splash_logo_dark_android12.png,1779867497464,b237d9f9035d419525a10b32889c30d44c706d62990b30bdc6bef911fe9352d6
@@ -53,23 +60,16 @@ assets/assets/icons/google_play_games.png,1772398653083,533c1d87d7be8690ab173ef4
 assets/assets/icons/google.png,1772398653083,f423e7e7be1e06008d45617d07f095f04da7fdcab9a56523f9e0633828e464e0
 assets/assets/icons/facebook.png,1772398653083,79ac67e449c1db63319d43329ca91f682b4e0bc6a0883b0dfb2a849e13ae6eb6
 assets/assets/icons/apple.png,1772398653083,2a737d8801ca81452b2978bb2e1ac72136acf1a4c338f2de2f77b65e9f6de1fa
-version.json,1781388383201,55f3aab1f3d71610bf791902e59e92cd77db8963f8290193f573c4172fa6fd32
-flutter_service_worker.js,1781388386040,baeeaf9f4b8e6f40d3b0549429ceb70ca01f120db6a7ef2f60d5809233dc2205
-assets/AssetManifest.bin,1781388383326,78bccb08a36307a400711a1d7e6868bd5f89a24e63439fb5b6747660323e4475
-assets/AssetManifest.bin.json,1781388383326,50a11b51c3fc4cbed1b5ec3a4f466c6a6b75c481d08d4782c8191f99bdbdba9c
-assets/FontManifest.json,1781388383326,4d84ab517c27984d36f9a3c8be6f2a72788c0c3985c1d5874297fef0a53407ca
-assets/shaders/ink_sparkle.frag,1781388383423,1c8e222328206d1e06754f76fb53947aad38d62180aafad5298a3c6f510b173d
-assets/shaders/stretch_effect.frag,1781388383423,1a7d4ac2be40cf0a459dfb390ef08bcd740f37913ffdee8de3c2ea836a18410e
-assets/packages/cupertino_icons/assets/CupertinoIcons.ttf,1781388385468,12bc6bf55aad4657f62747b6c1c9b5c120a594ed3540db21729b6db3c847340d
-assets/fonts/MaterialIcons-Regular.otf,1781388385471,89da9939a222284d9e14e9757b4dbdb75965434cb84b0f2969495153f3a018c9
-main.dart.js_3.part.js,1781388360492,6f52d11c8e140736cd046ce6b541ad8d8bf20e6ef709f39d8ef4eb3dddbece8b
-main.dart.js_1.part.js,1781388360481,42136799a40b5acb14b5acf0a8cef39bbef13b4dc99ce808a7bc8a1f8cdd8b09
-assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w300.ttf,1781388385457,aebf5e4f6b1e6de1e61a866f813aa5b08efb4cdd108cc2831d40aad71398c88f
-assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w400.ttf,1781388385463,edcd01ee13f6ec2285fd18863c0ce0efb0876b290fb427ad5c052f753b3210c8
-assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w600.ttf,1781388385468,008f1e974c9ff4e8d40d16221226e0d34d2298a7feb2bdea8c134a9333929c9c
-assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w100.ttf,1781388385446,c16d95412fe2600bda1f53c2b8dc4bd82496f60f7c5a6ecfa180b0f866128712
-assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w500.ttf,1781388385464,3f68f958d0fa13077968a6767339c38ede8705bcadd0382078db6ec4bac96fa0
-assets/packages/lucide_icons_flutter/assets/lucide.ttf,1781388385448,9b000e47cddf9ada4a6b85fc9577fef7ed2ee261c9279e9a44e4753da28f83d3
-assets/packages/lucide_icons_flutter/assets/build_font/LucideVariable-w200.ttf,1781388385451,1f798186cfc3e2fcd54b15aa7b8695bc7c29b781c5058029a8d80ecdfa615904
-assets/NOTICES,1781388383326,a18efc42c5ed99b56481537d0f229ddd3add671c548a893aaf8766f30c854158
-main.dart.js,1781388361400,b625f1b346dc2f1475ee99ebb1d698654e74183d737c91e1bbac020869096a84
+version.json,1781400658272,495754f8591b89616bdad18717ffd8aa9275a8605889167170e6bc98ced40489
+flutter_service_worker.js,1781400658740,baeeaf9f4b8e6f40d3b0549429ceb70ca01f120db6a7ef2f60d5809233dc2205
+assets/FontManifest.json,1781400658381,4d84ab517c27984d36f9a3c8be6f2a72788c0c3985c1d5874297fef0a53407ca
+index.html,1781400619641,bb8142eb84e9e44049957c3edf86006e1ae5f194c397a8326ce505b68fdf58f4
+assets/AssetManifest.bin,1781400658381,78bccb08a36307a400711a1d7e6868bd5f89a24e63439fb5b6747660323e4475
+assets/AssetManifest.bin.json,1781400658381,50a11b51c3fc4cbed1b5ec3a4f466c6a6b75c481d08d4782c8191f99bdbdba9c
+assets/shaders/stretch_effect.frag,1781400658449,1a7d4ac2be40cf0a459dfb390ef08bcd740f37913ffdee8de3c2ea836a18410e
+assets/shaders/ink_sparkle.frag,1781400658449,1c8e222328206d1e06754f76fb53947aad38d62180aafad5298a3c6f510b173d
+flutter_bootstrap.js,1781400619636,371abfca6d227535d1d7bf43ada40ba5256e04ae0aed40e29ccae33f964fa7f7
+main.dart.js_3.part.js,1781400646444,6f52d11c8e140736cd046ce6b541ad8d8bf20e6ef709f39d8ef4eb3dddbece8b
+main.dart.js_1.part.js,1781400646439,42136799a40b5acb14b5acf0a8cef39bbef13b4dc99ce808a7bc8a1f8cdd8b09
+assets/NOTICES,1781400658382,a18efc42c5ed99b56481537d0f229ddd3add671c548a893aaf8766f30c854158
+main.dart.js,1781400646862,c0154549b8162d55ff32593e679d1f3461e6f4ff744d9730cd87953b0244d8c9

package/templates/firebase/AGENTS.md

@@ -41,15 +41,19 @@ colours, typography, spacing and dozens of ready widgets (`KasyButton`,
 `showKasyConfirmDialog`, …). Reuse one before writing a new widget. Full token
 reference: **`DESIGN_SYSTEM.md`**.
 
-**Responsiveness is deliberate, not improvised.** There are exactly three
-breakpoints and the type sizes are pinned per breakpoint, so the UI never
-oscillates or guesses:
+**Responsiveness is deliberate, not improvised.** The responsive system
+(`DeviceType` in `lib/core/widgets/responsive_layout.dart`) has four tiers and the
+type sizes are pinned per breakpoint, so the UI never oscillates or guesses:
 
-| Breakpoint | Width      | Notes                                            |
-| ---------- | ---------- | ------------------------------------------------ |
-| Mobile     | `< 768`    | native iOS/Android + phone-width web             |
-| Tablet     | `768–1024` |                                                  |
-| Desktop    | `>= 1024`  | authored baseline                                |
+| DeviceType | Width        | Notes                                            |
+| ---------- | ------------ | ------------------------------------------------ |
+| `small`    | `< 768`      | native iOS/Android + phone-width web             |
+| `medium`   | `768–1023`   | tablet                                           |
+| `large`    | `1024–1279`  | desktop, authored baseline                       |
+| `xlarge`   | `>= 1280`    | wide desktop (web-scale design target, 1280)     |
+
+Typography collapses `large`+`xlarge` into one "desktop" tier (same sizes); the
+`1280` boundary matters for the web render scale (its design target), not type.
 
 - **Typography** (`KasyTypeScale`): each role has an **explicit size per
   breakpoint** — headings are largest on desktop and step down on smaller
@@ -63,6 +67,11 @@ oscillates or guesses:
   renders ~10% large, so **desktop only** scales the whole UI to `0.95`. Tablet
   and mobile web render at natural size, like native. This is NOT the typography
   scale — don't conflate the two.
+- **Screen width follows content type** (two tiers): read/form screens (Settings,
+  Notifications) are contained + centred at `kKasyContentMaxWidth` (600) — set
+  `KasyOverlayScaffold(maxContentWidth: kKasyContentMaxWidth)` or use `KasyScreen`;
+  feed/dashboard screens (Home) go full width + the 16 gutter. Mirror
+  Settings/Notifications, or Home. Full rule: **`DESIGN_SYSTEM.md`** → Internal-screen contract.
 
 To re-tune sizes, edit `KasyTypeScale` in `lib/core/theme/type_scale.dart` —
 nothing else. The live ramp (tabs per breakpoint) is under **Design System →
@@ -95,7 +104,8 @@ lib/
 
 1. Read `DESIGN_SYSTEM.md` (tokens, typography roles, components).
 2. Reuse a kit component before building one. Wrap new pages in `KasyScreen`
-   (or mirror an existing page's scaffold).
+   (or mirror an existing page's scaffold). Pick the width tier — contained
+   (mirror Settings/Notifications) vs full-width (mirror Home); see `DESIGN_SYSTEM.md`.
 3. Use semantic typography roles (`pageTitle`, `sectionTitle`, `rowTitle`, …)
    and tokens for **every** size, colour and spacing.
 4. Strings via `context.t.*` (add keys to the i18n JSON, never inline text).
@@ -139,7 +149,7 @@ Recommended flow when the user wants newer kit code:
 2. Run the relevant command:
    - `kasy update` — shows what's new for the features in use
    - `kasy update core` / `kasy update components` — refreshes core files / UI components
-   - `kasy update <feature>` — e.g. `revenuecat`, `ai_chat`, `auth` (re-applies that feature)
+   - `kasy update <feature>` — e.g. `revenuecat`, `ai_chat`, `widget` (re-applies that feature)
 3. The command overwrites the files and prints which ones changed.
 4. **Merge:** if the user had customized any overwritten file, reconcile their version
    (in the previous git commit) with the new kit version. As the in-project agent,

package/templates/firebase/DESIGN_SYSTEM.md

@@ -222,6 +222,19 @@ New internal screens follow the sidebar / Home ruler:
 - Haptics only on native (`if (!kIsWeb)`); "hide chrome on scroll" only on the
   phone breakpoint (`width < 768`).
 
+**Content width — two tiers (width follows content type):**
+- *Read / form screens* (Settings, Notifications, Reminder) → **contained + centred**
+  at `kKasyContentMaxWidth` (600, in `core/widgets/responsive_layout.dart`). With the
+  overlay pattern, set `KasyOverlayScaffold(maxContentWidth: kKasyContentMaxWidth)`
+  (centres the column on desktop, keeps the 16 gutter on mobile); with `KasyScreen`
+  it is the default. Long lines and lone controls read badly stretched, so cap them.
+  The Settings desktop master/detail centres the **nav + detail as one unit**.
+- *Browse / feed / dashboard screens* (Home) → **full width + the 16 gutter, on
+  purpose** — width helps a grid/feed. Do **not** contain these.
+- Every tier shares the same family (16 gutter, `KasyCard`, sidebar + web header) —
+  only the max width changes. To mirror: copy **Settings / Notifications** for a
+  contained screen, **Home** for a full-width one.
+
 ---
 
 ## Keeping it consistent — the guard-rail (optional)

package/templates/firebase/README.en.md

@@ -74,7 +74,7 @@ Force manually: `kasy run --rc=test` or `kasy run --rc=prod`. `--rc=auto` (defau
 To update, edit `.vscode/launch.json` or pass via command line:
 
 ```sh
-flutter run --dart-define=RC_ANDROID_API_KEY=your_key
+flutter run --dart-define=RC_ANDROID_PROD_KEY=your_key
 ```
 
 ---

package/templates/firebase/README.es.md

@@ -74,7 +74,7 @@ Forzar manualmente: `kasy run --rc=test` o `kasy run --rc=prod`. `--rc=auto` (po
 Para actualizar, edita `.vscode/launch.json` o pasa por línea de comandos:
 
 ```sh
-flutter run --dart-define=RC_ANDROID_API_KEY=tu_clave
+flutter run --dart-define=RC_ANDROID_PROD_KEY=tu_clave
 ```
 
 ---

package/templates/firebase/README.md

@@ -74,7 +74,7 @@ Forçar manualmente: `kasy run --rc=test` ou `kasy run --rc=prod`. `--rc=auto` (
 Para atualizar, edite o `.vscode/launch.json` ou passe via linha de comando:
 
 ```sh
-flutter run --dart-define=RC_ANDROID_API_KEY=sua_chave
+flutter run --dart-define=RC_ANDROID_PROD_KEY=sua_chave
 ```
 
 ---

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

@@ -27,6 +27,7 @@ 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/chrome/web_header_scope.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';
@@ -56,8 +57,11 @@ enum KasyAppBarScrollTreatment { overlay, intrinsicScroll }
 
 /// Vertical inset for scroll/viewport when using [KasyAppBarScrollTreatment.overlay].
 double kasyAppBarBodyTopOverlap(BuildContext context) {
-  // On desktop the app bar hides (the web header owns the top chrome).
-  if (MediaQuery.sizeOf(context).width >= DeviceType.large.breakpoint) {
+  // On desktop the app bar hides only inside the web-header scope (the shell), so
+  // no overlap there. Outside it (a full-screen pushed route) the bar is visible,
+  // so reserve its height like on phone/tablet.
+  if (MediaQuery.sizeOf(context).width >= DeviceType.large.breakpoint &&
+      KasyWebHeaderScope.of(context)) {
     return 0;
   }
   return MediaQuery.paddingOf(context).top +
@@ -74,23 +78,47 @@ List<Widget> kasyOverlayPaddedSlivers(
   BuildContext context, {
   required List<Widget> slivers,
   EdgeInsetsGeometry? contentPadding,
+  double? maxContentWidth,
 }) {
-  final EdgeInsetsGeometry pad =
-      contentPadding ??
-      EdgeInsets.fromLTRB(
-        KasySpacing.pageHorizontalGutter,
-        KasySpacing.belowChromeContentGap,
-        KasySpacing.pageHorizontalGutter,
-        MediaQuery.paddingOf(context).bottom + KasySpacing.pageVerticalGutter,
-      );
+  const double topPad = KasySpacing.belowChromeContentGap;
+  final double bottomPad =
+      MediaQuery.paddingOf(context).bottom + KasySpacing.pageVerticalGutter;
+  const double gutter = KasySpacing.pageHorizontalGutter;
+
+  final Widget body = SliverMainAxisGroup(slivers: slivers);
+
+  // An explicit [contentPadding] takes full control; otherwise use the page
+  // gutters, optionally centering content within [maxContentWidth] on wide
+  // viewports (so lists never stretch edge-to-edge on desktop). Centering is
+  // computed from the real content width (SliverLayoutBuilder) so it stays
+  // correct inside the desktop shell where the sidebar already took space.
+  final Widget paddedGroup;
+  if (contentPadding != null) {
+    paddedGroup = SliverPadding(padding: contentPadding, sliver: body);
+  } else if (maxContentWidth == null) {
+    paddedGroup = SliverPadding(
+      padding: EdgeInsets.fromLTRB(gutter, topPad, gutter, bottomPad),
+      sliver: body,
+    );
+  } else {
+    paddedGroup = SliverLayoutBuilder(
+      builder: (context, constraints) {
+        final double available = constraints.crossAxisExtent;
+        final double horizontal = available - 2 * gutter > maxContentWidth
+            ? (available - maxContentWidth) / 2
+            : gutter;
+        return SliverPadding(
+          padding: EdgeInsets.fromLTRB(horizontal, topPad, horizontal, bottomPad),
+          sliver: body,
+        );
+      },
+    );
+  }
   return <Widget>[
     SliverToBoxAdapter(
       child: SizedBox(height: kasyAppBarBodyTopOverlap(context)),
     ),
-    SliverPadding(
-      padding: pad,
-      sliver: SliverMainAxisGroup(slivers: slivers),
-    ),
+    paddedGroup,
   ];
 }
 
@@ -285,8 +313,12 @@ class KasyAppBar extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    // On desktop the web header owns the top chrome, so the page app bar hides.
-    if (MediaQuery.sizeOf(context).width >= DeviceType.large.breakpoint) {
+    // On desktop the web header owns the top chrome, so the page app bar hides —
+    // but ONLY when there actually is a web header above (i.e. inside the shell's
+    // KasyWebHeaderScope). A full-screen route pushed over the shell has no web
+    // header, so the bar stays visible and its back button is never lost.
+    if (MediaQuery.sizeOf(context).width >= DeviceType.large.breakpoint &&
+        KasyWebHeaderScope.of(context)) {
       return const SizedBox.shrink();
     }
     final Color orbFg = context.colors.onSurface;
@@ -461,6 +493,13 @@ class KasyOverlayScaffold extends StatelessWidget {
   final Widget? trailing;
   final List<Widget> slivers;
   final EdgeInsetsGeometry? contentPadding;
+
+  /// When set, content is centered within this max width on wide viewports
+  /// (desktop) instead of stretching edge-to-edge. Use [kKasyContentMaxWidth]
+  /// for the standard single-column internal page. Ignored when
+  /// [contentPadding] is provided (that takes full control of the insets).
+  final double? maxContentWidth;
+
   final ScrollController? scrollController;
   final ScrollPhysics? physics;
   final Color? backgroundColor;
@@ -480,6 +519,7 @@ class KasyOverlayScaffold extends StatelessWidget {
     this.trailing,
     required this.slivers,
     this.contentPadding,
+    this.maxContentWidth,
     this.scrollController,
     this.physics,
     this.backgroundColor,
@@ -504,6 +544,7 @@ class KasyOverlayScaffold extends StatelessWidget {
       slivers: kasyOverlayPaddedSlivers(
         context,
         contentPadding: contentPadding,
+        maxContentWidth: maxContentWidth,
         slivers: slivers,
       ),
     );