appiq-solution 1.4.8 → 1.5.0

package/#NEW APP PROMPT/flutter-ai-rules/combined/flutter_with_riverpod.md

@@ -1,375 +0,0 @@
-# Flutter with Riverpod - Combined Rules
-
-### Using Ref in Riverpod
-1. The `Ref` object is essential for accessing the provider system, reading or watching other providers, managing lifecycles, and handling dependencies in Riverpod.
-2. In functional providers, obtain `Ref` as a parameter; in class-based providers, access it as a property of the Notifier.
-3. In widgets, use `WidgetRef` (a subtype of `Ref`) to interact with providers.
-4. The `@riverpod` annotation is used to define providers with code generation, where the function receives `ref` as its parameter.
-5. Use `ref.watch` to reactively listen to other providers; use `ref.read` for one-time access (non-reactive); use `ref.listen` for imperative subscriptions; use `ref.onDispose` to clean up resources.
-6. Example: Functional provider with Ref
-   ```dart
-   final otherProvider = Provider<int>((ref) => 0);
-   final provider = Provider<int>((ref) {
-     final value = ref.watch(otherProvider);
-     return value * 2;
-   });
-   ```
-7. Example: Provider with @riverpod annotation
-   ```dart
-   @riverpod
-   int example(ref) {
-     return 0;
-   }
-   ```
-8. Example: Using Ref for cleanup
-   ```dart
-   final provider = StreamProvider<int>((ref) {
-     final controller = StreamController<int>();
-     ref.onDispose(controller.close);
-     return controller.stream;
-   });
-   ```
-9. Example: Using WidgetRef in a widget
-   ```dart
-   class MyWidget extends ConsumerWidget {
-     @override
-     Widget build(BuildContext context, WidgetRef ref) {
-       final value = ref.watch(myProvider);
-       return Text('$value');
-     }
-   }
-   ```
-
-### Naming Conventions
-1. Use terms consistently throughout your code.
-2. Follow existing mnemonic conventions when naming type parameters (e.g., `E` for element, `K`/`V` for key/value, `T`/`S`/`U` for generic types).
-3. Name types using `UpperCamelCase` (classes, enums, typedefs, type parameters).
-4. Name extensions using `UpperCamelCase`.
-5. Name packages, directories, and source files using `lowercase_with_underscores`.
-6. Name import prefixes using `lowercase_with_underscores`.
-7. Name other identifiers using `lowerCamelCase` (variables, parameters, named parameters).
-8. Capitalize acronyms and abbreviations longer than two letters like words.
-9. Avoid abbreviations unless the abbreviation is more common than the unabbreviated term.
-10. Prefer putting the most descriptive noun last in names.
-11. Consider making code read like a sentence when designing APIs.
-12. Prefer a noun phrase for non-boolean properties or variables.
-13. Prefer a non-imperative verb phrase for boolean properties or variables.
-14. Prefer the positive form for boolean property and variable names.
-15. Consider omitting the verb for named boolean parameters.
-16. Use camelCase for variable and function names.
-17. Use PascalCase for class names.
-18. Use snake_case for file names.
-
-### Types and Functions
-1. Use class modifiers to control if your class can be extended or used as an interface.
-2. Type annotate variables without initializers.
-3. Type annotate fields and top-level variables if the type isn't obvious.
-4. Annotate return types on function declarations.
-5. Annotate parameter types on function declarations.
-6. Write type arguments on generic invocations that aren't inferred.
-7. Annotate with `dynamic` instead of letting inference fail.
-8. Use `Future<void>` as the return type of asynchronous members that do not produce values.
-9. Use getters for operations that conceptually access properties.
-10. Use setters for operations that conceptually change properties.
-11. Use a function declaration to bind a function to a name.
-12. Use inclusive start and exclusive end parameters to accept a range.
-
-### Style
-1. Format your code using `dart format`.
-2. Use curly braces for all flow control statements.
-3. Prefer `final` over `var` when variable values won't change.
-4. Use `const` for compile-time constants.
-
-### Imports & Files
-1. Don't import libraries inside the `src` directory of another package.
-2. Don't allow import paths to reach into or out of `lib`.
-3. Prefer relative import paths within a package.
-4. Don't use `/lib/` or `../` in import paths.
-5. Consider writing a library-level doc comment for library files.
-
-### Structure
-1. Keep files focused on a single responsibility.
-2. Limit file length to maintain readability.
-3. Group related functionality together.
-4. Prefer making fields and top-level variables `final`.
-5. Consider making your constructor `const` if the class supports it.
-6. Prefer making declarations private.
-
-### Usage
-1. Use strings in `part of` directives.
-2. Use adjacent strings to concatenate string literals.
-3. Use collection literals when possible.
-4. Use `whereType()` to filter a collection by type.
-5. Test for `Future<T>` when disambiguating a `FutureOr<T>` whose type argument could be `Object`.
-6. Follow a consistent rule for `var` and `final` on local variables.
-7. Initialize fields at their declaration when possible.
-8. Use initializing formals when possible.
-9. Use `;` instead of `{}` for empty constructor bodies.
-10. Use `rethrow` to rethrow a caught exception.
-11. Override `hashCode` if you override `==`.
-12. Make your `==` operator obey the mathematical rules of equality.
-
-### Documentation
-1. Format comments like sentences.
-2. Use `///` doc comments to document members and types; don't use block comments for documentation.
-3. Prefer writing doc comments for public APIs.
-4. Consider writing doc comments for private APIs.
-5. Consider including explanations of terminology, links, and references in library-level docs.
-6. Start doc comments with a single-sentence summary.
-7. Separate the first sentence of a doc comment into its own paragraph.
-8. Use square brackets in doc comments to refer to in-scope identifiers.
-9. Use prose to explain parameters, return values, and exceptions.
-10. Put doc comments before metadata annotations.
-11. Document why code exists or how it should be used, not just what it does.
-
-### Testing
-1. Write unit tests for business logic.
-2. Write widget tests for UI components.
-3. Aim for good test coverage.
-
-### Widgets
-1. Extract reusable widgets into separate components.
-2. Use `StatelessWidget` when possible.
-3. Keep build methods simple and focused.
-
-### State Management
-1. Choose appropriate state management based on complexity.
-2. Avoid unnecessary `StatefulWidget`s.
-3. Keep state as local as possible.
-
-### Performance
-1. Use `const` constructors when possible.
-2. Avoid expensive operations in build methods.
-3. Implement pagination for large lists.
-
-### Branches
-1. Use `if` statements for conditional branching. The condition must evaluate to a boolean.
-2. `if` statements support optional `else` and `else if` clauses for multiple branches.
-3. Use `if-case` statements to match and destructure a value against a single pattern. Example: `if (pair case [int x, int y]) { ... }`
-4. If the pattern in an `if-case` matches, variables defined in the pattern are in scope for that branch.
-5. If the pattern does not match in an `if-case`, control flows to the `else` branch if present.
-6. Use `switch` statements to match a value against multiple patterns (cases). Each `case` can use any kind of pattern.
-7. When a value matches a `case` pattern in a `switch` statement, the case body executes and control jumps to the end of the switch. `break` is not required.
-8. You can end a non-empty `case` clause with `continue`, `throw`, or `return`.
-9. Use `default` or `_` in a `switch` statement to handle unmatched values.
-10. Empty `case` clauses fall through to the next case. Use `break` to prevent fallthrough.
-11. Use `continue` with a label for non-sequential fallthrough between cases.
-12. Use logical-or patterns (e.g., `case a || b`) to share a body or guard between cases.
-13. Use `switch` expressions to produce a value based on matching cases. Syntax differs from statements: omit `case`, use `=>` for bodies, and separate cases with commas.
-14. In `switch` expressions, the default case must use `_` (not `default`).
-15. Dart checks for exhaustiveness in `switch` statements and expressions, reporting a compile-time error if not all possible values are handled.
-16. To ensure exhaustiveness, use a default (`default` or `_`) case, or switch over enums or sealed types.
-17. Use the `sealed` modifier on a class to enable exhaustiveness checking when switching over its subtypes.
-18. Add a guard clause to a `case` using `when` to further constrain when a case matches. Example: `case pattern when condition:`
-19. Guard clauses can be used in `if-case`, `switch` statements, and `switch` expressions. The guard is evaluated after pattern matching.
-20. If a guard clause evaluates to false, execution proceeds to the next case (does not exit the switch).
-
-### Patterns
-1. Patterns are a syntactic category that represent the shape of values for matching and destructuring.
-2. Pattern matching checks if a value has a certain shape, constant, equality, or type.
-3. Pattern destructuring allows extracting parts of a matched value and binding them to variables.
-4. Patterns can be nested, using subpatterns (outer/inner patterns) for recursive matching and destructuring.
-5. Use wildcard patterns (`_`) to ignore parts of a matched value; use rest elements in list patterns to ignore remaining elements.
-6. Patterns can be used in:
-   - Local variable declarations and assignments
-   - For and for-in loops
-   - If-case and switch-case statements
-   - Control flow in collection literals
-7. Pattern variable declarations start with `var` or `final` and bind new variables from the matched value. Example: `var (a, [b, c]) = ('str', [1, 2]);`
-8. Pattern variable assignments destructure a value and assign to existing variables. Example: `(b, a) = (a, b); // swap values`
-9. Every case clause in `switch` and `if-case` contains a pattern. Any kind of pattern can be used in a case.
-10. Case patterns are refutable; if the pattern doesn't match, execution continues to the next case.
-11. Destructured values in a case become local variables scoped to the case body.
-12. Use logical-or patterns (e.g., `case a || b`) to match multiple alternatives in a single case.
-13. Use logical-or patterns with guards (`when`) to share a body or guard between cases.
-14. Guard clauses (`when`) evaluate a condition after matching; if false, execution proceeds to the next case.
-15. Patterns can be used in for and for-in loops to destructure collection elements (e.g., destructuring `MapEntry` in map iteration).
-16. Object patterns match named object types and destructure their data using getters. Example: `var Foo(:one, :two) = myFoo;`
-8. Constant patterns match if the value is equal to a constant (number, string, bool, named constant, const constructor, const collection, etc.). Use parentheses and `const` for complex expressions.
-9. Variable patterns (`var name`, `final Type name`) bind new variables to matched/destructured values. Typed variable patterns only match if the value has the declared type.
-10. Identifier patterns (`foo`, `_`) act as variable or constant patterns depending on context. `_` always acts as a wildcard and matches/discards any value.
-11. Parenthesized patterns (`(subpattern)`) control pattern precedence and grouping, similar to expressions.
-12. List patterns (`[subpattern1, subpattern2]`) match lists and destructure elements by position. The pattern length must match the list unless a rest element is used.
-13. Rest elements (`...`, `...rest`) in list patterns match arbitrary-length lists or collect unmatched elements into a new list.
-14. Map patterns (`{"key": subpattern}`) match maps and destructure by key. Only specified keys are matched; missing keys throw a `StateError`.
-15. Record patterns (`(subpattern1, subpattern2)`, `(x: subpattern1, y: subpattern2)`) match records by shape and destructure positional/named fields. Field names can be omitted if inferred from variable or identifier patterns.
-16. Object patterns (`ClassName(field1: subpattern1, field2: subpattern2)`) match objects by type and destructure using getters. Extra fields in the object are ignored.
-17. Wildcard patterns (`_`, `Type _`) match any value without binding. Useful for ignoring values or type-checking without binding.
-18. All pattern types can be nested and combined for expressive and precise matching and destructuring.
-
-### Records
-1. Records are anonymous, immutable, aggregate types that bundle multiple objects into a single value.
-2. Records are fixed-sized, heterogeneous, and strongly typed. Each field can have a different type.
-3. Records are real values: store them in variables, nest them, pass to/from functions, and use in lists, maps, and sets.
-4. Record expressions use parentheses with comma-delimited positional and/or named fields, e.g. `('first', a: 2, b: true, 'last')`.
-5. Record type annotations use parentheses with comma-delimited types. Named fields use curly braces: `({int a, bool b})`.
-6. The names of named fields are part of the record's type (shape). Records with different named field names have different types.
-7. Positional field names in type annotations are for documentation only and do not affect the record's type.
-8. Record fields are accessed via built-in getters: positional fields as `$1`, `$2`, etc., and named fields by their name (e.g., `.a`).
-9. Records are immutable: fields do not have setters.
-10. Records are structurally typed: the set, types, and names of fields define the record's type (shape).
-11. Two records are equal if they have the same shape and all corresponding field values are equal. Named field order does not affect equality.
-12. Records automatically define `hashCode` and `==` based on structure and field values.
-13. Use records for functions that return multiple values; destructure with pattern matching: `var (name, age) = userInfo(json);`
-14. Destructure named fields with the colon syntax: `final (:name, :age) = userInfo(json);`
-15. Using records for multiple returns is more concise and type-safe than using classes, lists, or maps.
-16. Use lists of records for simple data tuples with the same shape.
-17. Use type aliases (`typedef`) for record types to improve readability and maintainability.
-18. Changing a record type alias does not guarantee all code using it is still type-safe; only classes provide full abstraction/encapsulation.
-19. Extension types can wrap records but do not provide full abstraction or protection.
-20. Records are best for simple, immutable data aggregation; use classes for abstraction, encapsulation, and behavior.
-
-### Common Flutter Errors
-
-1. If you get a "RenderFlex overflowed" error, check if a `Row` or `Column` contains unconstrained widgets. Fix by wrapping children in `Flexible`, `Expanded`, or by setting constraints.
-2. If you get "Vertical viewport was given unbounded height", ensure `ListView` or similar scrollable widgets inside a `Column` have a bounded height (e.g., wrap with `Expanded` or `SizedBox`).
-3. If you get "An InputDecorator...cannot have an unbounded width", constrain the width of widgets like `TextField` using `Expanded`, `SizedBox`, or by placing them in a parent with width constraints.
-4. If you get a "setState called during build" error, do not call `setState` or `showDialog` directly inside the build method. Trigger dialogs or state changes in response to user actions or after the build completes (e.g., using `addPostFrameCallback`).
-5. If you get "The ScrollController is attached to multiple scroll views", make sure each `ScrollController` is only attached to a single scrollable widget at a time.
-6. If you get a "RenderBox was not laid out" error, check for missing or unbounded constraints in your widget tree. This is often caused by using widgets like `ListView` or `Column` without proper size constraints.
-7. Use the Flutter Inspector and review widget constraints to debug layout issues. Refer to the official documentation on constraints if needed.
-
-### Combining Requests
-1. Use the `Ref` object to combine providers and requests; all providers have access to a `Ref`.
-2. In functional providers, obtain `Ref` as a parameter; in class-based providers, access it as a property of the Notifier.
-3. Prefer using `ref.watch` to combine requests, as it enables reactive and declarative logic that automatically recomputes when dependencies change.
-4. When using `ref.watch` with asynchronous providers, use `.future` to await the value if you need the resolved result, otherwise you will receive an `AsyncValue`.
-5. Avoid calling `ref.watch` inside imperative code (e.g., listener callbacks or Notifier methods); only use it during the build phase of the provider.
-6. Use `ref.listen` as an alternative to `ref.watch` for imperative subscriptions, but prefer `ref.watch` for most cases as `ref.listen` is more error-prone.
-7. It is safe to use `ref.listen` during the build phase; listeners are automatically cleaned up when the provider is recomputed.
-8. Use the return value of `ref.listen` to manually remove listeners when needed.
-9. Use `ref.read` only when you cannot use `ref.watch`, such as inside Notifier methods; `ref.read` does not listen to provider changes.
-10. Be cautious with `ref.read`, as providers not being listened to may destroy their state if not actively watched.
-
-### Auto Dispose & State Disposal
-1. By default, with code generation, provider state is destroyed when the provider stops being listened to for a full frame.
-2. Opt out of automatic disposal by setting `keepAlive: true` (codegen) or using `ref.keepAlive()` (manual).
-3. When not using code generation, state is not destroyed by default; enable `.autoDispose` on providers to activate automatic disposal.
-4. Always enable automatic disposal for providers that receive parameters to prevent memory leaks from unused parameter combinations.
-5. State is always destroyed when a provider is recomputed, regardless of auto dispose settings.
-6. Use `ref.onDispose` to register cleanup logic that runs when provider state is destroyed; do not trigger side effects or modify providers inside `onDispose`.
-7. Use `ref.onCancel` to react when the last listener is removed, and `ref.onResume` when a new listener is added after cancellation.
-8. Call `ref.onDispose` multiple times if needed—once per disposable object—to ensure all resources are cleaned up.
-9. Use `ref.invalidate` to manually force the destruction of a provider's state; if the provider is still listened to, a new state will be created.
-10. Use `ref.invalidateSelf` inside a provider to force its own destruction and immediate recreation.
-11. When invalidating parameterized providers, you can invalidate a specific parameter or all parameter combinations.
-12. Use `ref.keepAlive` for fine-tuned control over state disposal; revert to automatic disposal using the return value of `ref.keepAlive`.
-13. To keep provider state alive for a specific duration, combine a `Timer` with `ref.keepAlive` and dispose after the timer completes.
-14. Consider using `ref.onCancel` and `ref.onResume` to implement custom disposal strategies, such as delayed disposal after a provider is no longer listened to.
-
-### Eager Initialization
-1. Providers are initialized lazily by default; they are only created when first used.
-2. There is no built-in way to mark a provider for eager initialization due to Dart's tree shaking.
-3. To eagerly initialize a provider, explicitly read or watch it at the root of your application (e.g., in a `Consumer` placed directly under `ProviderScope`).
-4. Place the eager initialization logic in a public widget (such as `MyApp`) rather than in `main()` to ensure consistent test behavior.
-5. Eagerly initializing a provider in a dedicated widget will not cause your entire app to rebuild when the provider changes; only the initialization widget will rebuild.
-6. Handle loading and error states for eagerly initialized providers as you would in any `Consumer`, e.g., by returning a loading indicator or error widget.
-7. Use `AsyncValue.requireValue` in widgets to read the data directly and throw a clear exception if the value is not ready, instead of handling loading/error states everywhere.
-8. Avoid creating multiple providers or using overrides solely to hide loading/error states; this adds unnecessary complexity and is discouraged.
-
-### First Provider & Network Requests
-1. Always wrap your app with `ProviderScope` at the root (directly in `runApp`) to enable Riverpod for the entire application.
-2. Place business logic such as network requests inside providers; use `Provider`, `FutureProvider`, or `StreamProvider` depending on the return type.
-3. Providers are lazy—network requests or logic inside a provider are only executed when the provider is first read.
-4. Define provider variables as `final` and at the top level (global scope).
-5. Use code generators like Freezed or json_serializable for models and JSON parsing to reduce boilerplate.
-6. Use `Consumer` or `ConsumerWidget` in your UI to access providers via a `ref` object.
-7. Handle loading and error states in the UI by using the `AsyncValue` API returned by `FutureProvider` and `StreamProvider`.
-8. Multiple widgets can listen to the same provider; the provider will only execute once and cache the result.
-9. Use `ConsumerWidget` or `ConsumerStatefulWidget` to reduce code indentation and improve readability over using a `Consumer` widget inside a regular widget.
-10. To use both hooks and providers in the same widget, use `HookConsumerWidget` or `StatefulHookConsumerWidget` from `flutter_hooks` and `hooks_riverpod`.
-11. Always install and use `riverpod_lint` to enable IDE refactoring and enforce best practices.
-12. Do not put `ProviderScope` inside `MyApp`; it must be the top-level widget passed to `runApp`.
-13. When handling network requests, always render loading and error states gracefully in the UI.
-14. Do not re-execute network requests on widget rebuilds; Riverpod ensures the provider is only executed once unless explicitly invalidated.
-
-### Passing Arguments to Providers
-1. Use provider "families" to pass arguments to providers; add `.family` after the provider type and specify the argument type.
-2. When using code generation, add parameters directly to the annotated function (excluding `ref`).
-3. Always enable `autoDispose` for providers that receive parameters to avoid memory leaks.
-4. When consuming a provider that takes arguments, call it as a function with the desired parameters (e.g., `ref.watch(myProvider(param))`).
-5. You can listen to the same provider with different arguments simultaneously; each argument combination is cached separately.
-6. The equality (`==`) of provider parameters determines caching—ensure parameters have consistent and correct equality semantics.
-7. Avoid passing objects that do not override `==` (such as plain `List` or `Map`) as provider parameters; use `const` collections, custom classes with proper equality, or Dart 3 records.
-8. Use the `provider_parameters` lint rule from `riverpod_lint` to catch mistakes with parameter equality.
-9. For multiple parameters, prefer code generation or Dart 3 records, as records naturally override `==` and are convenient for grouping arguments.
-10. If two widgets consume the same provider with the same parameters, only one computation/network request is made; with different parameters, each is cached separately.
-
-### FAQ & Best Practices
-1. Use `ref.refresh(provider)` when you want to both invalidate a provider and immediately read its new value; use `ref.invalidate(provider)` if you only want to invalidate without reading the value.
-2. Always use the return value of `ref.refresh`; ignoring it will trigger a lint warning.
-3. If a provider is invalidated while not being listened to, it will not update until it is listened to again.
-4. Do not try to share logic between `Ref` and `WidgetRef`; move shared logic into a `Notifier` and call methods on the notifier via `ref.read(yourNotifierProvider.notifier).yourMethod()`.
-5. Prefer `Ref` for business logic and avoid relying on `WidgetRef`, which ties logic to the UI layer.
-6. Extend `ConsumerWidget` instead of using raw `StatelessWidget` when you need access to providers in the widget tree, due to limitations of `InheritedWidget`.
-7. `InheritedWidget` cannot implement a reliable "on change" listener or track when widgets stop listening, which is required for Riverpod's advanced features.
-8. Do not expect to reset all providers at once; instead, make providers that should reset depend on a "user" or "session" provider and reset that dependency.
-9. `hooks_riverpod` and `flutter_hooks` are versioned independently; always add both as dependencies if using hooks.
-10. Riverpod uses `identical` instead of `==` to filter updates for performance reasons, especially with code-generated models; override `updateShouldNotify` on Notifiers to change this behavior.
-11. If you encounter "Cannot use `ref` after the widget was disposed", ensure you check `context.mounted` before using `ref` after an `await` in an async callback.
-
-### Provider Observers (Logging & Error Reporting)
-1. Use a `ProviderObserver` to listen to all events in the provider tree for logging, analytics, or error reporting.
-2. Extend the `ProviderObserver` class and override its methods to respond to provider lifecycle events:
-   - `didAddProvider`: called when a provider is added to the tree.
-   - `didUpdateProvider`: called when a provider is updated.
-   - `didDisposeProvider`: called when a provider is disposed.
-   - `providerDidFail`: called when a synchronous provider throws an error.
-3. Register your observer(s) by passing them to the `observers` parameter of `ProviderScope` (for Flutter apps) or `ProviderContainer` (for pure Dart).
-4. You can register multiple observers if needed by providing a list to the `observers` parameter.
-5. Use observers to integrate with remote error reporting services, log provider state changes, or trigger custom analytics.
-
-### Performing Side Effects
-1. Use Notifiers (`Notifier`, `AsyncNotifier`, etc.) to expose methods for performing side effects (e.g., POST, PUT, DELETE) and modifying provider state.
-2. Always define provider variables as `final` and at the top level (global scope).
-3. Choose the provider type (`NotifierProvider`, `AsyncNotifierProvider`, etc.) based on the return type of your logic.
-4. Use provider modifiers like `autoDispose` and `family` as needed for cache management and parameterization.
-5. Expose public methods on Notifiers for UI to trigger state changes or side effects.
-6. In UI event handlers (e.g., button `onPressed`), use `ref.read` to call Notifier methods; avoid using `ref.watch` for imperative actions.
-7. After performing a side effect, update the UI state by:
-   - Setting the new state directly if the server returns the updated data.
-   - Calling `ref.invalidateSelf()` to refresh the provider and re-fetch data.
-   - Manually updating the local cache if the server does not return the new state.
-8. When updating the local cache, prefer immutable state, but mutable state is possible if necessary.
-9. Always handle loading and error states in the UI when performing side effects.
-10. Use progress indicators and error messages to provide feedback for pending or failed operations.
-11. Be aware of the pros and cons of each update approach:
-    - Direct state update: most up-to-date but depends on server implementation.
-    - Invalidate and refetch: always consistent with server, but may incur extra network requests.
-    - Manual cache update: efficient, but risks state divergence from server.
-12. Use hooks (`flutter_hooks`) or `StatefulWidget` to manage local state (e.g., pending futures) for showing spinners or error UI during side effects.
-13. Do not perform side effects directly inside provider constructors or build methods; expose them via Notifier methods and invoke from the UI layer.
-
-### Testing Providers
-1. Always create a new `ProviderContainer` (unit tests) or `ProviderScope` (widget tests) for each test to avoid shared state between tests. Use a utility like `createContainer()` to set up and automatically dispose containers (see `/references/riverpod/testing/create_container.dart`).
-2. In unit tests, never share `ProviderContainer` instances between tests. Example:
-   ```dart
-   final container = createContainer();
-   expect(container.read(provider), equals('some value'));
-   ```
-3. In widget tests, always wrap your widget tree with `ProviderScope` when using `tester.pumpWidget`. Example:
-   ```dart
-   await tester.pumpWidget(
-     const ProviderScope(child: YourWidgetYouWantToTest()),
-   );
-   ```
-4. Obtain a `ProviderContainer` in widget tests using `ProviderScope.containerOf(BuildContext)`. Example:
-   ```dart
-   final element = tester.element(find.byType(YourWidgetYouWantToTest));
-   final container = ProviderScope.containerOf(element);
-   ```
-5. After obtaining the container, you can read or interact with providers as needed for assertions. Example:
-   ```dart
-   expect(container.read(provider), 'some value');
-   ```
-6. For providers with `autoDispose`, prefer `container.listen` over `container.read` to prevent the provider's state from being disposed during the test.
-7. Use `container.read` to read provider values and `container.listen` to listen to provider changes in tests.
-8. Use the `overrides` parameter on `ProviderScope` or `ProviderContainer` to inject mocks or fakes for providers in your tests.
-9. Use `container.listen` to spy on changes in a provider for assertions or to combine with mocking libraries.
-10. Await asynchronous providers in tests by reading the `.future` property (for `FutureProvider`) or listening to streams.
-11. Prefer mocking dependencies (such as repositories) used by Notifiers rather than mocking Notifiers directly.
-12. If you must mock a Notifier, subclass the original Notifier base class instead of using `implements` or `with Mock`.
-13. Place Notifier mocks in the same file as the Notifier being mocked if code generation is used, to access generated classes.
-14. Use the `overrides` parameter to swap out Notifiers or providers for mocks or fakes in tests.
-15. Keep all test-specific setup and teardown logic inside the test body or test utility functions. Avoid global state.
-16. Ensure your test environment closely matches your production environment for reliable results.

