kasy-cli 1.31.9 → 1.31.11

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);
   }

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

@@ -533,7 +533,9 @@ class _DeviceSwitchBridgeState extends State<_DeviceSwitchBridge> {
   void _onFrameVisibleChanged() {
     if (!mounted) return;
     final store = Provider.of<DevicePreviewStore>(context, listen: false);
-    if (store.data.isFrameVisible != widget.frameVisibleNotifier.value) {
+    final data = _readData(store);
+    if (data == null) return;
+    if (data.isFrameVisible != widget.frameVisibleNotifier.value) {
       store.toggleFrame();
     }
   }
@@ -543,11 +545,31 @@ class _DeviceSwitchBridgeState extends State<_DeviceSwitchBridge> {
   void _syncOrientation() {
     if (!mounted) return;
     final store = Provider.of<DevicePreviewStore>(context, listen: false);
+    final data = _readData(store);
+    if (data == null) {
+      // DevicePreview initializes asynchronously (it loads saved preferences), so
+      // on the first web frame the store can still be uninitialized and reading
+      // store.data throws "Not initialized". Retry next frame instead of surfacing
+      // a scary (and harmless) exception in the console.
+      WidgetsBinding.instance.addPostFrameCallback((_) => _syncOrientation());
+      return;
+    }
     final target = widget.landscapeNotifier.value
         ? Orientation.landscape
         : Orientation.portrait;
-    if (store.data.orientation != target) {
-      store.data = store.data.copyWith(orientation: target);
+    if (data.orientation != target) {
+      store.data = data.copyWith(orientation: target);
+    }
+  }
+
+  /// [DevicePreviewStore.data] throws while the store is still finishing its async
+  /// initialization. Returns null instead of throwing so callers can skip or retry
+  /// cleanly (see _syncOrientation).
+  DevicePreviewData? _readData(DevicePreviewStore store) {
+    try {
+      return store.data;
+    } catch (_) {
+      return null;
     }
   }
 

package/templates/firebase/lib/features/home/home_feed.dart

@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:kasy_kit/components/kasy_app_bar.dart';
 import 'package:kasy_kit/components/kasy_card.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
@@ -213,7 +214,12 @@ class _HomeFeedState extends State<HomeFeed> {
       child: Column(
         crossAxisAlignment: CrossAxisAlignment.stretch,
         children: <Widget>[
-          const SizedBox(height: KasySpacing.belowChromeContentGap),
+          // App bar inset lives INSIDE the scroll so it scrolls away and the
+          // feed slides under the frosted bar (overlay pattern).
+          SizedBox(
+            height: kasyAppBarBodyTopOverlap(context) +
+                KasySpacing.belowChromeContentGap,
+          ),
           _FilterRow(selected: _selected, onSelect: _select),
           const SizedBox(height: KasySpacing.lg),
           Padding(

package/templates/firebase/lib/features/home/home_page.dart

@@ -31,14 +31,11 @@ class HomePage extends ConsumerWidget {
         color: context.colors.background,
         child: Stack(
           children: [
-            Positioned.fill(
-              child: Padding(
-                padding: EdgeInsets.only(
-                  top: kasyAppBarBodyTopOverlap(context),
-                ),
-                child: const HomeFeed(),
-              ),
-            ),
+            // True overlay: the feed fills the whole height and scrolls UNDER
+            // the frosted app bar (the bar's top inset lives inside the feed's
+            // scroll, so it scrolls away). This way, when the bar hides on
+            // scroll, content already fills the top — no empty app-bar band.
+            const Positioned.fill(child: HomeFeed()),
             Positioned(
               top: 0,
               left: 0,
@@ -46,6 +43,7 @@ class HomePage extends ConsumerWidget {
               child: KasyAppBar(
                 title: t.home.dashboard.brand,
                 style: KasyAppBarStyle.rootTab,
+                hideOnScroll: true,
                 onThemeToggle: () {
                   KasyHaptics.light(context);
                   ThemeProvider.of(context).toggle();

package/templates/firebase/lib/features/notifications/ui/notifications_page.dart

@@ -105,6 +105,7 @@ class _NotificationsPageState extends ConsumerState<NotificationsPage> {
     return KasyOverlayScaffold(
       title: t.notifications.title,
       appBarStyle: KasyAppBarStyle.rootTab,
+      hideAppBarOnScroll: true,
       scrollController: _scrollController,
       trailing: Builder(
         builder: (ctx) => Row(

package/templates/firebase/lib/features/settings/settings_page.dart

@@ -3,6 +3,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 import 'package:kasy_kit/components/components.dart';
+import 'package:kasy_kit/core/chrome/chrome_visibility.dart';
 import 'package:kasy_kit/core/config/features.dart';
 import 'package:kasy_kit/core/data/models/user.dart';
 import 'package:kasy_kit/core/haptics/haptic_feedback_notifier.dart';
@@ -41,6 +42,7 @@ class SettingsPage extends ConsumerWidget {
     return KasyOverlayScaffold(
       title: tr.title,
       appBarStyle: KasyAppBarStyle.rootTab,
+      hideAppBarOnScroll: true,
       trailing: Builder(
         builder: (ctx) => KasyChromeOrbIconButton(
           icon: KasyIcons.logout,
@@ -118,6 +120,10 @@ class SettingsPage extends ConsumerWidget {
             const SettingsDivider(),
             const HapticFeedbackSwitcher(),
             const SettingsDivider(),
+            if (kShowHideChromeOnScrollSetting) ...[
+              const HideChromeOnScrollSwitcher(),
+              const SettingsDivider(),
+            ],
             const LanguageSwitcher(),
             if (withLocalReminders) ...[
               const SettingsDivider(),
@@ -641,6 +647,10 @@ class _DesktopDetail extends ConsumerWidget {
                 const SettingsDivider(),
                 const HapticFeedbackSwitcher(),
                 const SettingsDivider(),
+                if (kShowHideChromeOnScrollSetting) ...[
+                  const HideChromeOnScrollSwitcher(),
+                  const SettingsDivider(),
+                ],
                 const LanguageSwitcher(),
                 if (withLocalReminders) ...[
                   const SettingsDivider(),
@@ -953,6 +963,22 @@ class HapticFeedbackSwitcher extends ConsumerWidget {
   }
 }
 
+class HideChromeOnScrollSwitcher extends ConsumerWidget {
+  const HideChromeOnScrollSwitcher({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final isEnabled = ref.watch(hideChromeOnScrollProvider);
+    return SettingsSwitchTile(
+      icon: KasyIcons.eyeOff,
+      title: context.t.settings.hide_chrome_on_scroll_title,
+      value: isEnabled,
+      onChanged: (_) =>
+          ref.read(hideChromeOnScrollProvider.notifier).toggle(),
+    );
+  }
+}
+
 class ThemeSwitcher extends StatelessWidget {
   const ThemeSwitcher({super.key});
 

package/templates/firebase/lib/features/subscriptions/api/stripe_payment_api.dart

@@ -40,6 +40,10 @@ class StripePaymentApi implements SubscriptionPaymentApi {
       cancelUrl: returnUrl,
     );
     await _open(url);
+    // Checkout is now open in a new tab. Payment is NOT confirmed yet — the
+    // webhook will write the subscription record when the user pays. Throw so
+    // the provider knows to poll for activation instead of setting active now.
+    throw PendingWebCheckoutException();
   }
 
   @override
@@ -75,8 +79,6 @@ class StripePaymentApi implements SubscriptionPaymentApi {
   Future<void> presentCodeRedemptionSheet() async {}
 
   Future<void> _open(String url) async {
-    // On web, redirect the current tab so the user returns to the app after
-    // Stripe Checkout / the Customer Portal.
-    await launchUrl(Uri.parse(url), webOnlyWindowName: '_self');
+    await launchUrl(Uri.parse(url), webOnlyWindowName: '_blank');
   }
 }

package/templates/firebase/lib/features/subscriptions/api/subscription_payment_api.dart

@@ -51,3 +51,11 @@ abstract interface class SubscriptionPaymentApi {
 class UserCancelledPurchaseException implements Exception {
   UserCancelledPurchaseException();
 }
+
+/// Thrown by [StripePaymentApi.purchaseProduct] on web after the hosted
+/// Checkout URL is opened in a new browser tab. The purchase is NOT complete —
+/// the caller must poll for subscription activation (via webhook) instead of
+/// treating the returned Future as payment confirmation.
+class PendingWebCheckoutException implements Exception {
+  PendingWebCheckoutException();
+}

package/templates/firebase/lib/features/subscriptions/providers/premium_page_provider.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart' show PlatformException;
 import 'package:kasy_kit/core/data/api/analytics_api.dart';
+import 'package:kasy_kit/core/data/models/entitlement.dart';
 import 'package:kasy_kit/core/data/models/subscription.dart';
 import 'package:kasy_kit/core/states/models/user_state.dart';
 import 'package:kasy_kit/core/states/translations.dart';
@@ -8,7 +9,7 @@ import 'package:kasy_kit/core/states/user_state_notifier.dart';
 import 'package:kasy_kit/core/toast/toast_service.dart';
 import 'package:kasy_kit/features/feedbacks/repositories/feature_request_repository.dart';
 import 'package:kasy_kit/features/subscriptions/api/subscription_payment_api.dart'
-    show UserCancelledPurchaseException;
+    show PendingWebCheckoutException, UserCancelledPurchaseException;
 import 'package:kasy_kit/features/subscriptions/providers/models/premium_state.dart';
 import 'package:kasy_kit/features/subscriptions/repositories/subscription_repository.dart';
 import 'package:kasy_kit/router.dart';
@@ -123,61 +124,102 @@ class PremiumStateNotifier extends _$PremiumStateNotifier {
     String? paywall,
     String? redirectRoute,
   }) async {
-    state = switch (state.value) {
-      PremiumStateData(:final offers) => AsyncData(
-        PremiumState.sending(
-          isPremium: false,
-          offers: offers,
-          selectedOffer: offer,
-        ),
-      ),
+    final currentOffers = switch (state.value) {
+      PremiumStateData(:final offers) => offers,
       _ => throw "cannot purchase while active",
     };
+    state = AsyncData(
+      PremiumState.sending(isPremium: false, offers: currentOffers, selectedOffer: offer),
+    );
     try {
       final entitlements = await _subscriptionRepository.purchase(offer);
-      state = AsyncData(PremiumState.active(activeOffer: offer));
-      await _analyticsApi?.logEvent("purchase", {
-        "skuId": offer.skuId,
-        "price": offer.price,
-        // "promotion": offer.promotion,
-        "duration": offer.duration,
-        "paywall": paywall,
-      });
-      // let's refresh the user state
-      await ref
-          .read(userStateNotifierProvider.notifier)
-          .refreshSubscription(product: offer, entitlements: entitlements);
-      final t = ref.read(translationsProvider);
-      ref
-          .read(toastProvider)
-          .success(
-            title: t.premium.purchase_success_title,
-            text: t.premium.purchase_success_text,
-          );
-      await Future.delayed(const Duration(seconds: 2));
-      if (redirectRoute != null) ref.read(goRouterProvider).go(redirectRoute);
+      await _activateAfterPurchase(offer, entitlements, paywall, redirectRoute);
+    } on PendingWebCheckoutException {
+      // Stripe web: checkout opened in a new tab. Poll until the webhook
+      // activates the subscription or we time out.
+      await _waitForWebPayment(offer, currentOffers, paywall: paywall, redirectRoute: redirectRoute);
     } catch (err, stackTrace) {
-      state = switch (state.value) {
-        PremiumStateData(:final offers) => AsyncData(
-          PremiumState(offers: offers, selectedOffer: offer),
-        ),
-        PremiumStateSending(:final offers) => AsyncData(
-          PremiumState(offers: offers, selectedOffer: offer),
-        ),
-        PremiumStateActive() => state,
-        _ => throw "cannot purchase while active",
-      };
+      state = AsyncData(PremiumState(offers: currentOffers, selectedOffer: offer));
       if (err is UserCancelledPurchaseException) return;
       await Sentry.captureException(err, stackTrace: stackTrace);
       _logger.e("...PremiumStateNotifier: purchase failed $err : $stackTrace");
       final t = ref.read(translationsProvider);
-      ref
-          .read(toastProvider)
-          .error(
-            title: t.premium.error_title,
-            text: t.premium.error_text,
-            reason: "We were unable to process your subscription",
-          );
+      ref.read(toastProvider).error(
+        title: t.premium.error_title,
+        text: t.premium.error_text,
+        reason: "We were unable to process your subscription",
+      );
+    }
+  }
+
+  Future<void> _activateAfterPurchase(
+    SubscriptionProduct offer,
+    List<Entitlement>? entitlements,
+    String? paywall,
+    String? redirectRoute,
+  ) async {
+    state = AsyncData(PremiumState.active(activeOffer: offer));
+    await _analyticsApi?.logEvent("purchase", {
+      "skuId": offer.skuId,
+      "price": offer.price,
+      "duration": offer.duration,
+      "paywall": paywall,
+    });
+    await ref
+        .read(userStateNotifierProvider.notifier)
+        .refreshSubscription(product: offer, entitlements: entitlements);
+    final t = ref.read(translationsProvider);
+    ref.read(toastProvider).success(
+      title: t.premium.purchase_success_title,
+      text: t.premium.purchase_success_text,
+    );
+    await Future.delayed(const Duration(seconds: 2));
+    if (redirectRoute != null) ref.read(goRouterProvider).go(redirectRoute);
+  }
+
+  /// Polls the subscription backend every 5 s until the Stripe webhook delivers
+  /// the activation (up to 10 min). Runs while the state is [PremiumStateSending].
+  Future<void> _waitForWebPayment(
+    SubscriptionProduct offer,
+    List<SubscriptionProduct> currentOffers, {
+    String? paywall,
+    String? redirectRoute,
+  }) async {
+    const maxAttempts = 120; // 10 min at 5 s intervals
+    const interval = Duration(seconds: 5);
+    final userId = _userState.user.idOrNull;
+    if (userId == null) {
+      state = AsyncData(PremiumState(offers: currentOffers, selectedOffer: offer));
+      return;
+    }
+
+    try {
+      for (var i = 0; i < maxAttempts; i++) {
+        await Future.delayed(interval);
+        if (state.value is! PremiumStateSending) return;
+        try {
+          final sub = await _subscriptionRepository.get(userId);
+          if (sub.isActive) {
+            await _activateAfterPurchase(offer, null, paywall, redirectRoute);
+            return;
+          }
+        } catch (_) {
+          // network / backend error → keep polling; disposal propagates to
+          // the outer catch on the next state.value access.
+        }
+      }
+
+      // Timed out — revert to paywall and ask the user to restore if they paid.
+      if (state.value is PremiumStateSending) {
+        state = AsyncData(PremiumState(offers: currentOffers, selectedOffer: offer));
+        final t = ref.read(translationsProvider);
+        ref.read(toastProvider).error(
+          title: t.premium.web_checkout_timeout_title,
+          text: t.premium.web_checkout_timeout_text,
+        );
+      }
+    } catch (_) {
+      // Provider was disposed while polling (user left the paywall). Ignore.
     }
   }