### Installation Bundle Setup

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Configures the installation prefix and ensures a clean build bundle directory. This sets up the structure for creating a relocatable application bundle.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

--------------------------------

### Install Executable Target

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Installs the main application executable to the runtime destination. Marked with the 'Runtime' component.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)
```

--------------------------------

### Install Dependencies

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/README.md

Run this command in your project's root directory to install all necessary Flutter dependencies.

```bash
flutter pub get
```

--------------------------------

### Install Flutter Library

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Installs the Flutter library file to the root of the bundle directory. Marked with the 'Runtime' component.

```cmake
install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Installation Directory Configuration

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Configures installation directories for the application bundle. Support files are placed next to the executable for in-place running.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")
```

--------------------------------

### Install Bundled Plugin Libraries

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Installs any bundled plugin libraries to the root of the bundle directory. Marked with the 'Runtime' component.

```cmake
if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Basic CMake Project Setup

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Initializes CMake version and project name. Sets the executable name and application ID. Use this to define the fundamental project parameters.

```cmake
cmake_minimum_required(VERSION 3.10)
project(runner LANGUAGES CXX)

set(BINARY_NAME "flutter_mvvm_riverpod")
set(APPLICATION_ID "com.henry.flutter_mvvm_riverpod")

cmake_policy(SET CMP0063 NEW)

set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
```

--------------------------------

### Install AOT Library

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compiled library to the data directory, but only for Profile and Release build configurations.

```cmake
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Install Native Assets

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Installs native assets provided by build.dart from all packages to the root of the bundle directory. Marked with the 'Runtime' component.

```cmake
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/windows/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

--------------------------------

### Installing Application Components

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Installs the application executable, ICU data, Flutter library, and bundled plugin libraries to the specified bundle directories. This ensures all necessary files are included in the final application package.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Project and CMake Version Setup

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Sets the minimum required CMake version and project name. Ensures compatibility with modern CMake features.

```cmake
cmake_minimum_required(VERSION 3.14)
project(flutter_mvvm_riverpod LANGUAGES CXX)
```

--------------------------------

### Install Flutter Assets

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Installs Flutter assets, ensuring the assets directory is cleared and re-copied on each build to prevent stale files. Marked with the 'Runtime' component.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### Flutter Managed Directory Setup

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Sets the path to the Flutter managed directory and adds it as a subdirectory for build processing.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})
```

--------------------------------

### Install AOT Library

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compiled library on non-Debug builds. This ensures performance optimizations are included in release versions.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Install ICU Data File

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Installs the ICU data file to the data directory within the bundle. Marked with the 'Runtime' component.

```cmake
install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Dio HTTP Client with Riverpod

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Demonstrates GET and POST requests using a Riverpod-provided ApiClient. Includes examples of handling typed responses and various error types like TimeoutException, UnauthorizedException, and ServerException.

```dart
// lib/features/common/remote/api_client.dart

// GET request with typed response
final apiClient = ref.read(apiClientProvider);

// Returns T directly (not a Response wrapper)
final List<dynamic> heroes = await apiClient.get<List<dynamic>>('/hero');
final Map<String, dynamic> hero =
    await apiClient.get<Map<String, dynamic>>('/hero/abc-123');

// GET with query parameters
final data = await apiClient.get<Map<String, dynamic>>(
  '/hero',
  queryParameters: {'page': 1, 'limit': 20},
);

// POST request
await apiClient.post<void>(
  '/hero',
  data: {'name': 'Thor', 'power': 90},
);

// Error handling – all errors are mapped to typed exceptions:
try {
  await apiClient.get('/protected');
} on TimeoutException catch (e) {
  print(e.message); // 'Connection timeout'
} on UnauthorizedException catch (e) {
  print(e.message); // 'Unauthorized access'
} on NotFoundException catch (e) {
  print(e.message); // 'Resource not found'
} on ServerException catch (e) {
  print(e.message); // 'Internal server error'
} on NoInternetException catch (e) {
  print(e.message); // 'No internet connection'
}

// Exception types: TimeoutException, NoInternetException,
// RequestCancelledException, BadRequestException, UnauthorizedException,
// ForbiddenException, NotFoundException, ServerException, UnknownException
```

--------------------------------

### Installing Native Assets

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Installs native assets provided by the build.dart script into the application bundle. This ensures that any platform-specific assets are correctly packaged.

```cmake
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

--------------------------------

### SQLite Database Helper with Riverpod

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Provides a Riverpod provider for a singleton DatabaseHelper that manages SQLite database connections and migrations. Includes an example of executing raw queries.

```dart
// lib/utils/database_helper.dart

// The Riverpod provider wraps this singleton and closes on dispose
@riverpod
Future<Database> database(Ref ref) async {
  final db = await DatabaseHelper.instance.database;
  ref.onDispose(() async {
    await DatabaseHelper.instance.close();
  });
  return db;
}

