flutter-ai-starter / rules

---
description: Provider package, ChangeNotifier ViewModels, and go_router integration
globs: ["lib/**/*.dart", "test/**/*.dart"]
alwaysApply: false
---

# State management (provider + ChangeNotifier)

Follow [Flutter's recommended architecture](https://docs.flutter.dev/app-architecture/recommendations): **ViewModels extend `ChangeNotifier`**, wired with **`package:provider`**.

## ViewModels

- One `ChangeNotifier` ViewModel per screen (or cohesive flow).
- File: `presentation/view_models/<feature>_view_model.dart`
- Class: `<Feature>ViewModel extends ChangeNotifier`
- Repositories injected via constructor — keep them **private**.
- Call `notifyListeners()` after state changes.
- Dispose resources in `@override void dispose()`.

## Async state in ViewModels

Model explicit UI state on the ViewModel:

```dart
// Option A: fields on ViewModel
bool isLoading = false;
String? errorMessage;
Data? data;

// Option B: sealed/freezed UI state union (preferred for complex screens)
```

After `await`, guard with a `_disposed` flag or cancel `CancelToken` in `dispose()` — **do not use `mounted` on ViewModels** (`mounted` is for widgets only).

```dart
bool _disposed = false;

@override
void dispose() {
  _disposed = true;
  super.dispose();
}

Future<void> load() async {
  final data = await _repository.fetch();
  if (_disposed) return;
  _data = data;
  notifyListeners();
}
```

## Where to provide ViewModels

| Scope | Where | Examples |
|---|---|---|
| App-wide | Root `app/dependencies.dart` | auth, theme, cart |
| Screen / flow | Route `builder` + `ChangeNotifierProvider` | home, checkout, settings |
| Ephemeral dialog | Local `Provider` above subtree | one-off modal, bottom sheet |

Root wiring in `app/dependencies.dart` (app-wide repos + global ViewModels only):

```dart
runApp(
  MultiProvider(
    providers: [
      Provider(create: (_) => supabaseClient),
      Provider(create: (ctx) => AuthRepository(client: ctx.read())),
      ChangeNotifierProvider(
        create: (ctx) => AuthViewModel(repository: ctx.read()),
      ),
    ],
    child: const MyApp(),
  ),
);
```

- Services/repos: `Provider` or `Provider<T>.value`
- ViewModels: `ChangeNotifierProvider`
- Screen-scoped ViewModels: route `builder`, not global root

## Views

- Use `context.watch<ViewModel>()` to rebuild on changes.
- Use `context.read<ViewModel>()` in callbacks (buttons, `initState`) — never `watch` in event handlers.
- Prefer `Selector` / `Consumer` to narrow rebuilds.
- Side effects (navigation, snackbars): listen in `initState` with `addListener`, or route from ViewModel via callback interface — not inside `build`.

## Navigation

- `context.go()` / `context.push()` via go_router — not `Navigator.push`.

## go_router + auth redirect

```dart
GoRouter(
  refreshListenable: authViewModel, // ChangeNotifier
  redirect: (context, state) {
    final auth = context.read<AuthViewModel>();
    return auth.isLoggedIn ? null : '/login';
  },
  routes: [/* ... */],
);
```

## Testing

- **Unit:** instantiate ViewModel with fake repositories; call methods; assert public state.
- **Listener (optional):** attach a listener to verify `notifyListeners` fired — not to assert business rules.
- **Widget:** wrap with `ChangeNotifierProvider.value(value: fakeViewModel)` or `MultiProvider` overrides.
- Do not require a full app widget tree for ViewModel unit tests.

## Forbidden

- `flutter_riverpod`, `riverpod_annotation`, `hooks_riverpod`, or any Riverpod API
- `GetX`, `GetIt`, or global service locators without ADR
- Views calling repositories directly
- `setState` for shared or persisted app state
- Static singleton ViewModels or repositories
- Business logic in widget `build()` methods