package/#NEW APP PROMPT/flutter-ai-rules/combined/flutter_with_riverpod__under_6K.md

@@ -1,106 +0,0 @@
-# Flutter with Riverpod Rules
-
-## Core Dart Principles
-1. Use class modifiers (`base`, `final`, `sealed`, `interface`) to control class extension.
-2. Override `hashCode` if you override `==`.
-3. Type annotate fields, variables, and parameters when the type isn't obvious.
-4. Use `Future<void>` for asynchronous members without return values.
-5. Use getters for property access and setters for property changes.
-6. Use collection literals when possible.
-7. Use `whereType()` to filter collections by type.
-8. Initialize fields at declaration when possible.
-9. Use initializing formals when possible.
-10. Use `rethrow` to rethrow caught exceptions.
-
-## Riverpod Fundamentals
-1. Always wrap your app with `ProviderScope` at the root (directly in `runApp`).
-2. Define provider variables as `final` and at the top level (global scope).
-3. Use `Consumer` or `ConsumerWidget` in your UI to access providers via a `ref` object.
-4. Use `Provider` for synchronous values that don't change.
-5. Use `StateProvider` for simple state that can be modified from the UI.
-6. Use `FutureProvider` for asynchronous operations like API calls.
-7. Use `StreamProvider` for real-time data streams.
-8. Use `NotifierProvider` for complex state logic with methods.
-9. Use `AsyncNotifierProvider` for complex async state logic with methods.
-10. Always install and use `riverpod_lint` to enable IDE refactoring and enforce best practices.
-11. Providers are lazy—network requests or logic inside a provider are only executed when the provider is first read.
-12. Multiple widgets can listen to the same provider; the provider will only execute once and cache the result.
-13. Obtain the `Ref` object as a parameter in provider functions (or `WidgetRef` in widgets) to access other providers and manage lifecycles.
-
-**Example: Using @riverpod annotation**
-```dart
-@riverpod
-int example(ref) {
-  return 0;
-}
-```
-
-**Example: Using WidgetRef in a widget**
-```dart
-class MyWidget extends ConsumerWidget {
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final value = ref.watch(myProvider);
-    return Text('$value');
-  }
-}
-```
-
-## Ref Object Usage
-1. Use `ref.watch` to reactively depend on other providers; the provider will rebuild when dependencies change.
-2. When using `ref.watch` with asynchronous providers, use `.future` to await the value if you need the resolved result.
-3. Use `ref.listen` to perform side effects when a provider changes.
-4. Use `ref.read` only when you cannot use `ref.watch`, such as inside Notifier methods or event handlers.
-5. Be cautious with `ref.read`, as providers not being listened to may destroy their state if not actively watched.
-
-## State Management with Notifiers
-1. Use Notifiers to expose methods for performing side effects and modifying provider state.
-2. Expose public methods on Notifiers for UI to trigger state changes or side effects.
-3. In UI event handlers (e.g., button `onPressed`), use `ref.read` to call Notifier methods.
-4. After performing a side effect, update the UI state by:
-   - Setting the new state directly if the server returns the updated data.
-   - Calling `ref.invalidateSelf()` to refresh the provider and re-fetch data.
-   - Manually updating the local cache if the server does not return the new state.
-5. Always handle loading and error states in the UI when performing side effects.
-
-## Auto Dispose & State Disposal
-1. By default, with code generation, provider state is destroyed when the provider stops being listened to.
-2. Opt out of automatic disposal by setting `keepAlive: true` (codegen) or using `ref.keepAlive()` (manual).
-3. When not using code generation, enable `.autoDispose` on providers to activate automatic disposal.
-4. Always enable automatic disposal for providers that receive parameters to prevent memory leaks.
-5. Use `ref.onDispose` to register cleanup logic that runs when provider state is destroyed.
-
-## Passing Arguments to Providers
-1. Use provider "families" to pass arguments to providers; add `.family` after the provider type.
-2. When using code generation, add parameters directly to the annotated function (excluding `ref`).
-3. Always enable `autoDispose` for providers that receive parameters to avoid memory leaks.
-4. The equality (`==`) of provider parameters determines caching—ensure parameters have consistent equality.
-5. Avoid passing objects that do not override `==` (such as plain `List` or `Map`) as provider parameters.
-
-## Testing Providers
-1. Always create a new `ProviderContainer` (unit tests) or `ProviderScope` (widget tests) for each test.
-2. In unit tests, never share `ProviderContainer` instances between tests:
-   ```dart
-   final container = createContainer();
-   expect(container.read(provider), equals('some value'));
-   ```
-3. In widget tests, always wrap your widget tree with `ProviderScope`:
-   ```dart
-   await tester.pumpWidget(
-     const ProviderScope(child: YourWidgetYouWantToTest()),
-   );
-   ```
-4. Obtain a `ProviderContainer` in widget tests using `ProviderScope.containerOf(BuildContext)`:
-   ```dart
-   final element = tester.element(find.byType(YourWidgetYouWantToTest));
-   final container = ProviderScope.containerOf(element);
-   expect(container.read(provider), 'some value');
-   ```
-5. Prefer mocking dependencies (such as repositories) used by Notifiers rather than mocking Notifiers directly.
-
-## Dart 3 Modern Features
-1. Use records for grouping values: `var user = ('John', age: 30, isAdmin: true);`.
-2. Access record fields by position (`$1`, `$2`, ...) or by name: `user.$1`, `user.age`.
-3. Use patterns to destructure records, lists, and objects: `var (name, :age) = user;`.
-4. Use switch expressions and pattern matching for concise, exhaustive control flow.
-5. Use sealed classes for exhaustive `switch` and type safety.