// Direct usage (prefer the provider in UI/ViewModels)
final Database db = await DatabaseHelper.instance.database;

// Raw query example
final rows = await db.query(
  HeroTable.tableName,
  where: '${HeroTable.columnIsFavorite} = ?',
  whereArgs: [1],
  orderBy: '${HeroTable.columnPower} DESC',
);
final favoriteHeroes = rows.map(Hero.fromJson).toList();

// The database is created at: <app documents path>/app.db
// Schema created on first open via:
// await db.execute(HeroTable.createTableQuery);
```

--------------------------------

### HeroListRepository Provider and Usage

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Defines the Riverpod provider for HeroListRepository, which injects API client and database dependencies. Shows examples of fetching heroes from remote and local sources, and performing CRUD operations.

```dart
// lib/features/hero_list/repository/hero_list_repository.dart

// Provider
@riverpod
Future<HeroListRepository> heroListRepository(Ref ref) async {
  final apiClient = ref.watch(apiClientProvider);
  final db = await ref.watch(databaseProvider.future);
  return HeroListRepository(apiClient, db);
}

// ── Remote fetch ──────────────────────────────────────────────────────────
final repo = await ref.read(heroListRepositoryProvider.future);

final List<Hero> remoteHeroes = await repo.getHeroesFromRemote();
// GET https://example.com/api/hero  → deserializes with Hero.fromJson

final Hero? hero = await repo.getHeroFromRemote('hero-uuid-123');
// GET https://example.com/api/hero/hero-uuid-123

// ── Local SQLite CRUD ─────────────────────────────────────────────────────
// Read all heroes from the local DB
final List<Hero> localHeroes = await repo.getHeroes();

// Read a single hero
final Hero? local = await repo.getHero('hero-uuid-123');

// Insert (uses ConflictAlgorithm.replace – upsert behaviour)
await repo.insertHero(Hero(
  id: const Uuid().v4(),
  name: 'Iron Man',
  description: 'Genius billionaire',
  imageUrl: 'https://cdn.example.com/ironman.jpg',
  power: 95,
  lastUpdated: DateTime.now(),
));

// Update
await repo.updateHero(hero.copyWith(power: 99));
// Also bumps lastUpdated to DateTime.now() automatically

// Delete
await repo.deleteHero('hero-uuid-123');

// Toggle favourite
await repo.toggleFavorite('hero-uuid-123');
// Reads current isFavorite value and flips it, then calls updateHero

```

--------------------------------

### Get Current Locale

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Access the current locale of the application using context.locale. This can be useful for conditional logic or displaying the current language.

```dart
print(context.locale); // Locale('en')
```

--------------------------------

### Clone Repository

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/README.md

Use this command to clone the starter template repository to your local machine.

```bash
git clone https://github.com/namanh11611/flutter_mvvm_riverpod.git
```

--------------------------------

### App Entry Point and Initialization

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

The main function initializes SDKs like Supabase and EasyLocalization, registers licenses, and mounts the app within Riverpod's ProviderScope and EasyLocalization.

```dart
// lib/main.dart

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Initialize Supabase
  await Supabase.initialize(
    url: Env.supabaseUrl,       // from .env via envied
    anonKey: Env.supabaseAnonKey,
  );

  // 2. (Optional) Initialize RevenueCat – uncomment to enable
  // await initPlatformState();

  // 3. Initialize localization
  await EasyLocalization.ensureInitialized();

  // 4. Register Google Fonts license
  LicenseRegistry.addLicense(() async* {
    final license = await rootBundle.loadString('google_fonts/OFL.txt');
    yield LicenseEntryWithLineBreaks(['google_fonts'], license);
  });

  // 5. Mount the app inside ProviderScope (Riverpod root)
  runApp(
    ProviderScope(
      observers: [AppObserver()], // logs all provider changes to console
      child: EasyLocalization(
        supportedLocales: const [Locale('en'), Locale('vi')],
        path: 'assets/translations',
        fallbackLocale: const Locale('en'),
        useOnlyLangCode: true,
        child: const MainApp(),
      ),
    ),
  );
}

// Global Supabase client shorthand used throughout the codebase
final supabase = Supabase.instance.client;

