kasy-cli 1.34.0 → 1.35.0

package/templates/firebase/lib/core/data/api/remote_config_api.dart

@@ -1,4 +1,5 @@
 import 'package:firebase_remote_config/firebase_remote_config.dart';
+import 'package:flutter/foundation.dart' show kDebugMode;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:kasy_kit/core/initializer/onstart_service.dart';
 import 'package:logger/logger.dart';
@@ -17,6 +18,18 @@ final remoteConfigApiProvider = Provider<RemoteConfigApi>(
           api: remoteConfigWrapper,
         ),
       ),
+      appUpdate: AppUpdateConfigs(
+        latestVersion: FirebaseRemoteConfigData<String>(
+          key: 'app_latest_version',
+          api: remoteConfigWrapper,
+          defaultValue: '0.0.0',
+        ),
+        minVersion: FirebaseRemoteConfigData<String>(
+          key: 'app_min_version',
+          api: remoteConfigWrapper,
+          defaultValue: '0.0.0',
+        ),
+      ),
     );
   },
 );
@@ -48,10 +61,12 @@ final remoteConfigApiProvider = Provider<RemoteConfigApi>(
 class RemoteConfigApi implements OnStartService {
   final FirebaseRemoteConfig _remoteConfig;
   final SubscriptionConfigs subscription; // this is an example of group of keys
+  final AppUpdateConfigs appUpdate;
 
   RemoteConfigApi({
     required FirebaseRemoteConfig remoteConfig,
     required this.subscription,
+    required this.appUpdate,
   }) : _remoteConfig = remoteConfig;
 
   @override
@@ -59,7 +74,11 @@ class RemoteConfigApi implements OnStartService {
     try {
       await _remoteConfig.setConfigSettings(RemoteConfigSettings(
         fetchTimeout: const Duration(seconds: 60),
-        minimumFetchInterval: const Duration(hours: 1),
+        // In debug we fetch every launch so config changes (e.g. testing the
+        // "update available" versions) show up immediately; release throttles
+        // to once an hour as recommended.
+        minimumFetchInterval:
+            kDebugMode ? Duration.zero : const Duration(hours: 1),
       ));
       await _remoteConfig.fetchAndActivate();
     } catch (e) {
@@ -168,3 +187,21 @@ class SubscriptionConfigs {
   });
 }
 
+/// Remote keys that drive the "update available" prompt. Set these in the
+/// Firebase Remote Config console (works on every backend, since Firebase Core
+/// is always initialized):
+/// - `app_latest_version`: the newest version published to the stores. When the
+///   installed version is older, an *optional* update sheet is shown.
+/// - `app_min_version`: the oldest version still allowed. When the installed
+///   version is older, a *forced* (blocking) update sheet is shown.
+/// Both default to `0.0.0` (feature effectively off until you set real values).
+class AppUpdateConfigs {
+  final RemoteConfigData<String> latestVersion;
+  final RemoteConfigData<String> minVersion;
+
+  AppUpdateConfigs({
+    required this.latestVersion,
+    required this.minVersion,
+  });
+}
+

package/templates/firebase/lib/core/guards/guard.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
 
 enum RouterType {
   goRouter,
@@ -30,18 +31,27 @@ class Guard extends StatelessWidget {
       future: canActivate,
       builder: (_, result) {
         if (!result.hasData || result.hasError) {
-          return Container();
+          return _loadingScreen(context);
         }
         final bool canActivate = result.data!;
         if (canActivate) {
           return child;
         }
         redirect(context);
-        return loading ?? Container();
+        return loading ?? _loadingScreen(context);
       },
     );
   }
 
+  /// Themed placeholder shown while the guard resolves or redirects. Never a
+  /// bare [Container] (which paints nothing and shows the black window behind).
+  Widget _loadingScreen(BuildContext context) {
+    return Material(
+      color: context.colors.background,
+      child: const Center(child: CircularProgressIndicator.adaptive()),
+    );
+  }
+
   void redirect(BuildContext context) {
     WidgetsBinding.instance.addPostFrameCallback((timeStamp) {
       if (!context.mounted) return;
@@ -64,5 +74,9 @@ class Guard extends StatelessWidget {
           Navigator.of(context).pushReplacementNamed(fallbackRoute);
       }
     });
+    // addPostFrameCallback does not schedule a frame on its own; if the app is
+    // idle the redirect would otherwise wait until the next input event (the
+    // "stuck until you tap the screen" symptom). Force a frame so it runs now.
+    WidgetsBinding.instance.scheduleFrame();
   }
 }

package/templates/firebase/lib/core/icons/kasy_icons.dart

@@ -50,6 +50,9 @@ abstract final class KasyIcons {
 
   /// Collapse the left panel (sidebar) — narrow/expand toggle.
   static const IconData panelLeft = LucideIcons.panelLeft300;
+
+  /// Hamburger — opens the navigation drawer (e.g. from an app-bar leading).
+  static const IconData menu = LucideIcons.menu300;
   static const IconData cameraAlt = LucideIcons.camera400;
   static const IconData check = LucideIcons.check300;
   static const IconData checkCircle = LucideIcons.circleCheck300;

package/templates/firebase/lib/core/rating/widgets/rate_banner.dart

@@ -133,9 +133,7 @@ class RateBannerWidget extends StatelessWidget {
           Text(
             title,
             textAlign: TextAlign.center,
-            style: TextStyle(
-              fontSize: 17,
-              fontWeight: FontWeight.w600,
+            style: context.kasyTextTheme.sectionTitle.copyWith(
               color: cs.onSurface,
               height: 1.3,
             ),
@@ -144,8 +142,7 @@ class RateBannerWidget extends StatelessWidget {
           Text(
             text,
             textAlign: TextAlign.center,
-            style: TextStyle(
-              fontSize: 14,
+            style: context.textTheme.bodyMedium?.copyWith(
               color: cs.onSurface.withValues(alpha: 0.55),
               height: 1.4,
             ),

package/templates/firebase/lib/core/rating/widgets/review_popup.dart

@@ -21,9 +21,11 @@ Future<bool> showReviewDialog(
   WidgetRef ref, {
   bool force = false,
 }) async {
-  // Store reviews are a native-only concept (App Store / Play Store). On web
-  // there is nowhere to send the user, so the prompt never shows there.
-  if (kIsWeb) {
+  // Store reviews are native-only (App Store / Play Store). In production the
+  // auto prompt never shows on web (nowhere to send the user). But a forced
+  // call — the admin preview — still shows the dialog on web so its design can
+  // be reviewed there; only the store action won't do anything.
+  if (kIsWeb && !force) {
     return false;
   }
   if (!context.mounted) {

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

@@ -72,6 +72,20 @@ class SharedPreferencesBuilder implements OnStartService {
     return prefs.getBool('biometric_enabled') ?? false;
   }
 
+  /// Whether the user has already been through the one-time onboarding intro.
+  ///
+  /// Persisted locally so onboarding shows only once per install. Crucially it
+  /// survives logout (logout clears the account identity, not the fact that the
+  /// user has already seen the intro), so after signing out the user lands on
+  /// the sign-in screen instead of being dragged through onboarding again.
+  Future<void> setOnboardingCompleted(bool completed) async {
+    await prefs.setBool('onboarding_completed', completed);
+  }
+
+  bool getOnboardingCompleted() {
+    return prefs.getBool('onboarding_completed') ?? false;
+  }
+
   /// How many times the user dismissed the ATT soft prompt without accepting.
   /// Used to back off and eventually stop asking. See [MaybeShowAttPermission].
   int getAttSoftDismissCount() {

package/templates/firebase/lib/core/states/components/maybe_show_update_available.dart

@@ -0,0 +1,32 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/app_update/app_update_repository.dart';
+import 'package:kasy_kit/core/app_update/app_update_status.dart';
+import 'package:kasy_kit/core/app_update/update_available_sheet.dart';
+import 'package:kasy_kit/core/states/components/maybeshow_component.dart';
+import 'package:kasy_kit/core/states/models/event_model.dart';
+
+/// On app start, checks whether a newer version is available (remote config vs
+/// installed version) and, if so, prompts the user to update via the store.
+///
+/// Native-only. Distinct from `MaybeShowUpdateBottomSheet` (the "what's new"
+/// sheet, which runs *after* the user already updated): this runs *before*,
+/// when the user is behind. It is registered first so a required update
+/// pre-empts every other start-up prompt.
+class MaybeShowUpdateAvailable extends MaybeShowWithRef {
+  @override
+  Future<bool> handle(WidgetRef ref, AppEvent event) async {
+    if (event is! OnAppStartEvent) return false;
+    if (kIsWeb) return false;
+
+    final status = await ref.read(appUpdateRepositoryProvider).check();
+    if (status == AppUpdateStatus.upToDate) return false;
+    if (!ref.context.mounted) return false;
+
+    await showUpdateAvailableSheet(
+      ref.context,
+      forced: status == AppUpdateStatus.forced,
+    );
+    return true;
+  }
+}

package/templates/firebase/lib/core/states/logout_action.dart

@@ -20,6 +20,10 @@ Future<void> confirmLogout(BuildContext context, WidgetRef ref) {
     message: tr.disconnect_confirm_message,
     cancelLabel: tr.disconnect_cancel,
     confirmLabel: tr.disconnect,
-    onConfirm: () => ref.read(userStateNotifierProvider.notifier).onLogout(),
+    // Async so the confirm button shows a spinner while signing out, then the
+    // router redirect lands the user on the sign-in screen. (Don't fire-and-
+    // forget: that closed the dialog instantly and left the old screen frozen.)
+    onConfirmAsync: () =>
+        ref.read(userStateNotifierProvider.notifier).onLogout(),
   );
 }

package/templates/firebase/lib/core/states/user_state_notifier.dart

@@ -10,6 +10,7 @@ import 'package:kasy_kit/core/data/repositories/user_repository.dart';
 import 'package:kasy_kit/core/initializer/onstart_service.dart';
 import 'package:kasy_kit/core/shared_preferences/shared_preferences.dart';
 import 'package:kasy_kit/core/states/models/user_state.dart';
+import 'package:kasy_kit/core/utils/image_bytes_loader.dart';
 import 'package:kasy_kit/environments.dart';
 import 'package:kasy_kit/features/authentication/repositories/authentication_repository.dart';
 import 'package:kasy_kit/features/notifications/providers/models/device.dart';
@@ -89,11 +90,18 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
     state = const UserState(user: User.loading());
     await _loadState();
     await _initDeviceRegistration();
+    // A successful sign-in puts the user past first-run onboarding. Remember it
+    // so that after a later logout they land on the sign-in screen instead of
+    // being sent back through onboarding.
+    await ref.read(sharedPreferencesProvider).setOnboardingCompleted(true);
   }
 
   /// Set the user as onboarded in the database
   /// This function is called when the user has completed the onboarding
   Future<void> onOnboarded() async {
+    // Remember locally that onboarding is done, so it's never shown again on
+    // this install (survives logout and account deletion).
+    await ref.read(sharedPreferencesProvider).setOnboardingCompleted(true);
     if (state.user.idOrNull == null) {
       // Guest with no account: persist onboarding in local state only.
       // No Firestore document exists yet — no write needed.
@@ -104,10 +112,27 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
     state = state.copyWith(user: newUser);
   }
 
+  /// Finish onboarding (or "continue as guest" from the sign-in screen) by
+  /// making sure the user has a backend identity, then marking them onboarded.
+  ///
+  /// This is the ONLY place an anonymous account is created. It is created
+  /// lazily here — never eagerly on app start, never on logout — so users who
+  /// never get this far (or who later sign out) don't leave orphan anonymous
+  /// accounts behind in the backend.
+  Future<void> continueAsGuest() async {
+    if (mode == AuthenticationMode.anonymous && state.user.idOrNull == null) {
+      await _loadAnonymousState();
+    }
+    await onOnboarded();
+  }
+
   /// Mark the user as onboarded immediately (optimistic) and write to the
   /// backend in background. Used by the skip-onboarding flow so navigation
   /// to home is instant — no spinner while waiting for a network round-trip.
   void onSkippedOnboarding() {
+    // Remember onboarding as done locally (same flag as [onOnboarded]) so it's
+    // never shown again, even after a logout.
+    unawaited(ref.read(sharedPreferencesProvider).setOnboardingCompleted(true));
     state = state.copyWith(
       user: switch (state.user) {
         final AuthenticatedUserData u => u.copyWith(onboarded: true),
@@ -142,11 +167,14 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
     await ref.read(sharedPreferencesProvider).setBiometricEnabled(false);
     // Forget the last bottom-bar tab so the next login lands on the default tab
     // (Home) instead of wherever the previous account left off.
-    activeTabRouteNotifier.value = null;
+    forgetActiveTab();
     state = const UserState(user: User.anonymous());
-    if (mode == AuthenticationMode.anonymous) {
-      await _loadAnonymousState();
-    }
+    // No anonymous re-signup here. The router redirect sends the user to the
+    // sign-in screen (onboarding is remembered as done, so it isn't repeated).
+    // Recreating an anonymous account on every logout would pile up orphan
+    // users in the backend — an anonymous account is only ever created lazily,
+    // in [continueAsGuest], when the user finishes onboarding or explicitly
+    // chooses to continue as a guest.
   }
 
   /// Refresh the user
@@ -164,6 +192,41 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
     state = state.copyWith(user: user ?? User.anonymous(id: id));
   }
 
+  /// On first social sign-in, copy the provider's profile photo (e.g. Google)
+  /// into our own storage so the user starts with an avatar. Best-effort and
+  /// one-shot: only runs when the user has no avatar yet, and it never overwrites
+  /// a photo the user set manually. Apple does not expose a photo (no-op there).
+  Future<void> _importSocialAvatarIfNeeded() async {
+    final user = state.user;
+    if (user is! AuthenticatedUserData) return;
+    final userId = user.id;
+    if (userId == null || userId.isEmpty) return;
+    if (user.avatarPath?.isNotEmpty ?? false) return; // keep existing avatar
+    try {
+      final photoUrl = await _authenticationRepository.getCurrentUserPhotoUrl();
+      if (photoUrl == null || photoUrl.isEmpty) return;
+      final bytes = await loadImageBytes(_normalizeAvatarUrl(photoUrl));
+      if (bytes == null || bytes.isEmpty) return;
+      await for (final _ in _userRepository.saveAvatar(
+        userId: userId,
+        data: Uint8List.fromList(bytes),
+      )) {}
+      await refresh();
+    } catch (e) {
+      // Best-effort: keep the fallback avatar if the import fails.
+      _logger.w('Social avatar import skipped: $e');
+    }
+  }
+
+  /// Google serves profile photos with a size suffix (e.g. `=s96-c`, only 96px).
+  /// Request a ~400px source so the avatar stays crisp after our 450px
+  /// re-compression. URLs from other providers are returned unchanged.
+  String _normalizeAvatarUrl(String url) {
+    if (!url.contains('googleusercontent.com')) return url;
+    final base = url.contains('=') ? url.substring(0, url.indexOf('=')) : url;
+    return '$base=s400-c';
+  }
+
   /// This function is called after a user successfuly purchased a subscription
   /// It will refresh the subscription state without waiting for the webhook
   /// (which can take some time and could show a wrong state to the user)
@@ -208,11 +271,14 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
     }
     await _userRepository.delete();
     await _authenticationRepository.logout();
+    // Same as onLogout: forget the last bottom-bar tab so the next account that
+    // signs in lands on Home, not wherever the deleted account left off (the
+    // user deletes from Settings, so without this the next login reopens it).
+    forgetActiveTab();
     state = const UserState(user: User.anonymous());
-
-    if (mode == AuthenticationMode.anonymous) {
-      await _loadAnonymousState();
-    }
+    // Same as [onLogout]: no anonymous re-signup. The user lands on the sign-in
+    // screen; a new anonymous account is only created lazily if they choose to
+    // continue as a guest.
   }
 
   // -------------------------------
@@ -252,13 +318,16 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
   Future<void> _loadState() async {
     final credentials = await _authenticationRepository.get();
 
-    if (credentials == null && mode == AuthenticationMode.anonymous) {
-      _logger.i('Anonymous user mode activated, signup anonymously');
-      await _loadAnonymousState();
-    } else if (credentials == null && mode == AuthenticationMode.authRequired) {
-      _logger.i('Authentification required, user is not connected');
+    if (credentials == null) {
+      // No account yet. We deliberately do NOT create an anonymous account here
+      // anymore (even in anonymous mode). It's created lazily in
+      // [continueAsGuest] when the user finishes onboarding or taps "continue
+      // as guest", so simply opening the app — or signing out — never piles up
+      // orphan anonymous users. The router redirect decides where to send them:
+      // onboarding on the very first run, the sign-in screen after a logout.
+      _logger.i('No credentials: user starts as a guest with no account yet');
       state = state.copyWith(user: const User.anonymous());
-    } else if (credentials != null) {
+    } else {
       _logger.i('User is connected with id ${credentials.id}');
       var user = await _userRepository.get(credentials.id);
       // Retry a few times: the Cloud Function onUserRegistration may not have
@@ -299,10 +368,12 @@ class UserStateNotifier extends _$UserStateNotifier implements OnStartService {
           );
           final syncedUser = await _userRepository.get(credentials.id);
           state = state.copyWith(user: syncedUser ?? user);
+          unawaited(_importSocialAvatarIfNeeded());
           return;
         }
       }
       state = state.copyWith(user: user);
+      unawaited(_importSocialAvatarIfNeeded());
     }
   }
 

package/templates/firebase/lib/core/theme/responsive_text_theme.dart

@@ -0,0 +1,69 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/core/theme/texts.dart';
+import 'package:kasy_kit/core/widgets/responsive_layout.dart';
+
+/// Republishes the app's typography for the current breakpoint — without
+/// touching a single call site.
+///
+/// It reads the effective viewport width, picks the [DeviceType], and rebuilds
+/// the Material `textTheme` and the [KasyTextTheme] extension from the
+/// per-breakpoint [KasyTypeScale] ramp. Headings step down from desktop to
+/// mobile; body and labels stay constant. Colours are kept from the base theme
+/// (the ramp is colourless), so every `context.textTheme.*` and
+/// `context.kasyTextTheme.*` below inherits the breakpoint's sizes.
+///
+/// Placed as the innermost wrapper of the app (inside `WebViewportScale` and
+/// `DevicePreview`), so it reads the *same* width the screens lay out against:
+/// the type bucket always matches the layout bucket. Desktop is the authored
+/// baseline, so it is a pass-through there.
+class ResponsiveTextTheme extends StatelessWidget {
+  final Widget child;
+
+  const ResponsiveTextTheme({super.key, required this.child});
+
+  @override
+  Widget build(BuildContext context) {
+    final DeviceType device =
+        DeviceType.fromWidth(MediaQuery.sizeOf(context).width);
+
+    // Desktop is the authored baseline (the base theme built in main.dart) — no
+    // rebuild needed.
+    if (device != DeviceType.small && device != DeviceType.medium) {
+      return child;
+    }
+
+    final ThemeData theme = Theme.of(context);
+    final KasyTextTheme ramp = KasyTextTheme.build(device);
+    final TextTheme base = theme.textTheme;
+
+    // Take size/weight/line-height from the ramp, keep colour from the base
+    // (the ramp is colourless, so merge preserves the base slot's colour).
+    final TextTheme rebuilt = TextTheme(
+      displayLarge: base.displayLarge?.merge(ramp.displayLarge),
+      displayMedium: base.displayMedium?.merge(ramp.displayMedium),
+      displaySmall: base.displaySmall?.merge(ramp.displaySmall),
+      headlineLarge: base.headlineLarge?.merge(ramp.headlineLarge),
+      headlineMedium: base.headlineMedium?.merge(ramp.headlineMedium),
+      headlineSmall: base.headlineSmall?.merge(ramp.headlineSmall),
+      titleLarge: base.titleLarge?.merge(ramp.titleLarge),
+      titleMedium: base.titleMedium?.merge(ramp.titleMedium),
+      titleSmall: base.titleSmall?.merge(ramp.titleSmall),
+      bodyLarge: base.bodyLarge?.merge(ramp.bodyLarge),
+      bodyMedium: base.bodyMedium?.merge(ramp.bodyMedium),
+      bodySmall: base.bodySmall?.merge(ramp.bodySmall),
+      labelLarge: base.labelLarge?.merge(ramp.labelLarge),
+      labelMedium: base.labelMedium?.merge(ramp.labelMedium),
+      labelSmall: base.labelSmall?.merge(ramp.labelSmall),
+    );
+
+    // Replace only the KasyTextTheme extension; keep every other extension.
+    final List<ThemeExtension<dynamic>> extensions = theme.extensions.values
+        .map((e) => e is KasyTextTheme ? ramp : e)
+        .toList();
+
+    return Theme(
+      data: theme.copyWith(textTheme: rebuilt, extensions: extensions),
+      child: child,
+    );
+  }
+}

package/templates/firebase/lib/core/theme/texts.dart

@@ -1,5 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:google_fonts/google_fonts.dart';
+import 'package:kasy_kit/core/theme/type_scale.dart';
+import 'package:kasy_kit/core/widgets/responsive_layout.dart';
 
 /// Kasy Design System — Typography Tokens (HeroUI type scale)
 ///
@@ -32,6 +34,22 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
         decoration: decoration,
       );
 
+  // Builds a role from its responsive [RampSize] at a given [device]: the size
+  // (and proportional line-height) come from the breakpoint, the weight from
+  // the role. This is how every slot picks up the per-breakpoint type scale.
+  static TextStyle _fromRamp(
+    FontWeight weight,
+    RampSize ramp,
+    DeviceType device, {
+    TextDecoration? decoration,
+  }) =>
+      _inter(
+        weight,
+        ramp.size(device),
+        ramp.lineHeight(device),
+        decoration: decoration,
+      );
+
   // -----------------------------------------------------------------------
   // HeroUI roles — canonical styles (color applied per-theme downstream)
   // -----------------------------------------------------------------------
@@ -54,37 +72,9 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
   static TextStyle get buttonBase => _inter(FontWeight.w500, 16, 24);
   static TextStyle get buttonSm => _inter(FontWeight.w500, 14, 20);
 
-  // -----------------------------------------------------------------------
-  // Semantic app roles — name the recurring UI text roles so screens stop
-  // hand-tuning slots with copyWith(fontSize/fontWeight/...). Each composes a
-  // scale role above; restyle a role app-wide by editing it here once.
-  // Apply color at the call site (.copyWith(color: ...)); the scale is colorless.
-  // -----------------------------------------------------------------------
-
-  /// Top-level page title (auth, paywall, full-screen flows). 24 / w700.
-  static TextStyle get pageTitle => heading2;
-
-  /// Section or master-detail pane title (Settings detail, grouped areas). 16 / w600.
-  static TextStyle get sectionTitle => heading4;
-
-  /// Small header above a grouped list (e.g. "PREFERENCES"). 12 / w600, lightly tracked.
-  static TextStyle get sectionLabel =>
-      _inter(FontWeight.w600, 12, 16).copyWith(letterSpacing: 0.5);
-
-  /// Primary text of a list / settings row. 14 / w500.
-  static TextStyle get rowTitle => bodySmMedium;
-
-  /// Secondary / value text in a row (apply a muted color at the call site). 14 / w400.
-  static TextStyle get rowValue => bodySm;
-
-  /// Card title. 14 / w500.
-  static TextStyle get cardTitle => bodySmMedium;
-
-  /// Card subtitle / supporting line. 12 / w400.
-  static TextStyle get cardSubtitle => bodyXs;
-
-  /// Caption, hint, version label, footnote. 12 / w400.
-  static TextStyle get caption => bodyXs;
+  // Semantic UI roles (pageTitle, sectionTitle, rowTitle, …) live as INSTANCE
+  // getters further down, so they pick up the per-breakpoint scaling. The raw
+  // scale roles above stay static (the authored spec / design-system baseline).
 
   // -----------------------------------------------------------------------
   // Display — large hero text (extends the HeroUI scale upward in Inter)
@@ -143,35 +133,78 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
     required this.primary,
   });
 
-  factory KasyTextTheme.build() {
+  // -----------------------------------------------------------------------
+  // Semantic app roles — INSTANCE getters (responsive).
+  //
+  // These mirror the static roles above, but derive from this instance's
+  // fields, so they pick up the per-breakpoint scaling applied by
+  // [ResponsiveTextTheme]. Prefer `context.kasyTextTheme.<role>` on screens
+  // when you need a role that scales (the static `KasyTextTheme.<role>` stays
+  // fixed at the desktop baseline — fine for specs/docs, not for live UI).
+  // Apply colour at the call site; the scale is colourless.
+  // -----------------------------------------------------------------------
+
+  /// Top-level page title (auth, paywall, full-screen flows). 24 / w700.
+  TextStyle get pageTitle => headlineMedium;
+
+  /// Section or master-detail pane title (Settings detail, grouped areas). 16 / w600.
+  TextStyle get sectionTitle => titleMedium;
+
+  /// Small header above a grouped list (e.g. "PREFERENCES"). 12 / w600, lightly tracked.
+  TextStyle get sectionLabel =>
+      bodySmall.copyWith(fontWeight: FontWeight.w600, letterSpacing: 0.5);
+
+  /// Primary text of a list / settings row. 14 / w500.
+  TextStyle get rowTitle => titleSmall;
+
+  /// Secondary / value text in a row (apply a muted colour at the call site). 14 / w400.
+  TextStyle get rowValue => bodyMedium;
+
+  /// Card title. 14 / w500.
+  TextStyle get cardTitle => titleSmall;
+
+  /// Card subtitle / supporting line. 12 / w400.
+  TextStyle get cardSubtitle => bodySmall;
+
+  /// Caption, hint, version label, footnote. 12 / w400.
+  TextStyle get caption => bodySmall;
+
+  /// Builds the full text theme for a given [device].
+  ///
+  /// Each slot resolves its size from the responsive [KasyTypeScale] ramp at the
+  /// breakpoint: headings step down from desktop to mobile, body and labels stay
+  /// constant. Defaults to desktop ([DeviceType.large]) so the base theme built
+  /// once in `main.dart` is the authored reference; [ResponsiveTextTheme]
+  /// rebuilds it per breakpoint below the MediaQuery.
+  factory KasyTextTheme.build([DeviceType device = DeviceType.large]) {
     return KasyTextTheme(
-      // Display — hero text in Inter, neutral tracking.
-      displayLarge: _inter(FontWeight.w800, 57, 64),
-      displayMedium: _inter(FontWeight.w800, 45, 52),
-      displaySmall: heading1, // 36/40
-
-      // Headline → HeroUI Heading 1–3.
-      headlineLarge: heading1,
-      headlineMedium: heading2,
-      headlineSmall: heading3,
-
-      // Title → HeroUI Heading 3 / Heading 4 / Body sm medium.
-      titleLarge: heading3,
-      titleMedium: heading4,
-      titleSmall: bodySmMedium,
-
-      // Body → HeroUI Body base / Body sm / Body xs.
-      bodyLarge: bodyBase,
-      bodyMedium: bodySm,
-      bodySmall: bodyXs,
-
-      // Label → HeroUI Button sm / Body xs medium.
-      labelLarge: buttonSm,
-      labelMedium: bodyXsMedium,
-      labelSmall: bodyXsMedium,
+      // Display — hero text.
+      displayLarge: _fromRamp(FontWeight.w800, KasyTypeScale.displayLarge, device),
+      displayMedium: _fromRamp(FontWeight.w800, KasyTypeScale.displayMedium, device),
+      displaySmall: _fromRamp(FontWeight.w800, KasyTypeScale.heading1, device),
+
+      // Headline → Heading 1–3.
+      headlineLarge: _fromRamp(FontWeight.w800, KasyTypeScale.heading1, device),
+      headlineMedium: _fromRamp(FontWeight.w700, KasyTypeScale.heading2, device),
+      headlineSmall: _fromRamp(FontWeight.w600, KasyTypeScale.heading3, device),
+
+      // Title → Heading 3 / Heading 4 / Body sm medium.
+      titleLarge: _fromRamp(FontWeight.w600, KasyTypeScale.heading3, device),
+      titleMedium: _fromRamp(FontWeight.w600, KasyTypeScale.heading4, device),
+      titleSmall: _fromRamp(FontWeight.w500, KasyTypeScale.bodySm, device),
+
+      // Body → Body base / Body sm / Body xs.
+      bodyLarge: _fromRamp(FontWeight.w400, KasyTypeScale.bodyBase, device),
+      bodyMedium: _fromRamp(FontWeight.w400, KasyTypeScale.bodySm, device),
+      bodySmall: _fromRamp(FontWeight.w400, KasyTypeScale.bodyXs, device),
+
+      // Label → Button sm / Body xs medium.
+      labelLarge: _fromRamp(FontWeight.w500, KasyTypeScale.bodySm, device),
+      labelMedium: _fromRamp(FontWeight.w500, KasyTypeScale.bodyXs, device),
+      labelSmall: _fromRamp(FontWeight.w500, KasyTypeScale.bodyXs, device),
 
       // Legacy primary.
-      primary: bodyBase,
+      primary: _fromRamp(FontWeight.w400, KasyTypeScale.bodyBase, device),
     );
   }