package/#NEW APP PROMPT/flutter-ai-rules/rules/bloc.md

@@ -1,94 +0,0 @@
-# Bloc Rules
-
-### Naming Conventions
-1. Name events in the past tense, as they represent actions that have already occurred from the bloc's perspective.
-2. Use the format: `BlocSubject` + optional noun + verb (event). Example: `LoginButtonPressed`, `UserProfileLoaded`
-3. For initial load events, use: `BlocSubjectStarted`. Example: `AuthenticationStarted`
-4. The base event class should be named: `BlocSubjectEvent`.
-5. Name states as nouns, since a state is a snapshot at a particular point in time.
-6. When using subclasses for states, use the format: `BlocSubject` + `Initial` | `Success` | `Failure` | `InProgress`. Example: `LoginInitial`, `LoginSuccess`, `LoginFailure`, `LoginInProgress`
-7. For single-class states, use: `BlocSubjectState` with a `BlocSubjectStatus` enum (`initial`, `success`, `failure`, `loading`). Example: `LoginState` with `LoginStatus.initial`
-8. The base state class should always be named: `BlocSubjectState`.
-
-### Modeling State
-1. Extend `Equatable` for all state classes to enable value equality.
-2. Annotate state classes with `@immutable` to enforce immutability.
-3. Implement a `copyWith` method in state classes for easy state updates.
-4. Use `const` constructors for state classes when possible.
-5. Use a single concrete class with a status enum for simple, non-exclusive states or when many properties are shared.
-6. In the single-class approach, make properties nullable and handle them based on the current status.
-7. Use a sealed class with subclasses for well-defined, exclusive states.
-8. Store shared properties in the sealed base class; keep state-specific properties in subclasses.
-9. Use exhaustive `switch` statements to handle all possible state subclasses.
-10. Prefer the sealed class approach for type safety and exhaustiveness; prefer the single-class approach for conciseness and flexibility.
-11. Always pass all relevant properties to the `props` getter when using Equatable in state classes.
-12. When using Equatable, copy List or Map properties with `List.of` or `Map.of` to ensure value equality.
-13. To retain previous data after an error, use a single state class with nullable data and error fields.
-14. Emit a new instance of the state each time you want the UI to update; do not reuse the same instance.
-
-### Bloc Concepts
-1. Use `Cubit` for simple state management without events; use `Bloc` for more complex, event-driven state management.
-2. Define the initial state by passing it to the superclass in both `Cubit` and `Bloc`.
-3. Only use the `emit` method inside a `Cubit` or `Bloc`; do not call it externally.
-4. UI components should listen to state changes and update only in response to new states.
-5. Duplicate states (`state == nextState`) are ignored; no state change will occur.
-6. Override `onChange` in `Cubit` or `Bloc` to observe all state changes.
-7. Use a custom `BlocObserver` to observe all state changes and errors globally.
-8. Override `onError` in both `Cubit`/`Bloc` and `BlocObserver` for error handling.
-9. Add events to a `Bloc` in response to user actions or lifecycle events.
-10. Use `onTransition` in `Bloc` to observe the full transition (event, current state, next state).
-11. Use event transformers (e.g., debounce, throttle) in `Bloc` for advanced event processing.
-12. Prefer `Cubit` for simplicity and less boilerplate; prefer `Bloc` for traceability and advanced event handling.
-13. If unsure, start with `Cubit` and refactor to `Bloc` if needed as requirements grow.
-14. Initialize `BlocObserver` in `main.dart` for debugging and logging.
-15. Always keep business logic out of UI widgets; only interact with cubits/blocs via events or public methods.
-16. Internal events in a bloc should be private and only used for real-time updates from repositories.
-17. Use custom event transformers for internal events if needed.
-18. When exposing public methods on a cubit, only use them to trigger state changes and return `void` or `Future<void>`.
-19. For blocs, avoid exposing custom public methods; trigger state changes by adding events.
-20. When using `BlocProvider.of(context)`, call it within a child `BuildContext`, not the same context where the bloc was provided.
-
-### Architecture
-1. Separate your features into three layers: Presentation, Business Logic, and Data.
-2. The Data Layer is responsible for retrieving and manipulating data from sources such as databases or network requests.
-3. Structure the Data Layer into repositories (wrappers around data providers) and data providers (perform CRUD operations).
-4. The Business Logic Layer responds to input from the presentation layer and communicates with repositories to build new states.
-5. The Presentation Layer renders UI based on bloc states and handles user input and lifecycle events.
-6. Inject repositories into blocs via constructors; blocs should not directly access data providers.
-7. Avoid direct bloc-to-bloc communication to prevent tight coupling.
-8. To coordinate between blocs, use BlocListener in the presentation layer to listen to one bloc and add events to another.
-9. For shared data, inject the same repository into multiple blocs; let each bloc listen to repository streams independently.
-10. Always strive for loose coupling between architectural layers and components.
-11. Structure your project consistently and intentionally; there is no single right way.
-
-### Flutter Bloc Concepts
-1. Use `BlocBuilder` to rebuild widgets in response to bloc or cubit state changes; the builder function must be pure.
-2. Use `BlocListener` to perform side effects (e.g., navigation, dialogs) in response to state changes.
-3. Use `BlocConsumer` when you need both `BlocBuilder` and `BlocListener` functionality in a single widget.
-4. Use `BlocProvider` to provide blocs to widget subtrees via dependency injection.
-5. Use `MultiBlocProvider` to provide multiple blocs and avoid deeply nested providers.
-6. Use `BlocSelector` to rebuild widgets only when a selected part of the state changes.
-7. Use `MultiBlocListener` to listen for state changes and trigger side effects; avoid nesting listeners by using `MultiBlocListener`.
-8. Use `RepositoryProvider` to provide repositories or services to the widget tree.
-9. Use `MultiRepositoryProvider` to provide multiple repositories and avoid nesting.
-10. Use `context.read<T>()` to access a bloc or repository without listening for changes (e.g., in callbacks).
-11. Use `context.watch<T>()` inside the build method to listen for changes and trigger rebuilds.
-12. Use `context.select<T, R>()` to listen for changes in a specific part of a bloc’s state.
-13. Avoid using `context.watch` or `context.select` at the root of the build method to prevent unnecessary rebuilds.
-14. Prefer `BlocBuilder` and `BlocSelector` over `context.watch` and `context.select` for explicit rebuild scoping.
-15. Scope rebuilds using `Builder` when using `context.watch` or `context.select` for multiple blocs.
-16. Handle all possible cubit/bloc states explicitly in the UI (e.g., empty, loading, error, populated).
-
-### Testing
-1. Add the `test` and `bloc_test` packages to your dev dependencies for bloc testing.
-2. Organize tests into groups to share setup and teardown logic.
-3. Create a dedicated test file (e.g., `counter_bloc_test.dart`) for each bloc.
-4. Import the `test` and `bloc_test` packages in your test files.
-5. Use `setUp` to initialize bloc instances before each test and `tearDown` to clean up after tests.
-6. Test the bloc’s initial state before testing transitions.
-7. Use the `blocTest` function to test bloc state transitions in response to events.
-8. Assert the expected sequence of emitted states for each bloc event.
-9. Keep tests concise, focused, and easy to maintain to ensure confidence in refactoring.
-10. Mock cubits/blocs in widget tests to verify UI behavior for all possible states.
-
-TOTAL CHAR COUNT:     7810