// Root widget – reads theme mode from Riverpod and wires the router
class MainApp extends ConsumerWidget {
  const MainApp({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final themeMode = ref.watch(appThemeModeProvider); // AsyncValue<ThemeMode>

    return MaterialApp.router(
      theme: context.lightTheme,
      darkTheme: context.darkTheme,
      themeMode: themeMode.value,
      localizationsDelegates: context.localizationDelegates,
      supportedLocales: context.supportedLocales,
      locale: context.locale,
      routerConfig: router,
      debugShowCheckedModeBanner: false,
      builder: (context, child) => OfflineContainer(child: child),
    );
  }
}
```

--------------------------------

### Profile Model Construction and CopyWith

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Demonstrates how to construct a Profile object and use the copyWith method to create modified instances immutably. Note the field names in the model versus Supabase table names (e.g., expiryDatePremium vs expiry_date_premium).

```dart
// lib/features/profile/model/profile.dart

// Construction
const profile = Profile(
  id: 'uuid-from-supabase',
  email: 'alice@example.com',
  name: 'Alice',
  job: 'Developer',
  avatar: 'https://cdn.example.com/avatar.webp',
  diamond: 100,
  expiryDatePremium: null,   // null = not premium
  isLifetimePremium: null,
);

// CopyWith (returns new instance)
final updated = profile.copyWith(name: 'Alice Smith', diamond: 150);
```

--------------------------------

### Onboarding and Premium Gates

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Implement logic to gate onboarding or premium feature displays. Check if onboarding has been shown or if the user meets criteria to show a premium upsell.

```dart
// Onboarding gate
final wasShown = await ref.read(profileViewModelProvider.notifier)
    .wasShowOnboarding();
if (!wasShown) {
  await ref.read(profileViewModelProvider.notifier).setWasShowOnboarding();
  context.push(Routes.onboarding);
}

// Premium upsell gate (returns false if user is already premium,
true if never shown or shown > 3 days ago)
final shouldShow = await ref.read(profileViewModelProvider.notifier)
    .isShowPremium();
```

--------------------------------

### Initialize Authentication Repository Provider

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Sets up the `AuthenticationRepository` as a Riverpod provider. This provider should be used to access authentication functionalities throughout the app.

```dart
// lib/features/authentication/repository/authentication_repository.dart

// Provider (auto-generated by riverpod_annotation)
@riverpod
AuthenticationRepository authenticationRepository(Ref ref) =>
    AuthenticationRepository();
```

--------------------------------

### Navigate with Extra Parameters using go_router

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Demonstrates how to navigate to different screens using `context.push` and `context.pushReplacement`, passing extra data. Use `state.extra` to retrieve parameters in `pageBuilder`.

```dart
// lib/routing/router.dart – navigating with extra parameters
// Push OTP screen with data
context.push(Routes.otp, extra: {'email': 'user@example.com', 'isRegister': true});

// Push premium screen sliding up from the bottom
context.push(Routes.premium, extra: { Constants.isGoToMain: false});

// Push account info screen passing a Profile object
context.push(Routes.accountInformation, extra: currentProfile);

// Replace the current route (used in SplashScreen)
context.pushReplacement(Routes.main);
```

```dart
// GoRoute definition example with extra parameter extraction:
GoRoute(
  path: Routes.otp,
  pageBuilder: (context, state) {
    final map = state.extra as Map?;
    return state.slidePage(
      OtpScreen(
        email: map?['email'],
        isRegister: map?['isRegister'],
      ),
    );
  },
),
```

```dart
// Custom slide direction (default is SlideDirection.left):
GoRoute(
  path: Routes.premium,
  pageBuilder: (context, state) => state.slidePage(
    const PremiumScreen(),
    direction: SlideDirection.up, // slides in from bottom
  ),
),
```

--------------------------------

### Configure Flutter Library Interface

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/flutter/CMakeLists.txt

Sets up an INTERFACE library target named 'flutter' and configures its include directories, links it against the Flutter library and Pkg-config modules (GTK, GLIB, GIO).

```cmake
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}")
target_link_libraries(flutter INTERFACE
  PkgConfig::GTK
  PkgConfig::GLIB
  PkgConfig::GIO
)
add_dependencies(flutter flutter_assemble)
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/runner/CMakeLists.txt

Applies a standard set of build settings to the specified target. This can be removed if custom build settings are required.

```cmake
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Run Flutter App

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/README.md

This command builds and runs the Flutter application on a connected device or emulator.

```bash
flutter run
```

--------------------------------

### Find and Check Pkg-config Modules

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/flutter/CMakeLists.txt

Uses Pkg-config to find and check for required GTK, GLIB, and GIO modules, making their imported targets available for linking.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
```

--------------------------------

### Runtime Output Directory Configuration

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Sets the runtime output directory for the executable to a specific subdirectory. This is crucial for ensuring the application launches correctly with its resources.

```cmake
set_target_properties(${BINARY_NAME}
  PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
)
```

--------------------------------

### BuildContext Theme and UI Extensions

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

ThemeModeExtension adds convenience getters and helpers to BuildContext for theme-aware color lookups, theme data access, snack bar display, keyboard hiding, and URL launching.

