fix(flowr): harden listenable disposal

Author: Hu-Wentao

packages/flowr/lib/src/mixin/change_notifier.dart

@@ -84,11 +84,4 @@ mixin FrChangeNotifierMx<M> on FrViewModel<M>, ChangeNotifier {
       mutexTag: mutexTag,
     );
   }
-
-  /// Disposes both ChangeNotifier listeners and FlowR resources.
-  @override
-  void dispose() {
-    super.dispose();
-    unawaited(close());
-  }
 }

packages/flowr/lib/src/provider.dart

@@ -227,6 +227,10 @@ FrProvider(
 /// A FlowR-named [ListenableProvider] for creating [ChangeNotifier] values.
 class FrListenableProvider<T extends ChangeNotifier>
     extends ListenableProvider<T> {
+  /// Creates a [ChangeNotifier] and closes FlowR resources with it.
+  ///
+  /// [dispose] is an optional hook that runs before automatic disposal. It
+  /// must not dispose [T] itself.
   FrListenableProvider(
     Create<T> create, {
     super.key,
@@ -237,8 +241,20 @@ class FrListenableProvider<T extends ChangeNotifier>
   }) : super(
          create: create,
          dispose: (context, notifier) {
-           dispose?.call(context, notifier);
-           notifier.dispose();
+           try {
+             dispose?.call(context, notifier);
+           } finally {
+             try {
+               notifier.dispose();
+             } finally {
+               if (notifier is Closable) {
+                 final closable = notifier as Closable;
+                 if (!closable.isClosed) {
+                   unawaited(Future<void>.sync(closable.close));
+                 }
+               }
+             }
+           }
          },
        );
 }

packages/flowr/lib/src/support/provider/provider_support.dart

@@ -4,7 +4,7 @@ import 'package:flowr/src/view_model.dart' show FrViewModel;
 import 'package:flutter/foundation.dart';
 
 /// support Provider-Consumer
-/// adapt ChangeNotifierProvider use ChangeNotifier
+/// adapt FrProvider.listenable use ChangeNotifier
 abstract class FrChangeNotifierVM<M extends FrModel> extends FrViewModel<M>
     with ChangeNotifier, FrChangeNotifierMx {
   FrChangeNotifierVM(super.initialState);

packages/flowr/test/mixin/change_notifier_test.dart

@@ -1,3 +1,5 @@
+import 'dart:async' show unawaited;
+
 import 'package:flowr/flowr_mvvm.dart';
 import 'package:flowr/flowr_mvvm_support.dart';
 import 'package:flutter/material.dart';
@@ -78,6 +80,16 @@ class LifecycleCounterVM extends CounterVM {
   }
 }
 
+class SelfClosingCounterVM extends LifecycleCounterVM {
+  SelfClosingCounterVM(super.events);
+
+  @override
+  void dispose() {
+    unawaited(close());
+    super.dispose();
+  }
+}
+
 class MyChangNtfApp extends StatelessWidget {
   const MyChangNtfApp({super.key});
 
@@ -261,5 +273,52 @@ main() {
       expect(vm.isClosed, isTrue);
       expect(() => vm.addListener(() {}), throwsFlutterError);
     });
+
+    testWidgets('still disposes when the dispose hook throws', (tester) async {
+      late TrackedCounter counter;
+
+      await tester.pumpWidget(
+        FrProvider.listenable<TrackedCounter>(
+          (_) => counter = TrackedCounter(),
+          dispose: (_, _) => throw StateError('hook failed'),
+          child: Consumer<TrackedCounter>(
+            builder:
+                (_, value, _) =>
+                    Text('${value.count}', textDirection: TextDirection.ltr),
+          ),
+        ),
+      );
+
+      await tester.pumpWidget(const SizedBox());
+
+      expect(tester.takeException(), isA<StateError>());
+      expect(counter.disposeCalls, 1);
+      expect(() => counter.addListener(() {}), throwsFlutterError);
+    });
+
+    testWidgets('does not close an already self-closing FlowR twice', (
+      tester,
+    ) async {
+      late SelfClosingCounterVM vm;
+      final events = <String>[];
+
+      await tester.pumpWidget(
+        FrProvider.listenable<SelfClosingCounterVM>(
+          (_) => vm = SelfClosingCounterVM(events),
+          child: Consumer<SelfClosingCounterVM>(
+            builder:
+                (_, value, _) =>
+                    Text('${value.count}', textDirection: TextDirection.ltr),
+          ),
+        ),
+      );
+
+      await tester.pumpWidget(const SizedBox());
+      await tester.pump();
+
+      expect(vm.disposeCalls, 1);
+      expect(vm.closeCalls, 1);
+      expect(vm.isClosed, isTrue);
+    });
   });
 }

skills/flowr-usage/references/flowr-install.md

