oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-mobile/variants/flutter/snippets.md

@@ -0,0 +1,1353 @@
+# Mobile Agent - Code Snippets (Flutter)
+
+Copy-paste ready patterns. Use these as starting points; adapt to the specific task.
+Always cache decoded domain entities at the Repository layer — never at the Dio transport layer.
+
+---
+
+## §1. pubspec.yaml Dependencies
+
+```yaml
+# pubspec.yaml
+name: my_app
+description: Flutter app with Clean Architecture + Riverpod + Drift offline-first cache.
+version: 1.0.0+1
+
+environment:
+  sdk: ">=3.10.0 <4.0.0"    # go_router 17 requires Dart >= 3.10
+  flutter: ">=3.44.0"
+
+dependencies:
+  flutter:
+    sdk: flutter
+
+  # State management
+  flutter_riverpod: ^3.3.0
+  riverpod_annotation: ^4.0.0
+
+  # Navigation
+  go_router: ^17.3.0
+
+  # HTTP client
+  dio: ^5.4.3+1
+  pretty_dio_logger: ^1.4.0   # debug builds only; wrap in kDebugMode guard
+
+  # Local storage — offline cache (system of record for server-owned data)
+  drift: ^2.34.0
+  sqlite3_flutter_libs: ^0.5.24
+  path_provider: ^2.1.3
+  path: ^1.9.0
+
+  # Secrets
+  flutter_secure_storage: ^9.2.2
+
+  # Lightweight preferences
+  shared_preferences: ^2.3.2
+
+  # Value types / equality (optional but recommended for domain entities)
+  freezed_annotation: ^3.1.0
+  json_annotation: ^4.9.0
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+
+  # Code generation
+  build_runner: ^2.4.11
+  riverpod_generator: ^4.0.0
+  drift_dev: ^2.34.0
+  go_router_builder: ^4.3.0
+  freezed: ^3.2.0
+  json_serializable: ^6.8.0
+
+  # Test mocking
+  mocktail: ^1.0.4
+
+  # Lint
+  flutter_lints: ^6.0.0
+```
+
+Run code generation after adding packages:
+
+```bash
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+```
+
+---
+
+## §2. GoRouter with Typed Routes
+
+```dart
+// lib/core/router/app_router.dart
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../features/todos/presentation/screens/todos_screen.dart';
+import '../../features/todos/presentation/screens/todo_detail_screen.dart';
+
+part 'app_router.g.dart';
+
+// ---------------------------------------------------------------------------
+// Typed route declarations — go_router_builder generates push()/go() helpers
+// ---------------------------------------------------------------------------
+
+@TypedGoRoute<TodosRoute>(
+  path: '/',
+  routes: [
+    TypedGoRoute<TodoDetailRoute>(path: 'todos/:id'),
+  ],
+)
+class TodosRoute extends GoRouteData with $TodosRoute {
+  const TodosRoute();
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      const TodosScreen();
+}
+
+class TodoDetailRoute extends GoRouteData with $TodoDetailRoute {
+  const TodoDetailRoute({required this.id});
+  final int id;
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      TodoDetailScreen(todoId: id);
+}
+
+// ---------------------------------------------------------------------------
+// Router provider — singleton, lives as long as the ProviderScope
+// ---------------------------------------------------------------------------
+
+@Riverpod(keepAlive: true)
+GoRouter appRouter(Ref ref) {
+  return GoRouter(
+    initialLocation: '/',
+    debugLogDiagnostics: true,
+    routes: $appRoutes,                         // generated list
+    redirect: (context, state) {
+      // Global auth guard example — replace with real auth state:
+      // final isAuthenticated = ref.read(authProvider).isAuthenticated;
+      // if (!isAuthenticated && state.matchedLocation != '/login') return '/login';
+      return null;
+    },
+  );
+}
+```
+
+Usage in a screen:
+
+```dart
+// Navigate to detail:
+TodoDetailRoute(id: todo.id).push(context);
+
+// Navigate replacing current:
+const TodosRoute().go(context);
+```
+
+---
+
+## §3. Domain Entity + Repository Interface + Offline-First Implementation
+
+### §3a. Domain Entity
+
+```dart
+// lib/features/todos/domain/todo.dart
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'todo.freezed.dart';
+
+/// Pure domain entity — no Drift, no Dio, no JSON annotations.
+/// Equality and copyWith are generated by freezed.
+/// Freezed 3 requires the class to be `abstract` (or `sealed`).
+@freezed
+abstract class Todo with _$Todo {
+  const factory Todo({
+    required int id,
+    required String title,
+    required bool completed,
+    required DateTime cachedAt,   // populated by the Repository when storing
+  }) = _Todo;
+}
+```
+
+### §3b. Repository Interface (domain layer)
+
+```dart
+// lib/features/todos/domain/todo_repository.dart
+import 'todo.dart';
+
+/// Abstract contract the presentation layer depends on.
+/// Concrete implementations (online, offline-first, stub) swap behind this seam.
+abstract interface class TodoRepository {
+  /// Emits a warm cached list immediately; cold loads await network and surface errors.
+  /// Callers never interact with Drift or Dio directly.
+  Stream<List<Todo>> watchAll();
+  /// Bypass TTL; complete only after the network result has been stored.
+  Future<void> refresh();
+
+  /// Returns the cached todo for [id] immediately (or null when absent),
+  /// revalidating from the network in the background only when it is stale.
+  /// A `Future` cannot re-emit — watchers of [watchAll] observe the refreshed
+  /// row via the Drift stream after a background revalidation completes.
+  Future<Todo?> findById(int id);
+
+  Future<Todo> create(String title);
+  Future<Todo> toggle(int id);
+  Future<void> delete(int id);
+}
+```
+
+### §3c. Drift Table + DAO (data layer — local cache)
+
+```dart
+// lib/core/database/app_database.dart
+import 'dart:io';
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+import 'package:path_provider/path_provider.dart';
+import 'package:path/path.dart' as p;
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../features/todos/data/local/todos_dao.dart';
+
+part 'app_database.g.dart';
+
+// ---------------------------------------------------------------------------
+// Todos cache table
+// ---------------------------------------------------------------------------
+
+/// One row per server-owned Todo. `cachedAt` drives TTL checks.
+class TodosTable extends Table {
+  IntColumn get id       => integer()();
+  TextColumn get title   => text()();
+  BoolColumn get completed => boolean().withDefault(const Constant(false))();
+  DateTimeColumn get cachedAt => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+@DriftDatabase(tables: [TodosTable], daos: [TodosDao])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase() : super(_openConnection());
+  AppDatabase.forTesting(super.executor);   // pass NativeDatabase.memory() in tests
+
+  @override
+  int get schemaVersion => 1;
+}
+
+LazyDatabase _openConnection() {
+  return LazyDatabase(() async {
+    final dir = await getApplicationDocumentsDirectory();
+    final file = File(p.join(dir.path, 'app.sqlite'));
+    return NativeDatabase.createInBackground(file);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// App-wide DB provider
+// ---------------------------------------------------------------------------
+
+@Riverpod(keepAlive: true)
+AppDatabase appDatabase(Ref ref) {
+  final db = AppDatabase();
+  ref.onDispose(db.close);
+  return db;
+}
+```
+
+```dart
+// lib/features/todos/data/local/todos_dao.dart
+import 'package:drift/drift.dart';
+import '../../../../core/database/app_database.dart';
+
+part 'todos_dao.g.dart';
+
+@DriftAccessor(tables: [TodosTable])
+class TodosDao extends DatabaseAccessor<AppDatabase> with _$TodosDaoMixin {
+  TodosDao(super.db);
+
+  /// Live stream — emits updated rows whenever Drift detects a change.
+  Stream<List<TodosTableData>> watchAll() => select(todosTable).watch();
+
+  /// Upsert a batch of rows (INSERT OR REPLACE). Additive only — does NOT
+  /// remove rows absent from [rows]. Use for seeding; use [replaceAll] to
+  /// mirror a full server list.
+  Future<void> upsertAll(List<TodosTableCompanion> rows) =>
+      batch((b) => b.insertAllOnConflictUpdate(todosTable, rows));
+
+  /// Replace the whole cached list with the fresh server set in ONE
+  /// transaction: delete rows the server no longer returns, then upsert the
+  /// rest. Without the delete step, server-side deletions linger as ghost
+  /// rows. `isNotIn([])` (empty fresh set) safely deletes all rows in Drift.
+  Future<void> replaceAll(List<TodosTableCompanion> rows) {
+    return transaction(() async {
+      final freshIds = rows.map((r) => r.id.value).toList();
+      await (delete(todosTable)..where((t) => t.id.isNotIn(freshIds))).go();
+      await batch((b) => b.insertAllOnConflictUpdate(todosTable, rows));
+    });
+  }
+
+  /// Upsert a single row after create/toggle.
+  Future<void> upsertOne(TodosTableCompanion row) =>
+      into(todosTable).insertOnConflictUpdate(row);
+
+  Future<void> deleteById(int id) =>
+      (delete(todosTable)..where((t) => t.id.equals(id))).go();
+
+  Future<TodosTableData?> findById(int id) =>
+      (select(todosTable)..where((t) => t.id.equals(id))).getSingleOrNull();
+}
+```
+
+### §3d. Remote Data Source (data layer — Dio calls)
+
+```dart
+// lib/features/todos/data/remote/todos_remote_data_source.dart
+import 'package:dio/dio.dart';
+import '../dtos/todo_dto.dart';
+
+/// All Dio calls for the /todos resource.
+/// No caching here — transport concerns only.
+class TodosRemoteDataSource {
+  TodosRemoteDataSource(this._dio);
+  final Dio _dio;
+
+  Future<List<TodoDto>> fetchAll() async {
+    final response = await _dio.get<List<dynamic>>('/todos');
+    return (response.data ?? [])
+        .map((json) => TodoDto.fromJson(json as Map<String, dynamic>))
+        .toList();
+  }
+
+  Future<TodoDto> fetchById(int id) async {
+    final response = await _dio.get<Map<String, dynamic>>('/todos/$id');
+    return TodoDto.fromJson(response.data!);
+  }
+
+  Future<TodoDto> create(String title) async {
+    final response = await _dio.post<Map<String, dynamic>>(
+      '/todos',
+      data: {'title': title},
+    );
+    return TodoDto.fromJson(response.data!);
+  }
+
+  Future<TodoDto> toggle(int id) async {
+    final response = await _dio.patch<Map<String, dynamic>>('/todos/$id/toggle');
+    return TodoDto.fromJson(response.data!);
+  }
+
+  Future<void> delete(int id) => _dio.delete<void>('/todos/$id');
+}
+```
+
+```dart
+// lib/features/todos/data/dtos/todo_dto.dart
+import 'package:json_annotation/json_annotation.dart';
+import '../../domain/todo.dart';
+
+part 'todo_dto.g.dart';
+
+/// JSON transfer object. Isolated from the domain entity.
+@JsonSerializable()
+class TodoDto {
+  const TodoDto({
+    required this.id,
+    required this.title,
+    required this.completed,
+  });
+
+  final int id;
+  final String title;
+  final bool completed;
+
+  factory TodoDto.fromJson(Map<String, dynamic> json) => _$TodoDtoFromJson(json);
+  Map<String, dynamic> toJson() => _$TodoDtoToJson(this);
+
+  /// Map to domain entity; `cachedAt` is set by the Repository, not the DTO.
+  Todo toDomain({required DateTime cachedAt}) => Todo(
+        id: id,
+        title: title,
+        completed: completed,
+        cachedAt: cachedAt,
+      );
+}
+```
+
+### §3e. Offline-First Repository Implementation (data layer)
+
+```dart
+// lib/features/todos/data/todo_repository_impl.dart
+import 'package:dio/dio.dart';
+import 'package:drift/drift.dart';
+import '../../../core/database/app_database.dart';
+import '../domain/todo.dart';
+import '../domain/todo_repository.dart';
+import 'dtos/todo_dto.dart';
+import 'local/todos_dao.dart';
+import 'remote/todos_remote_data_source.dart';
+
+/// TTL for the todos list cache. Revalidate if the newest row is older than this.
+const _kCacheTtl = Duration(minutes: 5);
+
+/// Offline-first implementation of [TodoRepository].
+///
+/// Caching contract:
+///   - [watchAll] maps a warm Drift stream to domain entities immediately.
+///     A background revalidation triggers whenever the cache is stale (> TTL)
+///     when warm; a cold cache waits for the network and surfaces failure. Drift re-emits after writes.
+///   - Writes ([create], [toggle], [delete]) hit the network first, then upsert
+///     or delete the local Drift row so the stream emits the change instantly.
+///   - Cache key = logical operation, never URLs. TTL is explicit; no infinite cache.
+///   - Secrets and user-authored data are NOT stored here — use flutter_secure_storage
+///     or a separate Drift table with a different retention policy.
+///
+/// Note: staleness is evaluated at subscription time only. A long-lived
+/// subscription revalidates when it is (re-)subscribed — e.g. on app
+/// foreground or a `ref.invalidate` — not continuously while open. Drive
+/// periodic refresh from the presentation layer (pull-to-refresh, an
+/// app-lifecycle listener) if you need it while a screen stays mounted.
+class TodoRepositoryImpl implements TodoRepository {
+  TodoRepositoryImpl({
+    required TodosDao dao,
+    required TodosRemoteDataSource remote,
+  })  : _dao = dao,
+        _remote = remote;
+
+  final TodosDao _dao;
+  final TodosRemoteDataSource _remote;
+
+  // ---------------------------------------------------------------------------
+  // READ — stale-while-revalidate
+  // ---------------------------------------------------------------------------
+
+  @override
+  Stream<List<Todo>> watchAll() async* {
+    final snapshot = await _dao.watchAll().first;
+    final now = DateTime.now();
+    if (snapshot.isEmpty) {
+      // Cold-cache failures must reach Riverpod's error state.
+      await refresh();
+    } else if (snapshot.any((row) => now.difference(row.cachedAt) > _kCacheTtl)) {
+      // Only warm-cache revalidation may degrade to the stale value.
+      refresh().ignore();
+    }
+    yield* _dao.watchAll().map((rows) => rows.map(_rowToEntity).toList());
+  }
+
+  @override
+  Future<void> refresh() => _revalidate();
+
+  @override
+  Future<Todo?> findById(int id) async {
+    final cached = await _dao.findById(id);
+    final now = DateTime.now();
+
+    if (cached != null) {
+      // Serve the cached row immediately. Revalidate in the background only
+      // when it is stale; watchers of watchAll() pick up the refreshed row via
+      // the Drift stream. This Future returns the cached snapshot as-is.
+      if (now.difference(cached.cachedAt) > _kCacheTtl) {
+        _revalidateById(id, now).ignore();
+      }
+      return _rowToEntity(cached);
+    }
+
+    // Cache miss — fetch from network and persist.
+    try {
+      final dto = await _remote.fetchById(id);
+      await _dao.upsertOne(_dtoToCompanion(dto, cachedAt: now));
+      return dto.toDomain(cachedAt: now);
+    } on DioException catch (e) {
+      if (e.response?.statusCode == 404) return null;
+      rethrow;
+    }
+  }
+
+  Future<void> _revalidate() async {
+    final dtos = await _remote.fetchAll();
+    final now = DateTime.now();
+    await _dao.replaceAll(
+      dtos.map((dto) => _dtoToCompanion(dto, cachedAt: now)).toList(),
+    );
+  }
+
+  Future<void> _revalidateById(int id, DateTime now) async {
+    try {
+      final dto = await _remote.fetchById(id);
+      await _dao.upsertOne(_dtoToCompanion(dto, cachedAt: now));
+    } catch (_) {
+      // Non-fatal — caller already received the cached value.
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // WRITE — invalidate/update cache after success
+  // ---------------------------------------------------------------------------
+
+  @override
+  Future<Todo> create(String title) async {
+    final dto = await _remote.create(title);
+    final now = DateTime.now();
+    // Upsert the new row so watchAll() emits without waiting for a revalidation.
+    await _dao.upsertOne(_dtoToCompanion(dto, cachedAt: now));
+    return dto.toDomain(cachedAt: now);
+  }
+
+  @override
+  Future<Todo> toggle(int id) async {
+    final dto = await _remote.toggle(id);
+    final now = DateTime.now();
+    await _dao.upsertOne(_dtoToCompanion(dto, cachedAt: now));
+    return dto.toDomain(cachedAt: now);
+  }
+
+  @override
+  Future<void> delete(int id) async {
+    await _remote.delete(id);
+    // Remove the row so the stream emits the deletion immediately.
+    await _dao.deleteById(id);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+
+  Todo _rowToEntity(TodosTableData row) => Todo(
+        id: row.id,
+        title: row.title,
+        completed: row.completed,
+        cachedAt: row.cachedAt,
+      );
+
+  TodosTableCompanion _dtoToCompanion(TodoDto dto, {required DateTime cachedAt}) =>
+      TodosTableCompanion(
+        id: Value(dto.id),
+        title: Value(dto.title),
+        completed: Value(dto.completed),
+        cachedAt: Value(cachedAt),
+      );
+}
+```
+
+---
+
+## §4. Riverpod StreamNotifier Consuming the Repository Stream
+
+```dart
+// lib/features/todos/presentation/providers/todos_provider.dart
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import '../../domain/todo.dart';
+import '../../domain/todo_repository.dart';
+import '../../../../core/di/providers.dart';   // todoRepositoryProvider
+
+part 'todos_provider.g.dart';
+
+/// Exposes the offline-first todo list.
+///
+/// Riverpod converts the Repository's Stream into AsyncValue<List<Todo>>.
+/// The UI receives AsyncValue.loading() on first subscription, then
+/// AsyncValue.data(cachedList) on the first Drift emission, then
+/// AsyncValue.data(freshList) after network revalidation — without any
+/// loading flicker if the cache is warm.
+@riverpod
+class TodosNotifier extends _$TodosNotifier {
+  @override
+  Stream<List<Todo>> build() {
+    final repo = ref.watch(todoRepositoryProvider);
+    return repo.watchAll();
+  }
+
+  Future<void> create(String title) async {
+    final repo = ref.read(todoRepositoryProvider);
+    await repo.create(title);
+    // Stream auto-updates via Drift; no manual state mutation needed.
+  }
+
+  Future<void> toggle(int id) async {
+    final repo = ref.read(todoRepositoryProvider);
+    await repo.toggle(id);
+  }
+
+  Future<void> delete(int id) async {
+    final repo = ref.read(todoRepositoryProvider);
+    await repo.delete(id);
+  }
+}
+```
+
+```dart
+// lib/core/di/providers.dart
+import 'package:dio/dio.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../database/app_database.dart';
+import '../network/dio_client.dart';
+import '../../features/todos/data/local/todos_dao.dart';
+import '../../features/todos/data/remote/todos_remote_data_source.dart';
+import '../../features/todos/data/todo_repository_impl.dart';
+import '../../features/todos/domain/todo_repository.dart';
+
+part 'providers.g.dart';
+
+@Riverpod(keepAlive: true)
+Dio dio(Ref ref) => buildDioClient(ref);
+
+@Riverpod(keepAlive: true)
+TodosDao todosDao(Ref ref) {
+  final db = ref.watch(appDatabaseProvider);
+  return db.todosDao;
+}
+
+@Riverpod(keepAlive: true)
+TodosRemoteDataSource todosRemoteDataSource(Ref ref) =>
+    TodosRemoteDataSource(ref.watch(dioProvider));
+
+@Riverpod(keepAlive: true)
+TodoRepository todoRepository(Ref ref) => TodoRepositoryImpl(
+      dao: ref.watch(todosDaoProvider),
+      remote: ref.watch(todosRemoteDataSourceProvider),
+    );
+```
+
+---
+
+## §5. Dio Client with Auth + Retry + Logging Interceptors
+
+```dart
+// lib/core/network/dio_client.dart
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:pretty_dio_logger/pretty_dio_logger.dart';
+
+/// Builds the app-wide Dio instance with interceptors.
+/// Called once from the DI layer; never instantiated in features directly.
+Dio buildDioClient(Ref ref) {
+  final dio = Dio(
+    BaseOptions(
+      baseUrl: const String.fromEnvironment(
+        'API_BASE_URL',
+        defaultValue: 'https://api.example.com',
+      ),
+      connectTimeout: const Duration(seconds: 15),
+      receiveTimeout: const Duration(seconds: 30),
+      headers: {'Content-Type': 'application/json'},
+    ),
+  );
+
+  // Transport-layer interceptors only — no caching here.
+  dio.interceptors.addAll([
+    AuthInterceptor(const FlutterSecureStorage()),
+    RetryInterceptor(dio),
+    if (kDebugMode) PrettyDioLogger(requestBody: true, responseBody: true),
+  ]);
+
+  return dio;
+}
+
+// ---------------------------------------------------------------------------
+// Auth interceptor — injects Bearer token from secure storage
+// ---------------------------------------------------------------------------
+
+class AuthInterceptor extends Interceptor {
+  AuthInterceptor(this._storage);
+  final FlutterSecureStorage _storage;
+
+  @override
+  Future<void> onRequest(
+    RequestOptions options,
+    RequestInterceptorHandler handler,
+  ) async {
+    final token = await _storage.read(key: 'access_token');
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    handler.next(options);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    if (err.response?.statusCode == 401) {
+      // TODO: trigger token refresh or sign-out flow via ref
+      // For now, pass the error through to the caller.
+    }
+    handler.next(err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Retry interceptor — exponential back-off on transient failures
+// ---------------------------------------------------------------------------
+
+class RetryInterceptor extends Interceptor {
+  RetryInterceptor(this._dio, {this.maxRetries = 3});
+  final Dio _dio;
+  final int maxRetries;
+
+  @override
+  Future<void> onError(
+    DioException err,
+    ErrorInterceptorHandler handler,
+  ) async {
+    final attempt = err.requestOptions.extra['_retryCount'] as int? ?? 0;
+
+    // Only retry idempotent methods. Retrying a POST on receiveTimeout can
+    // duplicate a non-idempotent write (the server may have applied the first
+    // request before the response timed out).
+    const idempotentMethods = {'GET', 'HEAD', 'PUT', 'DELETE'};
+    final isIdempotent =
+        idempotentMethods.contains(err.requestOptions.method.toUpperCase());
+    final isRetriable = isIdempotent &&
+        (err.type == DioExceptionType.connectionTimeout ||
+            err.type == DioExceptionType.receiveTimeout ||
+            err.type == DioExceptionType.connectionError);
+
+    if (isRetriable && attempt < maxRetries) {
+      await Future.delayed(Duration(milliseconds: 200 * (1 << attempt)));
+      try {
+        final opts = err.requestOptions
+          ..extra['_retryCount'] = attempt + 1;
+        final response = await _dio.fetch<dynamic>(opts);
+        handler.resolve(response);
+        return;
+      } catch (_) {
+        // Fall through to next handler on retry failure.
+      }
+    }
+    handler.next(err);
+  }
+}
+```
+
+---
+
+## §6. Todos Screen (ConsumerStatefulWidget)
+
+```dart
+// lib/features/todos/presentation/screens/todos_screen.dart
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import '../../domain/todo.dart';
+import '../providers/todos_provider.dart';
+import '../widgets/todo_list_item.dart';
+import '../../../../shared/widgets/empty_state.dart';
+import '../../../../shared/widgets/error_view.dart';
+
+class TodosScreen extends ConsumerStatefulWidget {
+  const TodosScreen({super.key});
+
+  @override
+  ConsumerState<TodosScreen> createState() => _TodosScreenState();
+}
+
+class _TodosScreenState extends ConsumerState<TodosScreen> {
+  final _titleController = TextEditingController();
+
+  @override
+  void dispose() {
+    _titleController.dispose();   // always dispose controllers
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final todosAsync = ref.watch(todosNotifierProvider);
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Todos'),
+        actions: [
+          IconButton(
+            icon: const Icon(Icons.refresh),
+            tooltip: 'Refresh',
+            onPressed: () async {
+              try {
+                await ref.read(todoRepositoryProvider).refresh();
+              } catch (error) {
+                if (!context.mounted) return;
+                ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Refresh failed: $error')));
+              }
+            },
+          ),
+        ],
+      ),
+      body: todosAsync.when(
+        // Warm cache is available — render immediately, no spinner.
+        // Riverpod passes skipLoadingOnRefresh: true by default in Riverpod 3.x
+        // so a background revalidation does not re-show the loading state.
+        data: (todos) => todos.isEmpty
+            ? const EmptyState(
+                icon: Icons.check_circle_outline,
+                title: 'No todos yet',
+                subtitle: 'Add your first todo below.',
+              )
+            : _TodoList(todos: todos),
+        loading: () => const Center(child: CircularProgressIndicator()),
+        error: (err, _) => ErrorView(
+          message: err.toString(),
+          onRetry: () => ref.invalidate(todosNotifierProvider),
+        ),
+      ),
+      floatingActionButton: FloatingActionButton(
+        onPressed: _showAddDialog,
+        tooltip: 'Add todo',
+        child: const Icon(Icons.add),
+      ),
+    );
+  }
+
+  void _showAddDialog() {
+    _titleController.clear();
+    showDialog<void>(
+      context: context,
+      builder: (ctx) => AlertDialog(
+        title: const Text('New Todo'),
+        content: TextField(
+          controller: _titleController,
+          autofocus: true,
+          decoration: const InputDecoration(
+            labelText: 'Title',
+            hintText: 'What needs to be done?',
+          ),
+          onSubmitted: (_) => _submitAdd(ctx),
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.of(ctx).pop(),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            onPressed: () => _submitAdd(ctx),
+            child: const Text('Add'),
+          ),
+        ],
+      ),
+    );
+  }
+
+  Future<void> _submitAdd(BuildContext dialogCtx) async {
+    final title = _titleController.text.trim();
+    if (title.isEmpty) return;
+    Navigator.of(dialogCtx).pop();
+    await ref.read(todosNotifierProvider.notifier).create(title);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal list widget
+// ---------------------------------------------------------------------------
+
+class _TodoList extends ConsumerWidget {
+  const _TodoList({required this.todos});
+  final List<Todo> todos;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    return RefreshIndicator(
+      onRefresh: () async {
+        try {
+          await ref.read(todoRepositoryProvider).refresh();
+        } catch (error) {
+          if (!context.mounted) return;
+          ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Refresh failed: $error')));
+        }
+      },
+      child: ListView.builder(
+        itemCount: todos.length,
+        itemBuilder: (ctx, i) => TodoListItem(
+          todo: todos[i],
+          onToggle: () =>
+              ref.read(todosNotifierProvider.notifier).toggle(todos[i].id),
+          onDelete: () =>
+              ref.read(todosNotifierProvider.notifier).delete(todos[i].id),
+        ),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## §7. Shared Widgets (EmptyState, ErrorView, TodoListItem)
+
+```dart
+// lib/shared/widgets/empty_state.dart
+import 'package:flutter/material.dart';
+
+class EmptyState extends StatelessWidget {
+  const EmptyState({
+    super.key,
+    required this.icon,
+    required this.title,
+    this.subtitle,
+  });
+
+  final IconData icon;
+  final String title;
+  final String? subtitle;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.all(32),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(icon, size: 64, color: theme.colorScheme.secondary),
+            const SizedBox(height: 16),
+            Text(title, style: theme.textTheme.titleLarge),
+            if (subtitle != null) ...[
+              const SizedBox(height: 8),
+              Text(
+                subtitle!,
+                style: theme.textTheme.bodyMedium?.copyWith(
+                  color: theme.colorScheme.onSurface.withValues(alpha: 0.6),
+                ),
+                textAlign: TextAlign.center,
+              ),
+            ],
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+```dart
+// lib/shared/widgets/error_view.dart
+import 'package:flutter/material.dart';
+
+class ErrorView extends StatelessWidget {
+  const ErrorView({super.key, required this.message, this.onRetry});
+
+  final String message;
+  final VoidCallback? onRetry;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.all(24),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(Icons.error_outline, size: 64, color: theme.colorScheme.error),
+            const SizedBox(height: 16),
+            Text(
+              'Something went wrong',
+              style: theme.textTheme.titleLarge,
+              textAlign: TextAlign.center,
+            ),
+            const SizedBox(height: 8),
+            Text(
+              message,
+              style: theme.textTheme.bodyMedium?.copyWith(
+                color: theme.colorScheme.onSurface.withValues(alpha: 0.6),
+              ),
+              textAlign: TextAlign.center,
+            ),
+            if (onRetry != null) ...[
+              const SizedBox(height: 24),
+              FilledButton.icon(
+                onPressed: onRetry,
+                icon: const Icon(Icons.refresh),
+                label: const Text('Try Again'),
+              ),
+            ],
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+```dart
+// lib/features/todos/presentation/widgets/todo_list_item.dart
+import 'package:flutter/material.dart';
+import '../../domain/todo.dart';
+
+class TodoListItem extends StatelessWidget {
+  const TodoListItem({
+    super.key,
+    required this.todo,
+    required this.onToggle,
+    required this.onDelete,
+  });
+
+  final Todo todo;
+  final VoidCallback onToggle;
+  final VoidCallback onDelete;
+
+  @override
+  Widget build(BuildContext context) {
+    return ListTile(
+      leading: Checkbox(
+        value: todo.completed,
+        onChanged: (_) => onToggle(),
+      ),
+      title: Text(
+        todo.title,
+        style: todo.completed
+            ? TextStyle(
+                decoration: TextDecoration.lineThrough,
+                color: Theme.of(context).colorScheme.onSurface.withValues(alpha: 0.5),
+              )
+            : null,
+      ),
+      trailing: IconButton(
+        icon: const Icon(Icons.delete_outline),
+        tooltip: 'Delete',
+        onPressed: onDelete,
+      ),
+    );
+  }
+}
+```
+
+---
+
+## §8. App Entry Point (main.dart)
+
+```dart
+// lib/main.dart
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'core/router/app_router.dart';
+import 'core/theme/app_theme.dart';
+
+void main() {
+  WidgetsFlutterBinding.ensureInitialized();
+  runApp(
+    // ProviderScope is the Riverpod root — must wrap the entire widget tree.
+    const ProviderScope(child: MyApp()),
+  );
+}
+
+class MyApp extends ConsumerWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final router = ref.watch(appRouterProvider);
+
+    return MaterialApp.router(
+      title: 'My App',
+      theme: AppTheme.light(),
+      darkTheme: AppTheme.dark(),
+      routerConfig: router,
+      debugShowCheckedModeBanner: false,
+    );
+  }
+}
+```
+
+```dart
+// lib/core/theme/app_theme.dart
+import 'package:flutter/material.dart';
+
+/// Material 3 light/dark themes seeded from a single brand color.
+/// Kept intentionally small — extend with typography/component themes per project.
+abstract final class AppTheme {
+  static const _seed = Color(0xFF1A2332);   // Deep Ocean Navy
+
+  static ThemeData light() => _base(Brightness.light);
+  static ThemeData dark() => _base(Brightness.dark);
+
+  static ThemeData _base(Brightness brightness) {
+    final scheme = ColorScheme.fromSeed(
+      seedColor: _seed,
+      brightness: brightness,
+    );
+    return ThemeData(
+      useMaterial3: true,
+      colorScheme: scheme,
+      scaffoldBackgroundColor: scheme.surface,
+      appBarTheme: AppBarTheme(
+        backgroundColor: scheme.surface,
+        foregroundColor: scheme.onSurface,
+        centerTitle: false,
+      ),
+    );
+  }
+}
+```
+
+---
+
+## §9. flutter_test + mocktail Unit Tests
+
+```dart
+// test/features/todos/todos_provider_test.dart
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:my_app/features/todos/domain/todo.dart';
+import 'package:my_app/features/todos/domain/todo_repository.dart';
+import 'package:my_app/features/todos/presentation/providers/todos_provider.dart';
+import 'package:my_app/core/di/providers.dart';
+
+// ---------------------------------------------------------------------------
+// Mock — depends on the abstract repository interface, not the Dio/Drift impl
+// ---------------------------------------------------------------------------
+
+class MockTodoRepository extends Mock implements TodoRepository {}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+final _now = DateTime(2025, 1, 1);
+
+Todo _makeTodo(int id, {bool completed = false}) => Todo(
+      id: id,
+      title: 'Todo $id',
+      completed: completed,
+      cachedAt: _now,
+    );
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+void main() {
+  late MockTodoRepository mockRepo;
+  late ProviderContainer container;
+
+  setUp(() {
+    mockRepo = MockTodoRepository();
+    container = ProviderContainer(
+      overrides: [
+        // Swap the real repository for the mock at the DI seam.
+        todoRepositoryProvider.overrideWithValue(mockRepo),
+      ],
+    );
+    addTearDown(container.dispose);
+  });
+
+  test('todosNotifierProvider emits data from repository stream', () async {
+    final todos = [_makeTodo(1), _makeTodo(2)];
+    when(() => mockRepo.watchAll()).thenAnswer(
+      (_) => Stream.value(todos),
+    );
+
+    // Wait for the async stream to emit.
+    final result = await container
+        .read(todosNotifierProvider.future);
+
+    expect(result, equals(todos));
+  });
+
+  test('todosNotifierProvider emits empty list when repository returns []', () async {
+    when(() => mockRepo.watchAll()).thenAnswer((_) => Stream.value([]));
+
+    final result = await container.read(todosNotifierProvider.future);
+
+    expect(result, isEmpty);
+  });
+
+  test('todosNotifierProvider propagates repository errors', () async {
+    when(() => mockRepo.watchAll())
+        .thenAnswer((_) => Stream.error(Exception('network error')));
+
+    await expectLater(
+      container.read(todosNotifierProvider.future),
+      throwsA(isA<Exception>()),
+    );
+  });
+
+  test('create calls repository and stream auto-updates', () async {
+    final initial = [_makeTodo(1)];
+    final afterCreate = [_makeTodo(1), _makeTodo(2, completed: false)];
+    var streamIndex = 0;
+    final streams = [Stream.value(initial), Stream.value(afterCreate)];
+
+    when(() => mockRepo.watchAll())
+        .thenAnswer((_) => streams[streamIndex++ % streams.length]);
+    when(() => mockRepo.create(any()))
+        .thenAnswer((_) async => _makeTodo(2));
+
+    await container.read(todosNotifierProvider.notifier).create('Todo 2');
+
+    verify(() => mockRepo.create('Todo 2')).called(1);
+  });
+}
+```
+
+```dart
+// test/features/todos/todo_repository_impl_test.dart
+// Tests the real TodoRepositoryImpl with an in-memory Drift database.
+import 'dart:async';
+
+import 'package:drift/drift.dart' show Value;   // Value: drift/native.dart does not export it
+import 'package:drift/native.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:my_app/core/database/app_database.dart';
+import 'package:my_app/features/todos/data/dtos/todo_dto.dart';
+import 'package:my_app/features/todos/data/local/todos_dao.dart';
+import 'package:my_app/features/todos/data/remote/todos_remote_data_source.dart';
+import 'package:my_app/features/todos/data/todo_repository_impl.dart';
+
+class MockTodosRemoteDataSource extends Mock implements TodosRemoteDataSource {}
+
+void main() {
+  late AppDatabase db;
+  late TodosDao dao;
+  late MockTodosRemoteDataSource mockRemote;
+  late TodoRepositoryImpl repo;
+
+  setUp(() {
+    db = AppDatabase.forTesting(NativeDatabase.memory());
+    dao = db.todosDao;
+    mockRemote = MockTodosRemoteDataSource();
+    repo = TodoRepositoryImpl(dao: dao, remote: mockRemote);
+  });
+
+  tearDown(() => db.close());
+
+  test('watchAll emits cached rows immediately then revalidates', () async {
+    final now = DateTime.now();
+    // Pre-populate the cache with a stale entry.
+    // `.insert()` takes RAW values for required columns (id, title, cachedAt)
+    // and Value() only for defaulted/nullable ones (completed).
+    await dao.upsertAll([
+      TodosTableCompanion.insert(
+        id: 1,
+        title: 'Cached todo',
+        cachedAt: now.subtract(const Duration(hours: 1)),  // older than TTL
+        completed: const Value(false),
+      ),
+    ]);
+
+    // Gate the remote fetch behind a Completer so revalidation cannot race
+    // ahead of the first (cached) emission. Without the gate, if the upsert
+    // lands before the stream is subscribed, both emissions coalesce into one
+    // and `.take(2)` hangs. The test releases the gate after emission #1,
+    // guaranteeing two distinct emissions deterministically.
+    final gate = Completer<void>();
+    final freshDtos = [
+      TodoDto(id: 1, title: 'Fresh todo', completed: false),
+    ];
+    when(() => mockRemote.fetchAll()).thenAnswer((_) async {
+      await gate.future;
+      return freshDtos;
+    });
+
+    final emissions = <int>[];
+    await for (final todos in repo.watchAll().take(2)) {
+      emissions.add(todos.length);
+      if (emissions.length == 1) {
+        gate.complete();   // cached emission seen — now let revalidation run
+      }
+    }
+
+    // First emission: cached row; second: after revalidation.
+    expect(emissions, [1, 1]);
+    verify(() => mockRemote.fetchAll()).called(1);
+  });
+
+  test('cold-cache network failure reaches the stream error state', () async {
+    when(() => mockRemote.fetchAll()).thenThrow(Exception('offline'));
+    await expectLater(repo.watchAll().first, throwsA(isA<Exception>()));
+  });
+
+  test('manual refresh bypasses a warm TTL and awaits the fresh write', () async {
+    await dao.upsertAll([
+      TodosTableCompanion.insert(id: 1, title: 'Cached', cachedAt: DateTime.now()),
+    ]);
+    final started = Completer<void>();
+    final release = Completer<void>();
+    when(() => mockRemote.fetchAll()).thenAnswer((_) async {
+      started.complete();
+      await release.future;
+      return [TodoDto(id: 1, title: 'Fresh', completed: false)];
+    });
+    var completed = false;
+    final refreshing = repo.refresh().then((_) => completed = true);
+    await started.future;
+    expect(completed, isFalse);
+    release.complete();
+    await refreshing;
+    expect((await dao.watchAll().first).single.title, 'Fresh');
+    verify(() => mockRemote.fetchAll()).called(1);
+  });
+
+  test('create upserts into Drift and stream emits new item', () async {
+    when(() => mockRemote.create(any()))
+        .thenAnswer((_) async => TodoDto(id: 99, title: 'New', completed: false));
+
+    await repo.create('New');
+
+    final rows = await dao.watchAll().first;
+    expect(rows.any((r) => r.id == 99), isTrue);
+  });
+
+  test('delete removes row from Drift after remote success', () async {
+    final now = DateTime.now();
+    await dao.upsertAll([
+      TodosTableCompanion.insert(
+        id: 5,
+        title: 'To delete',
+        cachedAt: now,
+        completed: const Value(false),
+      ),
+    ]);
+    when(() => mockRemote.delete(5)).thenAnswer((_) async {});
+
+    await repo.delete(5);
+
+    final rows = await dao.watchAll().first;
+    expect(rows.any((r) => r.id == 5), isFalse);
+  });
+}
+```
+
+---
+
+## §10. Cache Rules Recap
+
+> These rules are mandatory. Violating any of them is a defect, not a style choice.
+
+1. **Repository layer, not transport.** Cache decoded `Todo` domain entities inside `TodoRepositoryImpl`. Do NOT use a Dio interceptor (e.g. `dio_http_cache`, `dio_cache_interceptor`) as the system of record for domain reads — interceptors operate on raw bytes and are invisible to the domain and its tests.
+2. **Stale-while-revalidate.** `watchAll()` emits the locally-cached Drift rows immediately (zero latency for the user), then silently revalidates from the network and re-emits via the Drift stream. No loading spinner on cache hits.
+3. **Explicit TTL.** Every cache row stores `cachedAt`. The Repository compares it against `_kCacheTtl` to decide whether to revalidate. Never use an implicit or infinite TTL.
+4. **Key = operation + params, never URLs.** The Drift table primary key (`id`) and the DAO operation name (e.g., `watchAll`, `findById`) are the effective cache keys. Changing the backend URL does not invalidate the cache; only writing new data or deleting rows does.
+5. **Invalidate on write.** `create` → upsert new row. `toggle` → upsert updated row. `delete` → delete row. After each mutation the Drift stream emits the new state to all active subscribers without any explicit refresh call in the UI.
+6. **Boundaries.** The Drift cache table is for transient server-owned data. Durable user-authored data (drafts, settings) → separate Drift table with its own retention policy. Secrets (tokens) → `flutter_secure_storage`. Do not use the cache table as a system of record.
+
+---
+
+## §11. Maestro E2E Flow
+
+<!-- oma-docs:ignore-start -->
+End-to-end UI test driven by Maestro. Lives at `maestro/todos_flow.yaml` (project
+root, see tech-stack `Testing`). Run with `maestro test maestro/todos_flow.yaml`.
+<!-- oma-docs:ignore-end -->
+
+```yaml
+# maestro/todos_flow.yaml
+# Launch → assert list screen → add a todo → assert it appears.
+appId: com.example.my_app
+---
+- launchApp:
+    clearState: true
+- assertVisible: "Todos"          # AppBar title confirms the list screen loaded
+- tapOn: "Add todo"               # matches the FAB tooltip/accessibility label
+- assertVisible: "New Todo"       # add dialog opened
+- tapOn: "Title"                  # focus the text field
+- inputText: "Buy milk"
+- tapOn: "Add"                    # FilledButton submits the dialog
+- assertVisible: "Buy milk"       # new item rendered in the list
+```
+
+Use text selectors for the tooltip/accessibility label above. The `id` selector
+requires an actual `Semantics(identifier: ...)`; a tooltip is not a resource ID.