```dart
// lib/extensions/build_context_extension.dart

// Color getters (auto-switch between dark and light values)
Color bg     = context.primaryBackgroundColor;   // #222222 dark / #FFFFFF light
Color bg2    = context.secondaryBackgroundColor; // #222222 dark / #FFF5EE light
Color widget = context.secondaryWidgetColor;     // #404040 dark / #FFFFFF light
Color text   = context.primaryTextColor;         // #EFEEEF dark / #222222 light
Color text2  = context.secondaryTextColor;       // #BEBEBE dark / #606060 light
Color div    = context.dividerColor;             // #606060 dark / #EFEFEF light
bool  dark   = context.isDarkMode;               // true / false

// Theme data (applied in MaterialApp.router)
ThemeData light = context.lightTheme;
ThemeData dark  = context.darkTheme;

// Snack bars
context.showSuccessSnackBar('Profile saved!');
context.showInfoSnackBar('Checking for updates…');
context.showWarningSnackBar('Low storage space');
context.showErrorSnackBar('Network unavailable');

// Keyboard
context.hideKeyboard(); // FocusScope.of(context).unfocus()

// URL launcher with error handling
context.tryLaunchUrl('https://example.com/terms');
```

--------------------------------

### Manage Guest Mode

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Provides functionality to set and check the guest mode status. This is managed using `SharedPreferences` flags.

```dart
// ── Guest mode ────────────────────────────────────────────────────────────
await ref.read(authenticationRepositoryProvider).setIsGuestMode();
final bool isGuest = await ref.read(authenticationRepositoryProvider).isGuestMode();
```

--------------------------------

### Generate Code

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/README.md

Execute this command to generate necessary code, such as Riverpod providers and other build-time generated files. The --delete-conflicting-outputs flag helps manage generated files.

```bash
dart run build_runner build --delete-conflicting-outputs
```

--------------------------------

### Link Libraries and Include Directories

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/runner/CMakeLists.txt

Links necessary libraries and specifies include directories for the target. Application-specific dependencies should be added here.

```cmake
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
```

```cmake
target_link_libraries(${BINARY_NAME} PRIVATE "dwmapi.lib")
```

```cmake
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
```

--------------------------------

### Generate Localization Files

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/README.md

This command generates localization files using the easy_localization package. Ensure the source directory is correctly specified.

```bash
dart run easy_localization:generate -f keys -o locale_keys.g.dart --source-dir assets/translations
```

--------------------------------

### Trigger Authentication Actions

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Use ref.read to trigger authentication actions like signing in with Google or verifying an OTP code. Ensure necessary controllers and parameters are provided.

```dart
// Trigger actions from a button press
ElevatedButton(
  onPressed: () => ref
      .read(authenticationViewModelProvider.notifier)
      .signInWithGoogle(),
  child: const Text('Sign in with Google'),
),

// Verify OTP code
ref.read(authenticationViewModelProvider.notifier).verifyOtp(
  email: emailController.text,
  token: otpController.text,
  isRegister: widget.isRegister,
);
```

--------------------------------

### Application Executable Definition

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Defines the main executable for the application, listing its source files. Ensure all necessary source files are included here.

```cmake
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)

apply_standard_settings(${BINARY_NAME})

target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)

add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Executable Name Configuration

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Defines the name of the application's executable. This name will be used on disk.

```cmake
set(BINARY_NAME "flutter_mvvm_riverpod")
```

--------------------------------

### Generate Locale Keys with easy_localization

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Run this command to generate locale keys from your JSON translation files. Ensure your JSON files are in the specified source directory.

```dart
dart run easy_localization:generate -f keys -o locale_keys.g.dart \
  --source-dir assets/translations
```

--------------------------------

### RevenueCat Integration for In-App Purchases

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Manages product offerings and purchase flows using RevenueCat via a PremiumViewModel. Demonstrates watching paywall state, selecting products, initiating purchases, and restoring purchases.

```dart
// lib/features/premium/ui/view_model/premium_view_model.dart

// Three product tiers (identifiers match RevenueCat dashboard)
// Constants.premiumMonthly  = '$rc_monthly'
// Constants.premiumYearly   = '$rc_annual'
// Constants.premiumLifeTime = '$rc_lifetime'

// Default fallback prices (shown when RevenueCat is unavailable)
// Monthly:  $0.99 / month   (save 34%)
// Yearly:   $9.99 / year    (save 38%)
// Lifetime: $14.99 one-time (save 42%)

// Watch paywall state
final premiumState = ref.watch(premiumViewModelProvider);
premiumState.when(
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => Text('$e'),
  data: (state) => Column(
    children: [
      ...state.products.asMap().entries.map(
        (e) => ProductItem(
          product: e.value,
          isSelected: e.key == state.selectedIndex,
          onTap: () => ref
              .read(premiumViewModelProvider.notifier)
              .selectProduct(e.key),
        ),
      ),
    ],
  ),
);

// Select a product tier
ref.read(premiumViewModelProvider.notifier).selectProduct(0); // monthly
ref.read(premiumViewModelProvider.notifier).selectProduct(1); // yearly
ref.read(premiumViewModelProvider.notifier).selectProduct(2); // lifetime

// Initiate purchase of currently selected product
try {
  await ref.read(premiumViewModelProvider.notifier).purchase();
  final isPurchased = ref.read(premiumViewModelProvider).value!.isPurchaseSuccessfully;
  if (isPurchased) context.pop(); // return to app
} catch (_) {
  context.showErrorSnackBar('Purchase failed');
}

