reis-mobile 0.3.5

package/skills/flutter-building-forms/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: flutter-building-forms
+description: Builds Flutter forms with validation and user input handling. Use when creating login screens, data entry forms, or any multi-field user input.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:15:24 GMT
+routing: manual
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Building Validated Forms
+
+## Contents
+- [Form Architecture](#form-architecture)
+- [Field Validation](#field-validation)
+- [Workflow: Implementing a Validated Form](#workflow-implementing-a-validated-form)
+- [Examples](#examples)
+
+## Form Architecture
+
+Implement forms using a `Form` widget to group and validate multiple input fields together. 
+
+- **Use a StatefulWidget:** Always host your `Form` inside a `StatefulWidget`. 
+- **Persist the GlobalKey:** Instantiate a `GlobalKey<FormState>` exactly once as a final variable within the `State` class. Do not generate a new `GlobalKey` inside the `build` method; doing so is resource-expensive and destroys the form's state on every rebuild.
+- **Bind the Key:** Pass the `GlobalKey<FormState>` to the `key` property of the `Form` widget. This uniquely identifies the form and provides access to the `FormState` for validation and submission.
+- **Alternative Access:** If dealing with highly complex widget trees where passing the key is impractical, use `Form.of(context)` to access the `FormState` from a descendant widget.
+
+## Field Validation
+
+Use `TextFormField` to render Material Design text inputs with built-in validation support. `TextFormField` is a convenience widget that automatically wraps a standard `TextField` inside a `FormField`.
+
+- **Implement the Validator:** Provide a `validator()` callback function to each `TextFormField`.
+- **Return Error Messages:** If the user's input is invalid, return a `String` containing the specific error message. The `Form` will automatically rebuild to display this text below the field.
+- **Return Null for Success:** If the input passes validation, you must return `null`.
+
+## Workflow: Implementing a Validated Form
+
+Follow this sequential workflow to implement and validate a form. Copy the checklist to track your progress.
+
+**Task Progress:**
+- [ ] 1. Create a `StatefulWidget` and its corresponding `State` class.
+- [ ] 2. Instantiate `final _formKey = GlobalKey<FormState>();` in the `State` class.
+- [ ] 3. Return a `Form` widget in the `build` method and assign `key: _formKey`.
+- [ ] 4. Add `TextFormField` widgets as descendants of the `Form`.
+- [ ] 5. Write a `validator` function for each `TextFormField` (return `String` on error, `null` on success).
+- [ ] 6. Add a submit button (e.g., `ElevatedButton`).
+- [ ] 7. Implement the validation check in the button's `onPressed` callback using `_formKey.currentState!.validate()`.
+
+### Validation Decision Logic
+
+When the user triggers the submit action, execute the following conditional logic:
+
+1. Call `_formKey.currentState!.validate()`.
+2. **If `true` (Valid):** All validators returned `null`. Proceed with form submission (e.g., save data, make API call) and display a success indicator (e.g., a `SnackBar`).
+3. **If `false` (Invalid):** One or more validators returned an error string. The `FormState` automatically rebuilds the UI to display the error messages. 
+4. **Feedback Loop:** Run validator -> review errors -> fix. The user must adjust their input and resubmit until `validate()` returns `true`.
+
+## Examples
+
+### Complete Validated Form Implementation
+
+Use the following pattern to implement a robust, validated form.
+
+```dart
+import 'package:flutter/material.dart';
+
+class UserRegistrationForm extends StatefulWidget {
+  const UserRegistrationForm({super.key});
+
+  @override
+  State<UserRegistrationForm> createState() => _UserRegistrationFormState();
+}
+
+class _UserRegistrationFormState extends State<UserRegistrationForm> {
+  // 1. Persist the GlobalKey in the State class
+  final _formKey = GlobalKey<FormState>();
+
+  @override
+  Widget build(BuildContext context) {
+    // 2. Bind the key to the Form
+    return Form(
+      key: _formKey,
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          // 3. Add TextFormFields with validators
+          TextFormField(
+            decoration: const InputDecoration(
+              labelText: 'Username',
+              hintText: 'Enter your username',
+            ),
+            validator: (value) {
+              if (value == null || value.isEmpty) {
+                return 'Please enter a username'; // Error state
+              }
+              if (value.length < 4) {
+                return 'Username must be at least 4 characters'; // Error state
+              }
+              return null; // Valid state
+            },
+          ),
+          const SizedBox(height: 16),
+          // 4. Add the submit button
+          ElevatedButton(
+            onPressed: () {
+              // 5. Trigger validation logic
+              if (_formKey.currentState!.validate()) {
+                // Form is valid: Process data
+                ScaffoldMessenger.of(context).showSnackBar(
+                  const SnackBar(content: Text('Processing Data')),
+                );
+              } else {
+                // Form is invalid: Errors are automatically displayed
+                debugPrint('Form validation failed.');
+              }
+            },
+            child: const Text('Submit'),
+          ),
+        ],
+      ),
+    );
+  }
+}
+```

package/skills/flutter-building-layouts/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: flutter-building-layouts
+description: Builds Flutter layouts using the constraint system and layout widgets. Use when creating or refining the UI structure of a Flutter application.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:14:15 GMT
+routing: manual
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Architecting Flutter Layouts
+
+## Contents
+- [Core Layout Principles](#core-layout-principles)
+- [Structural Widgets](#structural-widgets)
+- [Adaptive and Responsive Design](#adaptive-and-responsive-design)
+- [Workflow: Implementing a Complex Layout](#workflow-implementing-a-complex-layout)
+- [Examples](#examples)
+
+## Core Layout Principles
+
+Master the fundamental Flutter layout rule: **Constraints go down. Sizes go up. Parent sets position.**
+
+*   **Pass Constraints Down:** Always pass constraints (minimum/maximum width and height) from the parent Widget to its children. A Widget cannot choose its own size independently of its parent's constraints.
+*   **Pass Sizes Up:** Calculate the child Widget's desired size within the given constraints and pass this size back up to the parent.
+*   **Set Position via Parent:** Define the `x` and `y` coordinates of a child Widget exclusively within the parent Widget. Children do not know their own position on the screen.
+*   **Avoid Unbounded Constraints:** Never pass unbounded constraints (e.g., `double.infinity`) in the cross-axis of a flex box (`Row` or `Column`) or within scrollable regions (`ListView`). This causes render exceptions.
+
+## Structural Widgets
+
+Select the appropriate structural Widget based on the required spatial arrangement.
+
+*   **Use `Row` and `Column`:** Implement `Row` for horizontal linear layouts and `Column` for vertical linear layouts. Control child alignment using `mainAxisAlignment` and `crossAxisAlignment`.
+*   **Use `Expanded` and `Flexible`:** Wrap children of `Row` or `Column` in `Expanded` to force them to fill available space, or `Flexible` to allow them to size themselves up to the available space.
+*   **Use `Container`:** Wrap Widgets in a `Container` when you need to apply padding, margins, borders, or background colors.
+*   **Use `Stack`:** Implement `Stack` when Widgets must overlap on the Z-axis. Use `Positioned` to anchor children to specific edges of the `Stack`.
+*   **Use `SizedBox`:** Enforce strict, tight constraints on a child Widget by wrapping it in a `SizedBox` with explicit `width` and `height` values.
+
+## Adaptive and Responsive Design
+
+Apply conditional logic to handle varying screen sizes and form factors.
+
+*   **If fitting UI into available space (Responsive):** Use `LayoutBuilder`, `Expanded`, and `Flexible` to dynamically adjust the size and placement of elements based on the parent's constraints.
+*   **If adjusting UI usability for a specific form factor (Adaptive):** Use conditional rendering to swap entire layout structures. For example, render a bottom navigation bar on mobile, but a side navigation rail on tablets/desktop.
+
+## Workflow: Implementing a Complex Layout
+
+Follow this sequential workflow to architect and implement robust Flutter layouts.
+
+### Task Progress
+- [ ] **Phase 1: Visual Deconstruction**
+  - [ ] Break down the target UI into a hierarchy of rows, columns, and grids.
+  - [ ] Identify overlapping elements (requiring `Stack`).
+  - [ ] Identify scrolling regions (requiring `ListView` or `SingleChildScrollView`).
+- [ ] **Phase 2: Constraint Planning**
+  - [ ] Determine which Widgets require tight constraints (fixed size) vs. loose constraints (flexible size).
+  - [ ] Identify potential unbounded constraint risks (e.g., a `ListView` inside a `Column`).
+- [ ] **Phase 3: Implementation**
+  - [ ] Build the layout from the outside in, starting with the `Scaffold` and primary structural Widgets.
+  - [ ] Extract deeply nested layout sections into separate, stateless Widgets to maintain readability.
+- [ ] **Phase 4: Validation and Feedback Loop**
+  - [ ] Run the application on target devices/simulators.
+  - [ ] **Run validator -> review errors -> fix:** Open the Flutter Inspector. Enable "Debug Paint" to visualize render boxes.
+  - [ ] Check for yellow/black striped overflow warnings.
+  - [ ] If overflow occurs: Wrap the overflowing Widget in `Expanded` (if inside a flex box) or wrap the parent in a scrollable Widget.
+
+## Examples
+
+### Example: Resolving Unbounded Constraints in Flex Boxes
+
+**Anti-pattern:** Placing a `ListView` directly inside a `Column` causes an unbounded height exception because the `Column` provides infinite vertical space to the `ListView`.
+
+```dart
+// BAD: Throws unbounded height exception
+Column(
+  children: [
+    Text('Header'),
+    ListView(
+      children: [/* items */],
+    ),
+  ],
+)
+```
+
+**Implementation:** Wrap the `ListView` in an `Expanded` Widget to bound its height to the remaining space in the `Column`.
+
+```dart
+// GOOD: ListView is constrained to remaining space
+Column(
+  children: [
+    Text('Header'),
+    Expanded(
+      child: ListView(
+        children: [/* items */],
+      ),
+    ),
+  ],
+)
+```
+
+### Example: Responsive Layout with LayoutBuilder
+
+Implement `LayoutBuilder` to conditionally render different structural Widgets based on available width.
+
+```dart
+Widget buildAdaptiveLayout(BuildContext context) {
+  return LayoutBuilder(
+    builder: (context, constraints) {
+      // Conditional logic based on screen width
+      if (constraints.maxWidth > 600) {
+        // Tablet/Desktop: Side-by-side layout
+        return Row(
+          children: [
+            SizedBox(width: 250, child: SidebarWidget()),
+            Expanded(child: MainContentWidget()),
+          ],
+        );
+      } else {
+        // Mobile: Stacked layout with navigation
+        return Column(
+          children: [
+            Expanded(child: MainContentWidget()),
+            BottomNavigationBarWidget(),
+          ],
+        );
+      }
+    },
+  );
+}
+```

package/skills/flutter-building-plugins/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: flutter-building-plugins
+description: Builds Flutter plugins that provide native interop for other apps to use. Use when creating reusable packages that bridge Flutter with platform-specific functionality.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:21:35 GMT
+routing: manual
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Developing Flutter Plugins
+
+## Contents
+- [Architecture & Design Patterns](#architecture--design-patterns)
+- [Workflow: Creating a New Plugin](#workflow-creating-a-new-plugin)
+- [Workflow: Implementing Android Platform Code](#workflow-implementing-android-platform-code)
+- [Workflow: Implementing Windows Platform Code](#workflow-implementing-windows-platform-code)
+- [Workflow: Adding Platforms to an Existing Plugin](#workflow-adding-platforms-to-an-existing-plugin)
+- [Examples](#examples)
+
+## Architecture & Design Patterns
+
+### Federated Plugins
+Implement federated plugins to split a plugin's API across multiple packages, allowing independent teams to build platform-specific implementations. Structure federated plugins into three distinct components:
+1. **App-facing interface:** The primary package users depend on. It exports the public API.
+2. **Platform interface:** The package defining the common interface that all platform implementations must implement.
+3. **Platform implementations:** Independent packages containing platform-specific code (e.g., `my_plugin_android`, `my_plugin_windows`).
+
+### FFI vs. Standard Plugins
+Choose the correct plugin template based on your native interoperability requirements:
+* **Standard Plugins (`--template=plugin`):** Use for accessing platform-specific APIs (e.g., Android SDK, iOS frameworks) via Method Channels.
+* **FFI Plugins (`--template=plugin_ffi`):** Use for accessing C/C++ native libraries, configuring Google Play services on Android, or using static linking on iOS/macOS. 
+  * *Constraint:* FFI plugin packages support bundling native code and method channel registration code, but *not* method channels themselves. If you require both method channels and FFI, use the standard non-FFI plugin template.
+
+## Workflow: Creating a New Plugin
+
+Follow this workflow to initialize a new plugin package.
+
+**Task Progress:**
+- [ ] Determine if the plugin requires FFI or standard Method Channels.
+- [ ] Execute the appropriate `flutter create` command.
+- [ ] Verify the generated directory structure.
+
+**Conditional Initialization:**
+* **If creating a STANDARD plugin:**
+  Run the following command, specifying your supported platforms, organization, and preferred languages (defaults are Swift and Kotlin):
+  ```bash
+  flutter create --template=plugin \
+    --platforms=android,ios,web,linux,macos,windows \
+    --org com.example.organization \
+    -i objc -a java \
+    my_plugin
+  ```
+* **If creating an FFI plugin:**
+  Run the following command to generate a project with Dart code in `lib` (using `dart:ffi`) and native source code in `src` (with a `CMakeLists.txt`):
+  ```bash
+  flutter create --template=plugin_ffi my_ffi_plugin
+  ```
+
+## Workflow: Implementing Android Platform Code
+
+Always edit Android platform code using Android Studio to ensure proper code completion and Gradle synchronization.
+
+**Task Progress:**
+- [ ] Run initial build to generate necessary Gradle files.
+- [ ] Open the Android module in Android Studio.
+- [ ] Implement `FlutterPlugin` and lifecycle-aware interfaces.
+- [ ] Refactor legacy `registerWith` logic.
+- [ ] Run validator -> review errors -> fix.
+
+1. **Generate Build Files:**
+   Build the code at least once before editing to resolve dependencies.
+   ```bash
+   cd example
+   flutter build apk --config-only
+   ```
+2. **Open in IDE:**
+   Launch Android Studio and open the `example/android/build.gradle` or `example/android/build.gradle.kts` file.
+3. **Locate Source:**
+   Navigate to your plugin's source code at `java/<organization-path>/<PluginName>`.
+4. **Implement V2 Embedding:**
+   * Implement the `FlutterPlugin` interface.
+   * Ensure your plugin class has a public constructor.
+   * Extract shared initialization logic from the legacy `registerWith()` method and the new `onAttachedToEngine()` method into a single private method. Both entry points must call this private method to maintain backward compatibility without duplicating logic.
+5. **Implement Lifecycle Interfaces:**
+   * **If your plugin requires an `Activity` reference:** Implement the `ActivityAware` interface and handle the `onAttachedToActivity`, `onDetachedFromActivityForConfigChanges`, `onReattachedToActivityForConfigChanges`, and `onDetachedFromActivity` callbacks.
+   * **If your plugin runs in a background `Service`:** Implement the `ServiceAware` interface.
+6. **Update Example App:**
+   Ensure the example app's `MainActivity.java` extends the v2 embedding `io.flutter.embedding.android.FlutterActivity`.
+7. **Document API:**
+   Document all non-overridden public members in your Android implementation.
+
+## Workflow: Implementing Windows Platform Code
+
+Always edit Windows platform code using Visual Studio.
+
+**Task Progress:**
+- [ ] Run initial build to generate the Visual Studio solution.
+- [ ] Open the solution in Visual Studio.
+- [ ] Implement C++ logic.
+- [ ] Rebuild the solution.
+
+1. **Generate Build Files:**
+   ```bash
+   cd example
+   flutter build windows
+   ```
+2. **Open in IDE:**
+   Launch Visual Studio and open the `example/build/windows/hello_example.sln` file.
+3. **Locate Source:**
+   Navigate to `hello_plugin/Source Files` and `hello_plugin/Header Files` in the Solution Explorer.
+4. **Rebuild:**
+   After making changes to the C++ plugin code, you *must* rebuild the solution in Visual Studio before running the app, or the outdated plugin binary will be used.
+
+## Workflow: Adding Platforms to an Existing Plugin
+
+Use this workflow to retrofit an existing plugin with support for additional platforms.
+
+**Task Progress:**
+- [ ] Run the platform addition command.
+- [ ] Update iOS/macOS podspecs (if applicable).
+- [ ] Implement the platform-specific code.
+
+1. **Run Create Command:**
+   Navigate to the root directory of your existing plugin and run:
+   ```bash
+   flutter create --template=plugin --platforms=web,macos .
+   ```
+2. **Update Podspecs:**
+   If adding iOS or macOS support, open the generated `.podspec` file and configure the required dependencies and deployment targets.
+
+## Examples
+
+### Android V2 Embedding Implementation
+High-fidelity example of an Android plugin implementing `FlutterPlugin` and `ActivityAware` while maintaining legacy compatibility.
+
+```java
+package com.example.myplugin;
+
+import androidx.annotation.NonNull;
+import io.flutter.embedding.engine.plugins.FlutterPlugin;
+import io.flutter.embedding.engine.plugins.activity.ActivityAware;
+import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding;
+import io.flutter.plugin.common.MethodCall;
+import io.flutter.plugin.common.MethodChannel;
+import io.flutter.plugin.common.MethodChannel.MethodCallHandler;
+import io.flutter.plugin.common.MethodChannel.Result;
+import io.flutter.plugin.common.PluginRegistry.Registrar;
+
+/** MyPlugin */
+public class MyPlugin implements FlutterPlugin, MethodCallHandler, ActivityAware {
+  private MethodChannel channel;
+
+  // Public constructor required for v2 embedding
+  public MyPlugin() {}
+
+  @Override
+  public void onAttachedToEngine(@NonNull FlutterPluginBinding flutterPluginBinding) {
+    setupChannel(flutterPluginBinding.getBinaryMessenger());
+  }
+
+  // Legacy v1 embedding support
+  public static void registerWith(Registrar registrar) {
+    MyPlugin plugin = new MyPlugin();
+    plugin.setupChannel(registrar.messenger());
+  }
+
+  // Shared initialization logic
+  private void setupChannel(BinaryMessenger messenger) {
+    channel = new MethodChannel(messenger, "my_plugin");
+    channel.setMethodCallHandler(this);
+  }
+
+  @Override
+  public void onMethodCall(@NonNull MethodCall call, @NonNull Result result) {
+    if (call.method.equals("getPlatformVersion")) {
+      result.success("Android " + android.os.Build.VERSION.RELEASE);
+    } else {
+      result.notImplemented();
+    }
+  }
+
+  @Override
+  public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
+    channel.setMethodCallHandler(null);
+  }
+
+  @Override
+  public void onAttachedToActivity(@NonNull ActivityPluginBinding binding) {
+    // Handle Activity attachment
+  }
+
+  @Override
+  public void onDetachedFromActivityForConfigChanges() {
+    // Handle config changes
+  }
+
+  @Override
+  public void onReattachedToActivityForConfigChanges(@NonNull ActivityPluginBinding binding) {
+    // Handle reattachment
+  }
+
+  @Override
+  public void onDetachedFromActivity() {
+    // Clean up Activity references
+  }
+}
+```

package/skills/flutter-caching-data/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: flutter-caching-data
+description: Implements caching strategies for Flutter apps to improve performance and offline support. Use when retaining app data locally to reduce network requests or speed up startup.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:19:54 GMT
+routing: manual
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Implementing Flutter Caching and Offline-First Architectures
+
+## Contents
+- [Selecting a Caching Strategy](#selecting-a-caching-strategy)
+- [Implementing Offline-First Data Synchronization](#implementing-offline-first-data-synchronization)
+- [Managing File System and SQLite Persistence](#managing-file-system-and-sqlite-persistence)
+- [Optimizing UI, Scroll, and Image Caching](#optimizing-ui-scroll-and-image-caching)
+- [Caching the FlutterEngine (Android)](#caching-the-flutterengine-android)
+- [Workflows](#workflows)
+
+## Selecting a Caching Strategy
+
+Apply the appropriate caching mechanism based on the data lifecycle and size requirements.
+
+*   **If storing small, non-critical UI states or preferences:** Use `shared_preferences`.
+*   **If storing large, structured datasets:** Use on-device databases (SQLite via `sqflite`, Drift, Hive CE, or Isar).
+*   **If storing binary data or large media:** Use file system caching via `path_provider`.
+*   **If retaining user session state (navigation, scroll positions):** Implement Flutter's built-in state restoration to sync the Element tree with the engine.
+*   **If optimizing Android initialization:** Pre-warm and cache the `FlutterEngine`.
+
+## Implementing Offline-First Data Synchronization
+
+Design repositories as the single source of truth, combining local databases and remote API clients. 
+
+### Read Operations (Stream Approach)
+Yield local data immediately for fast UI rendering, then fetch remote data, update the local cache, and yield the fresh data.
+
+```dart
+Stream<UserProfile> getUserProfile() async* {
+  // 1. Yield local cache first
+  final localProfile = await _databaseService.fetchUserProfile();
+  if (localProfile != null) yield localProfile;
+
+  // 2. Fetch remote, update cache, yield fresh data
+  try {
+    final remoteProfile = await _apiClientService.getUserProfile();
+    await _databaseService.updateUserProfile(remoteProfile);
+    yield remoteProfile;
+  } catch (e) {
+    // Handle network failure; UI already has local data
+  }
+}
+```
+
+### Write Operations
+Determine the write strategy based on data criticality:
+*   **If strict server synchronization is required (Online-only):** Attempt the API call first. Only update the local database if the API call succeeds.
+*   **If offline availability is prioritized (Offline-first):** Write to the local database immediately. Attempt the API call. If the API call fails, flag the local record for background synchronization.
+
+### Background Synchronization
+Add a `synchronized` boolean flag to your data models. Run a periodic background task (e.g., via `workmanager` or a `Timer`) to push unsynchronized local changes to the server.
+
+## Managing File System and SQLite Persistence
+
+### File System Caching
+Use `path_provider` to locate the correct directory. 
+*   Use `getApplicationDocumentsDirectory()` for persistent data.
+*   Use `getTemporaryDirectory()` for cache data the OS can clear.
+
+```dart
+Future<File> get _localFile async {
+  final directory = await getApplicationDocumentsDirectory();
+  return File('${directory.path}/cache.txt');
+}
+```
+
+### SQLite Persistence
+Use `sqflite` for relational data caching. Always use `whereArgs` to prevent SQL injection.
+
+```dart
+Future<void> updateCachedRecord(Record record) async {
+  final db = await database;
+  await db.update(
+    'records',
+    record.toMap(),
+    where: 'id = ?',
+    whereArgs: [record.id], // NEVER use string interpolation here
+  );
+}
+```
+
+## Optimizing UI, Scroll, and Image Caching
+
+### Image Caching
+Image I/O and decompression are expensive. 
+*   Use the `cached_network_image` package to handle file-system caching of remote images.
+*   **Custom ImageProviders:** If implementing a custom `ImageProvider`, override `createStream()` and `resolveStreamForKey()` instead of the deprecated `resolve()` method.
+*   **Cache Sizing:** The `ImageCache.maxByteSize` no longer automatically expands for large images. If loading images larger than the default cache size, manually increase `ImageCache.maxByteSize` or subclass `ImageCache` to implement custom eviction logic.
+
+### Scroll Caching
+When configuring caching for scrollable widgets (`ListView`, `GridView`, `Viewport`), use the `scrollCacheExtent` property with a `ScrollCacheExtent` object. Do not use the deprecated `cacheExtent` and `cacheExtentStyle` properties.
+
+```dart
+// Correct implementation
+ListView(
+  scrollCacheExtent: const ScrollCacheExtent.pixels(500.0),
+  children: // ...
+)
+
+Viewport(
+  scrollCacheExtent: const ScrollCacheExtent.viewport(0.5),
+  slivers: // ...
+)
+```
+
+### Widget Caching
+*   Avoid overriding `operator ==` on `Widget` objects. It causes O(N²) behavior during rebuilds.
+*   **Exception:** You may override `operator ==` *only* on leaf widgets (no children) where comparing properties is significantly faster than rebuilding, and the properties rarely change.
+*   Prefer using `const` constructors to allow the framework to short-circuit rebuilds automatically.
+
+## Caching the FlutterEngine (Android)
+
+To eliminate the non-trivial warm-up time of a `FlutterEngine` when adding Flutter to an existing Android app, pre-warm and cache the engine.
+
+1. Instantiate and pre-warm the engine in the `Application` class.
+2. Store it in the `FlutterEngineCache`.
+3. Retrieve it using `withCachedEngine` in the `FlutterActivity` or `FlutterFragment`.
+
+```kotlin
+// 1. Pre-warm in Application class
+val flutterEngine = FlutterEngine(this)
+flutterEngine.navigationChannel.setInitialRoute("/cached_route")
+flutterEngine.dartExecutor.executeDartEntrypoint(DartEntrypoint.createDefault())
+
+// 2. Cache the engine
+FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine)
+
+// 3. Use in Activity/Fragment
+startActivity(
+  FlutterActivity.withCachedEngine("my_engine_id").build(this)
+)
+```
+*Note: You cannot set an initial route via the Activity/Fragment builder when using a cached engine. Set the initial route on the engine's navigation channel before executing the Dart entrypoint.*
+
+## Workflows
+
+### Workflow: Implementing an Offline-First Repository
+Follow these steps to implement a robust offline-first data layer.
+
+- [ ] **Task Progress:**
+  - [ ] Define the data model with a `synchronized` boolean flag (default `false`).
+  - [ ] Implement the local `DatabaseService` (SQLite/Hive) with CRUD operations.
+  - [ ] Implement the remote `ApiClientService` for network requests.
+  - [ ] Create the `Repository` class combining both services.
+  - [ ] Implement the read method returning a `Stream<T>` (yield local, fetch remote, update local, yield remote).
+  - [ ] Implement the write method (write local, attempt remote, update `synchronized` flag).
+  - [ ] Implement a background sync function to process records where `synchronized == false`.
+  - [ ] Run validator -> review errors -> fix (Test offline behavior by disabling network).
+
+### Workflow: Pre-warming the Android FlutterEngine
+Follow these steps to cache the FlutterEngine for seamless Android integration.
+
+- [ ] **Task Progress:**
+  - [ ] Locate the Android `Application` class (create one if it doesn't exist and register in `AndroidManifest.xml`).
+  - [ ] Instantiate a new `FlutterEngine`.
+  - [ ] (Optional) Set the initial route via `navigationChannel.setInitialRoute()`.
+  - [ ] Execute the Dart entrypoint via `dartExecutor.executeDartEntrypoint()`.
+  - [ ] Store the engine in `FlutterEngineCache.getInstance().put()`.
+  - [ ] Update the target `FlutterActivity` or `FlutterFragment` to use `.withCachedEngine("id")`.
+  - [ ] Run validator -> review errors -> fix (Verify no blank screen appears during transition).