@@ -71,6 +71,8 @@ class CounterPage extends StatelessWidget {
   state is page-scoped.
 - Use `FrProvider.value` for an existing instance and `FrProvider.multi` when a
   subtree owns multiple view models.
+- Use `FrProvider.listenable` instead of `ChangeNotifierProvider` for a
+  `FrViewModel` mixed with `FrChangeNotifierMx`.
 - Use `FrViewModel<M>` for method-driven state and `FrBlocViewModel<E, M>` when
   callers should dispatch events with `add(event)`.
 

skills/flowr-usage/references/flutter.md

@@ -44,6 +44,9 @@ FrProvider(
 - `FrProvider` owns and disposes instances created by its factory. Use
   `FrProvider.value` only for an existing instance; use `FrProvider.multi` for
   several owned providers.
+- Use `FrProvider.listenable` for a `ChangeNotifier`, especially a
+  `FrViewModel` mixed with `FrChangeNotifierMx`; it disposes notifier listeners
+  and closes FlowR resources together.
 - Use `autoDisposeNotifier(notifier)` for an owned `ChangeNotifier`, such as a
   `FocusNode` or `TextEditingController`.
 - `FrView` rebuilds UI from state. `FrListener` handles side effects,

skills/fr-mvvm-contract/SKILL.md

@@ -318,7 +318,7 @@ where the root Provider creates `Dio`; new scaffolds use
 `factory Type(Dio dio)` constructor; base URL ownership belongs to
 `AppEnv.apiBaseUrl` and `createAppDio(AppEnv)`, never project skill config or a
 service annotation/constructor. Provide `AppEnvViewModel` through
-`ChangeNotifierProvider` with `FrChangeNotifierMx`, then key the Dio/business
+`FrProvider.listenable` with `FrChangeNotifierMx`, then key the Dio/business
 runtime subtree by environment identity so an environment update disposes the
 old Dio and business state. Clear installed persistent token/cookie stores
 before publishing that update. After first

skills/fr-mvvm-contract/assets/acdd_scaffold/lib/core/providers.dart.tmpl

@@ -15,12 +15,13 @@ class AppProviders extends StatelessWidget {
   final Dio? dio;
 
   @override
-  Widget build(BuildContext context) => ChangeNotifierProvider(
-    create: (context) => AppEnvViewModel(),
-    child: FrProvider.multi([
+  Widget build(BuildContext context) => FrProvider.multi(
+    [
+      FrProvider.listenable<AppEnvViewModel>((context) => AppEnvViewModel()),
       FrProvider((context) => AppLocaleViewModel()),
       FrProvider((context) => AppThemeViewModel()),
-    ], child: Consumer<AppEnvViewModel>(
+    ],
+    child: Consumer<AppEnvViewModel>(
       builder: (context, appEnvViewModel, child) => _AppEnvironmentScope(
         key: ValueKey(
           '${appEnvViewModel.state.env}|${appEnvViewModel.state.apiBaseUrl}',
@@ -30,7 +31,7 @@ class AppProviders extends StatelessWidget {
         child: child!,
       ),
       child: child,
-    )),
+    ),
   );
 }
 

skills/fr-mvvm-contract/references/acdd_scaffold.md

@@ -83,7 +83,7 @@ Do not make application launch part of the scaffold command.
   providers. `AppEnv.apiBaseUrl` is the single runtime base URL source and
   `createAppDio(AppEnv)` applies it with `BaseOptions`.
 - `AppEnvViewModel` mixes in `FrChangeNotifierMx` and is registered with
-  `ChangeNotifierProvider`. A `Consumer` keys the Dio/business runtime subtree
+  `FrProvider.listenable`. A `Consumer` keys the Dio/business runtime subtree
   by environment identity. Changing environment therefore disposes the old
   internally owned Dio, connections, and business ViewModels while preserving
   application-level Env, Locale, and Theme state. An externally injected test

skills/fr-mvvm-contract/scripts/tests/test_acdd_scaffold.py

@@ -212,7 +212,8 @@ def fake_runner(step: scaffold.CommandStep) -> None:
             self.assertIn("Dio createAppDio(AppEnv env)", interceptors_text)
             self.assertIn("BaseOptions(baseUrl: env.apiBaseUrl)", interceptors_text)
             self.assertIn("FrChangeNotifierMx<AppEnv>", env_text)
-            self.assertIn("ChangeNotifierProvider", providers_text)
+            self.assertIn("FrProvider.listenable<AppEnvViewModel>", providers_text)
+            self.assertNotIn("ChangeNotifierProvider", providers_text)
             self.assertIn("Consumer<AppEnvViewModel>", providers_text)
             self.assertIn("_AppEnvironmentScope", providers_text)
             self.assertIn("createAppDio(env)", providers_text)