// Restore previous purchases
await ref.read(premiumViewModelProvider.notifier).restorePurchases();
final isRestored = ref.read(premiumViewModelProvider).value!.isRestoreSuccessfully;
```

--------------------------------

### Define Routes with go_router

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Defines all application routes as string constants for use with go_router. Ensure all routes are declared here.

```dart
// lib/routing/routes.dart
class Routes {
  Routes._();
  static const splash           = '/';
  static const welcome          = '/welcome';
  static const register         = '/register';
  static const login            = '/login';
  static const otp              = '/otp';
  static const onboarding       = '/onboarding';
  static const main             = '/main';
  static const accountInformation = '/accountInformation';
  static const appearances      = '/appearances';
  static const languages        = '/languages';
  static const premium          = '/premium';
}
```

--------------------------------

### Sign in with Apple

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Authenticates the user using their Apple account. This involves generating a nonce, hashing it with SHA-256, and using the AppleIDCredential with Supabase.

```dart
// ── Apple Sign-In ─────────────────────────────────────────────────────────
final AuthResponse appleResponse = await ref.read(authenticationRepositoryProvider).signInWithApple();
// Generates nonce → SHA-256 hashes it → AppleIDCredential → Supabase
```

--------------------------------

### Change App Package Name

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/README.md

Use this command to change the application's package name. Replace 'com.new.package.name' with your desired package name.

```bash
dart run change_app_package_name:main com.new.package.name
```

--------------------------------

### Watch Authentication State in UI

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Use ref.watch to observe the authentication state and display UI elements based on loading, error, or data states. Handles navigation after successful sign-in or registration.

```dart
// lib/features/authentication/ui/view_model/authentication_view_model.dart

// Watch state in a ConsumerWidget
final authState = ref.watch(authenticationViewModelProvider);

authState.when(
  loading: () => const CircularProgressIndicator(),
  error: (error, _) => Text('Error: $error'),
  data: (state) {
    if (state.isSignInSuccessfully) {
      if (state.isRegisterSuccessfully) {
        context.pushReplacement(Routes.onboarding);
      } else {
        context.pushReplacement(Routes.main);
      }
    }
    return const SizedBox.shrink();
  },
);
```

--------------------------------

### Sign in with Google

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Authenticates the user using their Google account. This process involves obtaining an ID token and access token from Google and passing them to Supabase.

```dart
// ── Google Sign-In ────────────────────────────────────────────────────────
final AuthResponse googleResponse =
    await ref.read(authenticationRepositoryProvider).signInWithGoogle();
// Uses GoogleSignIn → obtains idToken/accessToken → passes to Supabase
```

--------------------------------

### Build Configuration Types

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Defines the available build configurations (Debug, Profile, Release). This setting is forced to ensure consistency.

```cmake
set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
    CACHE STRING "" FORCE)
```

--------------------------------

### Show and Hide Global Loading Overlay

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Use Global.showLoading and Global.hideLoading to display a full-screen loading indicator. It's safe to call hideLoading even if the overlay is not currently visible.

```dart
// lib/utils/global_loading.dart

// Show a full-screen loading spinner (Lottie animation)
Global.showLoading(context);

// Hide it (safe to call even if not currently showing)
Global.hideLoading();

// Typical usage around an async action:
Future<void> onSubmit() async {
  Global.showLoading(context);
  try {
    await someAsyncOperation();
  } finally {
    Global.hideLoading();
  }
}

// The overlay is inserted into the nearest Overlay widget,
// preventing user interaction while visible.
// Only one overlay entry is created at a time (guarded by null check).
```

--------------------------------

### Flutter and GTK Integration

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Loads Flutter's managed directory and checks for GTK system dependencies. This integrates Flutter's build system and ensures GTK is available.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)

add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
```

--------------------------------

### Cross-Building Configuration

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Configures CMake for cross-building by setting the sysroot and search paths. This is essential when building for a different platform than the host.

```cmake
if(FLUTTER_TARGET_PLATFORM_SYSROOT)
  set(CMAKE_SYSROOT ${FLUTTER_TARGET_PLATFORM_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
  set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
endif()
```

--------------------------------

### Standard Build Settings Function

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Defines a function to apply common compilation settings like C++ standard, warnings, and optimization levels. Use this to enforce consistent build practices across targets.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_14)
  target_compile_options(${TARGET} PRIVATE -Wall -Werror)
  target_compile_options(${TARGET} PRIVATE "<$<NOT:$<CONFIG:Debug>>:-O3>")
  target_compile_definitions(${TARGET} PRIVATE "<$<NOT:$<CONFIG:Debug>>:NDEBUG>")
endfunction()
```

--------------------------------

### Add Preprocessor Definitions for Build Version

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/runner/CMakeLists.txt

Adds preprocessor definitions to the target for build version information. This allows the application to access version details at compile time.

```cmake
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION=\"${FLUTTER_VERSION}\"")
```

```cmake
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MAJOR=${FLUTTER_VERSION_MAJOR}")
```

```cmake
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MINOR=${FLUTTER_VERSION_MINOR}")
```

```cmake
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_PATCH=${FLUTTER_VERSION_PATCH}")
```

```cmake
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_BUILD=${FLUTTER_VERSION_BUILD}")
```

--------------------------------

### Flutter Tool Backend Custom Command

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/flutter/CMakeLists.txt

Configures a custom command to run the Flutter tool backend script. This command generates the Flutter library and headers, and is triggered by a phony target to ensure it runs on every build.

```cmake
add_custom_command(
  OUTPUT ${FLUTTER_LIBRARY} ${FLUTTER_LIBRARY_HEADERS}
    ${CMAKE_CURRENT_BINARY_DIR}/_phony_
  COMMAND ${CMAKE_COMMAND} -E env
    ${FLUTTER_TOOL_ENVIRONMENT}
    "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.sh"
      ${FLUTTER_TARGET_PLATFORM} ${CMAKE_BUILD_TYPE}
  VERBATIM
)
```

--------------------------------

### Define App Typography Scale

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

AppTheme provides a consistent Nunito-based typography scale with predefined TextStyle instances for various semantic levels and sizes. Use these for consistent text styling throughout the application.

```dart
// lib/theme/app_theme.dart

// Titles (weight 700 / Bold)
AppTheme.title32  // 32sp bold – hero headlines
AppTheme.title24  // 24sp bold – screen titles
AppTheme.title20  // 20sp bold
AppTheme.title18  // 18sp bold – section headers
AppTheme.title16  // 16sp bold
AppTheme.title14  // 14sp bold
AppTheme.title12  // 12sp bold – small labels
AppTheme.title10  // 10sp bold – badges / chips

// Subtitles (weight 600 / SemiBold)
AppTheme.subtitle16
AppTheme.subtitle14
AppTheme.subtitle12

// Labels (weight 500 / Medium)
AppTheme.label16
AppTheme.label14
AppTheme.label12

// Body (weight 400 / Regular)
AppTheme.body16
AppTheme.body14
AppTheme.body12

// Usage
Text(
  'Hello World',
  style: AppTheme.title24.copyWith(color: context.primaryTextColor),
),
Text(
  'Subtitle',
  style: AppTheme.subtitle14.copyWith(color: context.secondaryTextColor),
),
```

--------------------------------

### Sign in with Email Magic Link

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Initiates the passwordless sign-in process using an email magic link. Supabase will send a 6-digit OTP to the provided email address.

```dart
// ── Magic-link (passwordless email) ──────────────────────────────────────
await ref.read(authenticationRepositoryProvider)
    .signInWithMagicLink('user@example.com');
// Supabase sends a 6-digit OTP to the email address.
```

--------------------------------

### Profile Model Serialization and Deserialization

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Shows how to serialize a Profile object to JSON and deserialize JSON back into a Profile object using toJson and fromJson methods. Ensure JSON keys match the expected format.

```dart
// Serialization
final json = profile.toJson();
// {
//   "id": "uuid-from-supabase",
//   "email": "alice@example.com",
//   "name": "Alice",
//   "job": "Developer",
//   "avatar": "https://cdn.example.com/avatar.webp",
//   "diamond": 100,
//   "expiry_date_premium": null,
//   "is_lifetime_premium": null
// }
final restored = Profile.fromJson(json);
```

--------------------------------

### Profile Build Mode Linker and Compiler Flags

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Sets linker and compiler flags for the Profile build mode, inheriting settings from the Release mode.

```cmake
set(CMAKE_EXE_LINKER_FLAGS_PROFILE "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE}")
set(CMAKE_C_FLAGS_PROFILE "${CMAKE_C_FLAGS_RELEASE}")
set(CMAKE_CXX_FLAGS_PROFILE "${CMAKE_CXX_FLAGS_RELEASE}")
```

--------------------------------

### Unicode Support

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Adds definitions to enable Unicode support for all projects. This ensures proper handling of international characters.

```cmake
add_definitions(-DUNICODE -D_UNICODE)
```

--------------------------------

### Modern CMake Policy Opt-in

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Explicitly opts into modern CMake behaviors to avoid warnings in recent CMake versions. Covers versions 3.14 through 3.25.

```cmake
cmake_policy(VERSION 3.14...3.25)
```

--------------------------------

### Standard Compilation Settings Function

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Defines a function to apply standard compilation settings to targets. Includes C++17 standard, warning level 4, and exception handling options.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_17)
  target_compile_options(${TARGET} PRIVATE /W4 /WX /wd"4100")
  target_compile_options(${TARGET} PRIVATE /EHsc)
  target_compile_definitions(${TARGET} PRIVATE "_HAS_EXCEPTIONS=0")
  target_compile_definitions(${TARGET} PRIVATE ")<$<CONFIG:Debug>:_DEBUG>)"
endfunction()
```

--------------------------------

### Build Type Configuration

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/CMakeLists.txt

Sets the default build type to 'Debug' if not already specified. Ensures a consistent build mode for the project.

```cmake
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
  set(CMAKE_BUILD_TYPE "Debug" CACHE
    STRING "Flutter build mode" FORCE)
  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
    "Debug" "Profile" "Release")
endif()
```

--------------------------------

### Runner Subdirectory Inclusion

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Includes the 'runner' subdirectory, which contains the application's main build rules.

```cmake
add_subdirectory("runner")
```

--------------------------------

### Read Profile State in UI

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Watch the profile state using ref.watch to display user profile information. Handles loading and error states, and renders user data when available.

```dart
// lib/features/profile/ui/view_model/profile_view_model.dart
// keepAlive: true – this provider stays alive for the app's lifetime

// Read profile in UI
final profileState = ref.watch(profileViewModelProvider);
profileState.when(
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => Text('$e'),
  data: (state) => Text(state.profile?.name ?? 'Guest'),
);
```

--------------------------------

### Define List Prepend Function

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/linux/flutter/CMakeLists.txt

Defines a custom CMake function 'list_prepend' to add a prefix to each element of a list, as 'list(TRANSFORM ... PREPEND ...)' is not available in CMake version 3.10.

```cmake
function(list_prepend LIST_NAME PREFIX)
    set(NEW_LIST "")
    foreach(element ${${LIST_NAME}})
        list(APPEND NEW_LIST "${PREFIX}${element}")
    endforeach(element)
    set(${LIST_NAME} "${NEW_LIST}" PARENT_SCOPE)
endfunction()
```

--------------------------------

### Generated Plugin Rules Inclusion

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/CMakeLists.txt

Includes generated CMake rules for plugins, which manage building and integrating them into the application.

```cmake
include(flutter/generated_plugins.cmake)
```

--------------------------------

### Hero Model with JSON Converters

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Defines the `Hero` model using `freezed` for immutability, suitable for SQLite storage. Includes custom JSON converters for handling SQLite's integer booleans and millisecond-epoch timestamps.

```dart
// lib/features/hero_list/model/hero.dart

// SQLite table schema (from database_constants.dart):
// CREATE TABLE IF NOT EXISTS heroes (
//   id TEXT PRIMARY KEY,
//   name TEXT NOT NULL,
//   description TEXT NOT NULL,
//   imageUrl TEXT NOT NULL,
//   isFavorite INTEGER NOT NULL DEFAULT 0,   ← bool stored as 0/1
//   power INTEGER NOT NULL DEFAULT 0,
//   lastUpdated INTEGER                       ← DateTime as ms-since-epoch
// )

// Deserialize from a SQLite row map
final hero = Hero.fromJson({
  'id': 'abc-123',
  'name': 'Thor',
  'description': 'God of Thunder',
  'imageUrl': 'https://example.com/thor.jpg',
  'isFavorite': 1,    // stored as int; converter returns true
  'power': 90,
  'lastUpdated': 1700000000000, // stored as int; converter returns DateTime
});

// Serialize back to a map for SQLite insert
final row = hero.toJson();
// {'id': 'abc-123', 'isFavorite': 1, 'lastUpdated': 1700000000000, ...}

// CopyWith
final updated = hero.copyWith(isFavorite: false, power: 95);

```

--------------------------------

### Check Login Status

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Asynchronously check the user's login status using ref.read. This is useful for determining initial navigation in splash screens or similar components.

```dart
// Check login status (e.g. in SplashScreen)
final isLoggedIn = await ref
    .read(authenticationViewModelProvider.notifier)
    .isLogin();
```

--------------------------------

### AppObserver for Riverpod Debug Logging

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

AppObserver extends Riverpod's ProviderObserver to log provider lifecycle events (initialization, updates, disposal, errors) to the console, aiding in debugging provider order and state changes.

```dart
// lib/utils/provider_observer.dart

// Registered in main.dart:
ProviderScope(
  observers: [AppObserver()],
  child: ..., 
)

// Console output examples:
// FMR Provider authenticationViewModelProvider was initialized with AsyncData(value: AuthenticationState(...))
// FMR Provider profileViewModelProvider updated from AsyncLoading() to AsyncData(value: ProfileState(...))
// FMR Provider heroListViewModelProvider was disposed
// FMR Provider heroListViewModelProvider threw Exception: ... at #0 ...

// Implements four hooks:
// didAddProvider    – provider first initialized
// didDisposeProvider – provider destroyed
// didUpdateProvider  – state changed (prints old and new value)
// providerDidFail    – provider threw an error
```

--------------------------------

### Define Executable Target

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/runner/CMakeLists.txt

Defines the main executable target for the Windows runner. Source files for the application should be added here. The binary name is controlled by the top-level CMakeLists.txt to ensure `flutter run` compatibility.

```cmake
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)
```

--------------------------------

### Define App Color Palette

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

AppColors provides a static constant color palette organized into semantic families. Use these predefined colors instead of raw hex values for consistent theming.

```dart
// lib/theme/app_colors.dart

// Blueberry (primary brand blue)
AppColors.blueberry100  // Color(0xFF0093FF) – primary action color
AppColors.blueberry10   // Color(0xFFE5F4FF) – lightest tint

// Watermelon (success/secondary green)
AppColors.watermelon100 // Color(0xFF048665)

// Cempedak (warning yellow)
AppColors.cempedak100   // Color(0xFFFFBE15)

// Rambutan (error/danger red)
AppColors.rambutan100   // Color(0xFFE60F41) – used as colorScheme.error

// Monochrome scale
AppColors.mono0         // Color(0xFFFFFFFF) – white
AppColors.mono20        // Color(0xFFEFEFEF)
AppColors.mono40        // Color(0xFFBEBEBE)
AppColors.mono60        // Color(0xFF8F8F8F)
AppColors.mono80        // Color(0xFF606060)
AppColors.mono90        // Color(0xFF404040)
AppColors.mono100       // Color(0xFF222222) – near black

// Gradient overlays (transparent → black)
AppColors.gradient0     // Color(0x00000000) – fully transparent
AppColors.gradient40    // Color(0x66000000) – 40% black
AppColors.gradient100   // Color(0xFF000000) – fully opaque black

AppColors.whiteBg           // Color(0xFFFFF5EE) – light mode background
AppColors.premiumBackground // Color(0xFF000000) – premium screen background

// Usage in themes (from BuildContext extension):
// Light: primary = blueberry100, error = rambutan100, scaffold = mono0
// Dark:  primary = blueberry100, error = rambutan100, scaffold = mono100
```

--------------------------------

### Verify OTP for Authentication

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Verifies the 6-digit OTP received via email for sign-in or registration. The `isRegister` flag determines if it's for a new signup or a magic link login.

```dart
// ── OTP verification ──────────────────────────────────────────────────────
final AuthResponse response = await ref.read(authenticationRepositoryProvider)
    .verifyOtp(
      email: 'user@example.com',
      token: '123456',   // code entered by the user
      isRegister: true,  // false → magiclink type, true → signup type
    );
print(response.user?.email); // user@example.com
```

--------------------------------

### Add Flutter Assemble Dependency

Source: https://github.com/namanh11611/flutter_mvvm_riverpod/blob/main/windows/runner/CMakeLists.txt

Ensures that the Flutter tool's assembly process is completed before the main target is built. This is a required step for Flutter projects.

```cmake
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Environment Configuration with envied

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

The Env class securely loads secrets from a .env file at build time using the envied package, making them accessible throughout the application.

```dart
// lib/environment/env.dart  (source)
@Envied(path: '.env')
abstract class Env {
  @EnviedField(varName: 'SUPABASE_URL', obfuscate: true)
  static final String supabaseUrl = _Env.supabaseUrl;

  @EnviedField(varName: 'SUPABASE_ANON_KEY', obfuscate: true)
  static final String supabaseAnonKey = _Env.supabaseAnonKey;

  @EnviedField(varName: 'GOOGLE_CLIENT_ID', obfuscate: true)
  static final String googleClientId = _Env.googleClientId;

  @EnviedField(varName: 'GOOGLE_SERVER_CLIENT_ID', obfuscate: true)
  static final String googleServerClientId = _Env.googleServerClientId;

  @EnviedField(varName: 'REVENUE_CAT_PLAY_STORE', obfuscate: true)
  static final String revenueCatPlayStore = _Env.revenueCatPlayStore;

  @EnviedField(varName: 'REVENUE_CAT_APP_STORE', obfuscate: true)
  static final String revenueCatAppStore = _Env.revenueCatAppStore;
}

// .env  (never committed, add to .gitignore)
// SUPABASE_URL=https://xyzcompany.supabase.co
// SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
// GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
// GOOGLE_SERVER_CLIENT_ID=123456789-xyz.apps.googleusercontent.com
// REVENUE_CAT_PLAY_STORE=goog_xxxxxxxxxxxxxx
// REVENUE_CAT_APP_STORE=appl_xxxxxxxxxxxxxx

// Regenerate after editing .env:
// dart run build_runner build --delete-conflicting-outputs

```

--------------------------------

### Switch Locale at Runtime

Source: https://context7.com/namanh11611/flutter_mvvm_riverpod/llms.txt

Call context.setLocale() with the desired Locale object to change the application's language dynamically. This is typically done in a settings or language selection screen.

```dart
await context.setLocale(const Locale('vi'));  // Vietnamese
await context.setLocale(const Locale('en'));  // English (fallback)
```