kuhyx/todo-app
1
0
Fork 0
mirror of https://github.com/kuhyx/todo-app.git synced 2026-07-04 13:23:15 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add Flutter/Dart agent skills and AI rules for Claude Code

Browse Source 
Installs the official flutter/skills and dart-lang/skills packs into
.agents/skills/ and appends Flutter's AI rules.md to CLAUDE.md, so
Claude Code has task-specific playbooks alongside the dart MCP server
(registered separately at user scope).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013NqCvrbFnoNNmqCwZKntBK
This commit is contained in:
Krzysztof kuhy Rudnicki 2026-06-22 22:53:03 +02:00
parent dac6bd6737
commit f91311f3f9
23 changed files with 4898 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
.agents/skills/dart-add-unit-test/SKILL.md Normal file
View File

@ -0,0 +1,122 @@
---
name: dart-add-unit-test
description: Write and organize unit tests for functions, methods, and classes using `package:test`. Use when creating new logic or fixing bugs to ensure code remains correct and regression-free.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 24 Apr 2026 15:07:58 GMT
---
# Testing Dart and Flutter Applications
## Contents
- [Structuring Test Files](#structuring-test-files)
- [Writing Tests](#writing-tests)
- [Executing Tests](#executing-tests)
- [Test Implementation Workflow](#test-implementation-workflow)
- [Examples](#examples)
## Structuring Test Files
Organize test files to mirror the `lib` directory structure to maintain predictability.
* Place all test code within the `test` directory at the root of the package.
* Append `_test.dart` to the end of all test file names (e.g., `lib/src/utils.dart` should be tested in `test/src/utils_test.dart`).
* If writing integration tests, place them in an `integration_test` directory at the root of the package.
## Writing Tests
Utilize `package:test` as the standard testing library for Dart applications.
* Import `package:test/test.dart` (or `package:flutter_test/flutter_test.dart` for Flutter).
* Group related tests using the `group()` function to provide shared context.
* Define individual test cases using the `test()` function.
* Validate outcomes using the `expect()` function alongside matchers (e.g., `equals()`, `isTrue`, `throwsA()`).
* Write asynchronous tests using standard `async`/`await` syntax. The test runner automatically waits for the `Future` to complete.
* Manage test setup and teardown using `setUp()` and `tearDown()` callbacks.
* If testing code that relies on dependency injection, use `package:mockito` alongside `package:test` to generate mock objects, configure fixed scenarios, and verify interactions.
## Executing Tests
Select the appropriate test runner based on the project type and test location.
* If working on a pure Dart project, execute tests using the `dart test` command.
* If working on a Flutter project, execute tests using the `flutter test` command.
* If running integration tests, explicitly specify the directory path, as the default runner ignores it: `dart test integration_test` or `flutter test integration_test`.
## Test Implementation Workflow
Follow this sequential workflow when implementing new test suites. Copy the checklist to track your progress.
### Task Progress
- [ ] 1. Create the test file in the `test/` directory, ensuring the `_test.dart` suffix.
- [ ] 2. Import `package:test/test.dart` and the target library.
- [ ] 3. Define a `main()` function.
- [ ] 4. Initialize shared resources or mocks using `setUp()`.
- [ ] 5. Write `test()` cases grouped by functionality using `group()`.
- [ ] 6. Execute the test suite using the appropriate CLI command.
- [ ] 7. **Feedback Loop**: Run test -> Review stack trace for failures -> Fix implementation or assertions -> Re-run until passing.
## Examples
### Standard Unit Test Suite
Demonstrates grouping, setup, synchronous, and asynchronous testing.
```dart
import 'package:test/test.dart';
import 'package:my_package/calculator.dart';
void main() {
group('Calculator', () {
late Calculator calc;
setUp(() {
calc = Calculator();
});
test('adds two numbers correctly', () {
expect(calc.add(2, 3), equals(5));
});
test('handles asynchronous operations', () async {
final result = await calc.fetchRemoteValue();
expect(result, isNotNull);
expect(result, greaterThan(0));
});
});
}
```
### Mocking with Mockito
Demonstrates configuring a mock object for dependency injection testing.
```dart
import 'package:test/test.dart';
import 'package:mockito/mockito.dart';
import 'package:mockito/annotations.dart';
import 'package:my_package/api_client.dart';
import 'package:my_package/data_service.dart';
// Generate the mock using build_runner: dart run build_runner build
@GenerateNiceMocks([MockSpec<ApiClient>()])
import 'data_service_test.mocks.dart';
void main() {
group('DataService', () {
late MockApiClient mockApiClient;
late DataService dataService;
setUp(() {
mockApiClient = MockApiClient();
dataService = DataService(apiClient: mockApiClient);
});
test('returns parsed data on successful API call', () async {
// Configure the mock
when(mockApiClient.get('/data')).thenAnswer((_) async => '{"id": 1}');
// Execute the system under test
final result = await dataService.fetchData();
// Verify outcomes and interactions
expect(result.id, equals(1));
verify(mockApiClient.get('/data')).called(1);
});
});
}
```

185
.agents/skills/dart-build-cli-app/SKILL.md Normal file
View File

@ -0,0 +1,185 @@
---
name: dart-build-cli-app
description: Entrypoint structure, exit codes, cross-platform scripts. Use when building command line utilities, scripts, or applications.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 04 May 2026 17:41:00 GMT
---
# Building Dart CLI Applications
## Contents
- [Project Setup & Architecture](#project-setup--architecture)
- [Argument Parsing & Command Routing](#argument-parsing--command-routing)
- [Execution & Error Handling](#execution--error-handling)
- [Testing CLI Applications](#testing-cli-applications)
- [Compilation & Distribution](#compilation--distribution)
- [Workflows](#workflows)
- [Examples](#examples)
## Project Setup & Architecture
Initialize new CLI projects using the official Dart template to ensure standard directory structures.
* Run `dart create -t cli <project_name>` to scaffold a console application with basic argument parsing.
* Place executable entry points (files containing `main()`) exclusively in the `bin/` directory.
* Place internal implementation logic in `lib/src/` and expose public APIs via `lib/<project_name>.dart`.
* Enforce formatting in CI environments by running `dart format . --set-exit-if-changed`. This returns exit code 1 if formatting violations exist.
## Argument Parsing & Command Routing
Import the `args` package to manage command-line arguments, flags, and subcommands.
* If building a simple script: Use `ArgParser` directly to define flags (`addFlag`) and options (`addOption`).
* If building a complex, multi-command CLI (like `git`): Implement `CommandRunner` and extend `Command` for each subcommand.
* Define global arguments on the `CommandRunner.argParser` and command-specific arguments on the individual `Command.argParser`.
* Catch `UsageException` to gracefully handle invalid arguments and display the automatically generated help text.
* **Validate Help Text Accuracy**: Ensure the help text provides all necessary information to run the tool. If the help text references a compiled executable name, and the user needs to add it to their PATH to run it that way, provide clear instructions on how to do so in the help text or description.
## Execution & Error Handling
Leverage the `io` and `stack_trace` packages to build robust, production-ready CLI tools.
* Use the `io` package's `ExitCode` enum to return standard POSIX exit codes (e.g., `ExitCode.success.code`, `ExitCode.usage.code`).
* Use `sharedStdIn` from the `io` package if multiple asynchronous listeners need sequential access to standard input.
* Wrap the application execution in `Chain.capture()` from the `stack_trace` package to track asynchronous stack chains.
* Format output stack traces using `Trace.terse` or `Chain.terse` to strip noisy core library frames and present readable errors to the user.
* **Do not swallow exceptions** in lower-level logic or storage classes unless recovery is possible. Let them bubble up or rethrow them so higher-level commands know operations failed.
* **Fail fast and with non-zero exit codes**: Ensure operation failures result in descriptive error messages to `stderr` and appropriate non-zero exit codes (e.g., using `exit(1)` or triggering a 64 exit code after a caught `UsageException`).
## Testing CLI Applications
> [!IMPORTANT]
> **All new commands and significant features must be covered by automated tests.** Manual verification is not sufficient for testing logic. However, manual verification of help text and user experience (UX) is still required to ensure the interface is intuitive and correct.
Use `test_process` and `test_descriptor` to write high-fidelity integration tests for your CLI.
* Define expected filesystem states using `test_descriptor` (`d.dir`, `d.file`).
* Create the mock filesystem before execution using `await d.Descriptor.create()`.
* Spawn the CLI process using `TestProcess.start('dart', ['run', 'bin/cli.dart', ...args])`.
* Validate standard output and error streams using `StreamQueue` matchers (e.g., `emitsThrough`, `emits`).
* Assert the final exit code using `await process.shouldExit(0)`.
* Validate resulting filesystem mutations using `await d.Descriptor.validate()`.
## Compilation & Distribution
Select the appropriate compilation target based on your distribution requirements.
* **If testing locally during development:** Use `dart run bin/cli.dart`. This uses the JIT compiler for rapid iteration.
* **If bundling code assets and dynamic libraries:** Use `dart build cli`. This runs build hooks and outputs to `build/cli/_/bundle/`.
* **If distributing a standalone native executable:** Use `dart compile exe bin/cli.dart -o <output_path>`. This bundles the Dart runtime and machine code into a single file.
* **If distributing multiple apps with strict disk space limits:** Use `dart compile aot-snapshot bin/cli.dart`. Run the resulting `.aot` file using `dartaotruntime`.
<details>
<summary>Cross-Compilation Targets (Linux Only)</summary>
Dart supports cross-compiling to Linux from macOS, Windows, or Linux hosts.
Use the `--target-os` and `--target-arch` flags with `dart compile exe` or `dart compile aot-snapshot`.
* `--target-os=linux` (Only Linux is currently supported as a cross-compilation target)
* `--target-arch=arm64` (64-bit ARM)
* `--target-arch=x64` (x86-64)
* `--target-arch=arm` (32-bit ARM)
* `--target-arch=riscv64` (64-bit RISC-V)
Example: `dart compile exe --target-os=linux --target-arch=arm64 bin/cli.dart`
</details>
## Workflows
### Task Progress: Implement a New CLI Command
- [ ] Create a new class extending `Command` in `lib/src/commands/`.
- [ ] Define the `name` and `description` properties.
- [ ] Register command-specific flags in the constructor using `argParser.addFlag()` or `argParser.addOption()`.
- [ ] Implement the `run()` method with the core logic.
- [ ] Register the new command in the `CommandRunner` instance in `bin/cli.dart` using `addCommand()`.
- [ ] Create tests for the new command in the `test/` directory using `test_process` or standard tests.
- [ ] Run validator -> Execute `dart run bin/cli.dart help <command_name>` to verify help text generation.
- [ ] Verify final UX: Compile the application using `dart compile exe` and run the resulting executable to verify the target user experience (e.g., `./bin/cli <command>`).
### Task Progress: Compile and Release Native Executable
- [ ] Run validator -> Execute `dart format . --set-exit-if-changed` to ensure code formatting.
- [ ] Run validator -> Execute `dart analyze` to ensure no static analysis errors.
- [ ] Run validator -> Execute `dart test` to pass all integration tests.
- [ ] Compile for host OS: `dart compile exe bin/cli.dart -o build/cli-host`
- [ ] Compile for Linux (if host is macOS/Windows): `dart compile exe --target-os=linux --target-arch=x64 bin/cli.dart -o build/cli-linux-x64`
## Examples
### Example: CommandRunner Implementation
```dart
import 'dart:io';
import 'package:args/command_runner.dart';
import 'package:stack_trace/stack_trace.dart';
class CommitCommand extends Command {
@override
final String name = 'commit';
@override
final String description = 'Record changes to the repository.';
CommitCommand() {
argParser.addFlag('all', abbr: 'a', help: 'Commit all changed files.');
}
@override
Future<void> run() async {
final commitAll = argResults?['all'] as bool? ?? false;
print('Committing... (All: $commitAll)');
}
}
void main(List<String> args) {
Chain.capture(() async {
final runner = CommandRunner('dgit', 'Distributed version control.')
..addCommand(CommitCommand());
await runner.run(args);
}, onError: (error, chain) {
if (error is UsageException) {
stderr.writeln(error.message);
stderr.writeln(error.usage);
exit(64); // ExitCode.usage.code
} else {
stderr.writeln('Fatal error: $error');
stderr.writeln(chain.terse);
exit(1);
}
});
}
```
### Example: Integration Testing with Subprocesses
```dart
import 'package:test/test.dart';
import 'package:test_process/test_process.dart';
import 'package:test_descriptor/test_descriptor.dart' as d;
void main() {
test('CLI formats output correctly and modifies filesystem', () async {
// 1. Setup mock filesystem
await d.dir('project', [
d.file('config.json', '{"key": "value"}')
]).create();
// 2. Spawn the CLI process
final process = await TestProcess.start(
'dart',
['run', 'bin/cli.dart', 'process', '--path', '${d.sandbox}/project']
);
// 3. Validate stdout stream
await expectLater(process.stdout, emitsThrough('Processing complete.'));
// 4. Validate exit code
await process.shouldExit(0);
// 5. Validate filesystem mutations
await d.dir('project', [
d.file('config.json', '{"key": "value"}'),
d.file('output.log', 'Success')
]).validate();
});
}
```

141
.agents/skills/dart-collect-coverage/SKILL.md Normal file
View File

@ -0,0 +1,141 @@
---
name: dart-collect-coverage
description: Collect coverage using the coverage packge and create an LCOV report
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 24 Apr 2026 15:14:32 GMT
---
# Implementing Dart and Flutter Test Coverage
## Contents
- [Testing Fundamentals](#testing-fundamentals)
- [Coverage Directives](#coverage-directives)
- [Workflow: Configuring and Generating Coverage Reports](#workflow-configuring-and-generating-coverage-reports)
- [Workflow: Advanced Manual Coverage Collection](#workflow-advanced-manual-coverage-collection)
- [Examples](#examples)
## Testing Fundamentals
Structure your test suites using the standard Dart testing paradigms. Use `package:test` for Dart projects and `flutter_test` for Flutter projects.
- **Unit Tests:** Verify individual functions, methods, or classes.
- **Component/Widget Tests:** Verify component behavior, layout, and interaction using mock objects (`package:mockito`).
- **Integration Tests:** Verify entire app flows on simulated or real devices.
## Coverage Directives
Exclude specific lines, blocks, or entire files from coverage metrics using inline comments. Pass the `--check-ignore` flag during formatting to enforce these directives.
- Ignore a single line: `// coverage:ignore-line`
- Ignore a block of code: `// coverage:ignore-start` and `// coverage:ignore-end`
- Ignore an entire file: `// coverage:ignore-file`
## Workflow: Configuring and Generating Coverage Reports
Follow this sequential workflow to add the coverage package, execute tests, and generate an LCOV report.
**Task Progress Checklist:**
- [ ] 1. Add `coverage` as a `dev_dependency`.
- [ ] 2. Execute the automated coverage script.
- [ ] 3. Validate the LCOV output.
### 1. Add Dependencies
Add the `coverage` package as a `dev_dependency` to your project. Do not add it to standard dependencies.
If working in a standard Dart project:
```bash
dart pub add dev:coverage
```
If working in a Flutter project:
```bash
flutter pub add dev:coverage
```
### 2. Collect Coverage and Generate LCOV
Use the bundled `test_with_coverage` script. This script automatically runs all tests, collects the JSON coverage data from the Dart VM, and formats it into an LCOV report.
```bash
dart run coverage:test_with_coverage
```
*Note: If working within a Dart workspace (monorepo), specify the test directories explicitly (e.g., `dart run coverage:test_with_coverage -- pkgs/foo/test pkgs/bar/test`).*
### 3. Feedback Loop: Validate Output
**Run validator -> review errors -> fix:**
1. Verify that the `coverage/` directory was created in the project root.
2. Ensure `coverage/coverage.json` (raw data) and `coverage/lcov.info` (formatted report) exist.
3. If coverage is missing for specific files, ensure they are imported and executed by your test files, or add `// coverage:ignore-file` if they are intentionally excluded.
## Workflow: Advanced Manual Coverage Collection
If you require granular control over the VM service, isolate pausing, or need branch/function-level coverage, use the manual collection workflow.
**Task Progress Checklist:**
- [ ] 1. Run tests with VM service enabled.
- [ ] 2. Collect raw JSON coverage.
- [ ] 3. Format JSON to LCOV.
### 1. Run Tests with VM Service
Execute tests while pausing isolates on exit and exposing the VM service on a specific port (e.g., 8181).
```bash
dart run --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=8181 test &
```
### 2. Collect Raw Coverage
Extract the coverage data from the running VM service and output it to a JSON file.
```bash
dart run coverage:collect_coverage --wait-paused --uri=http://127.0.0.1:8181/ -o coverage/coverage.json --resume-isolates
```
*Optional: Append `--function-coverage` and `--branch-coverage` to gather deeper metrics (requires Dart VM 2.17.0+).*
### 3. Format to LCOV
Convert the raw JSON data into the standard LCOV format.
```bash
dart run coverage:format_coverage --packages=.dart_tool/package_config.json --lcov -i coverage/coverage.json -o coverage/lcov.info --check-ignore
```
## Examples
### Example: `pubspec.yaml` Configuration
Ensure your `pubspec.yaml` reflects the `coverage` package strictly under `dev_dependencies`.
```yaml
name: my_dart_app
environment:
sdk: ^3.0.0
dependencies:
path: ^1.8.0
dev_dependencies:
test: ^1.24.0
coverage: ^1.15.0
```
### Example: Applying Ignore Directives
Use ignore directives to prevent generated code or untestable edge cases from lowering coverage scores.
```dart
// coverage:ignore-file
import 'package:meta/meta.dart';
class SystemConfig {
final String env;
SystemConfig(this.env);
// coverage:ignore-start
void legacyInit() {
print('Deprecated initialization');
}
// coverage:ignore-end
bool isProduction() {
if (env == 'prod') return true;
return false; // coverage:ignore-line
}
}
```

166
.agents/skills/dart-fix-runtime-errors/SKILL.md Normal file
View File

@ -0,0 +1,166 @@
---
name: dart-fix-runtime-errors
description: Uses get_runtime_errors and lsp to fetch an active stack trace, locate the failing line, apply a fix, and verify resolution via hot_reload.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 24 Apr 2026 15:13:22 GMT
---
# Resolving Dart Static Analysis Errors
## Contents
- [Core Concepts & Guidelines](#core-concepts--guidelines)
- [Type System & Soundness](#type-system--soundness)
- [Null Safety](#null-safety)
- [Error Handling](#error-handling)
- [Workflows](#workflows)
- [Workflow: Static Analysis Resolution](#workflow-static-analysis-resolution)
- [Examples](#examples)
## Core Concepts & Guidelines
### Type System & Soundness
Enforce Dart's sound type system to prevent runtime invalid states.
* **Method Overrides:** Maintain sound return types (covariant) and parameter types (contravariant). Never tighten a parameter type in a subclass unless explicitly marked with the `covariant` keyword.
* **Generics & Collections:** Add explicit type annotations to generic classes (e.g., `List<T>`, `Map<K, V>`). Never assign a `List<dynamic>` to a typed list (e.g., `List<Cat>`).
* **Downcasting:** Avoid implicit downcasts from `dynamic`. Use explicit casts (e.g., `as List<Cat>`) when necessary, but ensure the underlying runtime type matches to prevent `TypeError` exceptions.
* **Strict Casts:** Enable `strict-casts: true` in `analysis_options.yaml` under `analyzer: language:` to force explicit casting and catch implicit downcast errors at compile time.
### Null Safety
Eliminate static errors related to null safety by correctly managing variable initialization and nullability.
* **Modifiers:** Apply `?` for nullable types, `!` for null assertions, and `required` for named parameters that cannot be null.
* **Late Initialization:** Use the `late` keyword for non-nullable variables guaranteed to be initialized before use. Apply this specifically to top-level or instance variables where Dart's control flow analysis cannot definitively prove initialization.
* **Wildcards:** Use the `_` wildcard variable (Dart 3.7+) for non-binding local variables or parameters to avoid unused variable warnings.
### Error Handling
Distinguish between recoverable exceptions and unrecoverable errors.
* **Catching:** Catch `Exception` subtypes for recoverable failures.
* **Errors:** Never explicitly catch `Error` or its subtypes (e.g., `TypeError`, `ArgumentError`). Errors indicate programming bugs that must be fixed, not caught. Enforce this by enabling the `avoid_catching_errors` linter rule.
* **Rethrowing:** Use `rethrow` inside a `catch` block to propagate an exception while preserving its original stack trace.
## Workflows
### Workflow: Static Analysis Resolution
Use this sequential workflow to identify, fix, and verify static analysis errors in a Dart project. Copy the checklist to track your progress.
**Task Progress:**
- [ ] 1. Run static analyzer.
- [ ] 2. Apply automated fixes.
- [ ] 3. Resolve remaining errors manually.
- [ ] 4. Verify fixes (Feedback Loop).
**1. Run static analyzer**
Execute the Dart analyzer to identify all static errors in the target directory or file.
```bash
dart analyze . --fatal-infos
```
**2. Apply automated fixes**
Use the `dart fix` tool to automatically resolve standard linting and analysis issues.
```bash
# Preview changes
dart fix --dry-run
# Apply changes
dart fix --apply
```
**3. Resolve remaining errors manually**
Review the remaining analyzer output and apply conditional logic based on the error type:
* **If the error is a Null Safety issue (e.g., "Property cannot be accessed on a nullable receiver"):**
* Verify if the variable can logically be null.
* If yes, use optional chaining (`?.`) or provide a fallback (`??`).
* If no, and initialization is guaranteed elsewhere, mark the declaration with `late`.
* **If the error is a Type Mismatch (e.g., "The argument type 'List<dynamic>' can't be assigned..."):**
* Trace the variable's initialization.
* Add explicit generic type annotations to the instantiation (e.g., `<int>[]` instead of `[]`).
* **If the error is an Invalid Override (e.g., "The parameter type doesn't match the overridden method"):**
* Widen the parameter type to match the superclass, OR
* Add the `covariant` keyword to the parameter if tightening the type is intentionally required by the domain logic.
**4. Verify fixes (Feedback Loop)**
Run the validator. Review errors. Fix.
```bash
dart analyze .
dart test
```
* **If `dart analyze` reports errors:** Return to Step 3.
* **If `dart test` fails with a `TypeError`:** You have introduced an invalid explicit cast (`as T`) or accessed an uninitialized `late` variable. Locate the runtime failure and correct the type hierarchy or initialization order.
## Examples
### Example: Fixing Dynamic List Assignments
**Input (Fails Static Analysis):**
```dart
void printInts(List<int> a) => print(a);
void main() {
final list = []; // Inferred as List<dynamic>
list.add(1);
list.add(2);
printInts(list); // Error: List<dynamic> can't be assigned to List<int>
}
```
**Output (Passes Static Analysis):**
```dart
void printInts(List<int> a) => print(a);
void main() {
final list = <int>[]; // Explicitly typed
list.add(1);
list.add(2);
printInts(list);
}
```
### Example: Fixing Method Overrides (Contravariance)
**Input (Fails Static Analysis):**
```dart
class Animal {
void chase(Animal a) {}
}
class Cat extends Animal {
@override
void chase(Mouse a) {} // Error: Tightening parameter type
}
```
**Output (Passes Static Analysis):**
```dart
class Animal {
void chase(Animal a) {}
}
class Cat extends Animal {
@override
void chase(covariant Mouse a) {} // Explicitly marked covariant
}
```
### Example: Fixing Null Safety with `late`
**Input (Fails Static Analysis):**
```dart
class Thermometer {
String temperature; // Error: Non-nullable instance field must be initialized
void read() {
temperature = '20C';
}
}
```
**Output (Passes Static Analysis):**
```dart
class Thermometer {
late String temperature; // Defers initialization check to runtime
void read() {
temperature = '20C';
}
}
```

155
.agents/skills/dart-generate-test-mocks/SKILL.md Normal file
View File

@ -0,0 +1,155 @@
---
name: dart-generate-test-mocks
description: Define and generate mock objects for external dependencies using `package:mockito` and `build_runner`. Use when unit testing classes that depend on complex external services like APIs or databases.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 24 Apr 2026 15:13:58 GMT
---
# Testing and Mocking Dart Applications
## Contents
- [Structuring Code for Testability](#structuring-code-for-testability)
- [Managing Dependencies](#managing-dependencies)
- [Generating Mocks](#generating-mocks)
- [Implementing Unit Tests](#implementing-unit-tests)
- [Workflow: Creating and Running Mocked Tests](#workflow-creating-and-running-mocked-tests)
- [Examples](#examples)
## Structuring Code for Testability
Design Dart classes to support dependency injection. Isolate complex external dependencies (like API clients or databases) so they can be replaced with mock objects during testing.
- Inject external services (e.g., `http.Client`) through class constructors.
- Represent URLs strictly as `Uri` objects using `Uri.parse(string)`.
- Utilize Dart's object-oriented features (classes, mixins) to define clear interfaces for external interactions.
## Managing Dependencies
Configure the `pubspec.yaml` file with the necessary testing and code generation packages.
- Add runtime dependencies (e.g., `package:http`) using `dart pub add http`.
- Add testing dependencies using `dart pub add dev:test dev:mockito dev:build_runner`.
- Import HTTP libraries with a prefix to avoid namespace collisions: `import 'package:http/http.dart' as http;`.
## Generating Mocks
Use `package:mockito` and `build_runner` to automatically generate mock classes for fixed scenarios and behavior verification.
- Always use the `@GenerateNiceMocks` annotation (preferable to `@GenerateMocks` to avoid missing stub exceptions).
- Place the annotation in the test file, passing a list of `MockSpec<Type>()` objects.
- Import the generated file using the `.mocks.dart` extension.
- Execute `build_runner` to generate the mock files: `dart run build_runner build`.
## Implementing Unit Tests
Isolate the system under test using the generated mock objects. Use `package:test` to structure the test suite.
- **Stubbing:** Configure mock behavior before interacting with the system under test.
- Use `when(mock.method()).thenReturn(value)` for synchronous methods.
- **CRITICAL:** Always use `thenAnswer((_) async => value)` for methods returning a `Future` or `Stream`. Never use `thenReturn` for asynchronous returns.
- **Verification:** Assert that the system under test interacted with the mock object correctly.
- Use `verify(mock.method()).called(1)` to check exact invocation counts.
- Use argument matchers like `any`, `anyNamed`, or `captureAny` for flexible verification.
## Workflow: Creating and Running Mocked Tests
Use the following checklist to implement and verify mocked unit tests.
### Task Progress
- [ ] 1. Identify the external dependency to mock (e.g., `http.Client`).
- [ ] 2. Inject the dependency into the target class constructor.
- [ ] 3. Create a test file (e.g., `target_test.dart`) and add `@GenerateNiceMocks([MockSpec<Dependency>()])`.
- [ ] 4. Add the `part` or `import` directive for the generated `.mocks.dart` file.
- [ ] 5. Run `dart run build_runner build` to generate the mock classes.
- [ ] 6. Write the test cases using `group()` and `test()`.
- [ ] 7. Stub required behaviors using `when()`.
- [ ] 8. Execute the target method.
- [ ] 9. Verify interactions using `verify()` and assert outcomes using `expect()`.
- [ ] 10. Run the test suite using `dart test`.
### Feedback Loop: Test Failures
If tests fail or `build_runner` encounters errors:
1. **Run validator:** Execute `dart test` or `dart run build_runner build`.
2. **Review errors:** Check for missing stubs, mismatched argument matchers, or syntax errors in the generated files.
3. **Fix:**
- If a mock method throws an unexpected null error, ensure you used `@GenerateNiceMocks`.
- If an async stub throws an `ArgumentError`, change `thenReturn` to `thenAnswer`.
- If `build_runner` fails, ensure the `.mocks.dart` import matches the file name exactly.
4. Repeat until all tests pass.
## Examples
### High-Fidelity Mocking and Testing Example
**1. System Under Test (`lib/api_service.dart`)**
```dart
import 'dart:convert';
import 'package:http/http.dart' as http;
class ApiService {
final http.Client client;
ApiService(this.client);
Future<String> fetchData(String urlString) async {
final uri = Uri.parse(urlString);
final response = await client.get(uri);
if (response.statusCode == 200) {
return jsonDecode(response.body)['data'];
} else {
throw Exception('Failed to load data');
}
}
}
```
**2. Test Implementation (`test/api_service_test.dart`)**
```dart
import 'package:test/test.dart';
import 'package:mockito/annotations.dart';
import 'package:mockito/mockito.dart';
import 'package:http/http.dart' as http;
import 'package:my_app/api_service.dart';
// Generate the mock class for http.Client
@GenerateNiceMocks([MockSpec<http.Client>()])
import 'api_service_test.mocks.dart';
void main() {
group('ApiService', () {
late ApiService apiService;
late MockClient mockHttpClient;
setUp(() {
mockHttpClient = MockClient();
apiService = ApiService(mockHttpClient);
});
test('returns data if the http call completes successfully', () async {
// Arrange: Stub the async HTTP GET request using thenAnswer
when(mockHttpClient.get(any)).thenAnswer(
(_) async => http.Response('{"data": "Success"}', 200),
);
// Act
final result = await apiService.fetchData('https://api.example.com/data');
// Assert
expect(result, 'Success');
// Verify the mock was called with the correct Uri
verify(mockHttpClient.get(Uri.parse('https://api.example.com/data'))).called(1);
});
test('throws an exception if the http call completes with an error', () {
// Arrange
when(mockHttpClient.get(any)).thenAnswer(
(_) async => http.Response('Not Found', 404),
);
// Act & Assert
expect(
apiService.fetchData('https://api.example.com/data'),
throwsException,
);
});
});
}
```

528
.agents/skills/dart-migrate-to-checks-package/SKILL.md Normal file
View File

@ -0,0 +1,528 @@
---
name: dart-migrate-to-checks-package
description: |-
Replace the usage of `expect` and similar functions from `package:matcher`
to `package:checks` equivalents.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 09 Jun 2026 19:30:00 GMT
---
# Migrating Dart Tests to Package Checks
Use this skill when you need to migrate a Dart test suite from the legacy
`package:matcher` (which is exported by default from `package:test/test.dart`)
to the modern, type-safe, and literate `package:checks` assertion library.
## Contents
- [When to Use This Skill](#when-to-use-this-skill)
- [How to Use This Skill (The Workflow)](#how-to-use-this-skill-the-workflow)
- [Key Syntax Differences and Pitfalls](#key-syntax-differences-and-pitfalls)
- [Matcher-to-Checks Mapping Table](#matcher-to-checks-mapping-table)
- [Matchers with No Direct Replacements](#matchers-with-no-direct-replacements)
- [Strategies for Discovery](#strategies-for-discovery)
- [Examples](#examples)
---
## When to Use This Skill
- When asked to "migrate tests to checks", "use package:checks", or
"modernize test assertions".
- When updating legacy test suites where static type safety, better
autocomplete in IDEs, and highly detailed failure diagnostics are desired.
---
## How to Use This Skill (The Workflow)
Follow this structured workflow to safely and systematically migrate a test suite:
### 1. Dependency Setup
- Add `package:checks` as a `dev_dependency` in `pubspec.yaml`:
```bash
dart pub add dev:checks
```
- Remove `package:matcher` if it is explicitly listed under `dev_dependencies`
(it is typically transitively included by `package:test`, which is fine).
### 2. Identify and Plan Target Files
- Use the grep patterns in [Strategies for Discovery](#strategies-for-discovery)
to locate all test files containing legacy `expect` or `expectLater` calls.
- Decide whether to migrate files fully or incrementally.
### 3. Migrating a File (Incremental or Full)
For any target test file:
1. **Update Imports**:
- Replace the generic `import 'package:test/test.dart';` with:
```dart
import 'package:test/scaffolding.dart';
import 'package:checks/checks.dart';
```
- **For Incremental Migration**: If you only want to migrate some test cases
in the file, or want to migrate one step at a time, add:
```dart
import 'package:test/expect.dart'; // Temporarily allows legacy expect()
```
2. **Translate Assertions**: Rewrite legacy `expect` and `expectLater` calls
to `check` syntax following the [Key Syntax Differences and
Pitfalls](#key-syntax-differences-and-pitfalls) and the
[Matcher-to-Checks Mapping Table](#matcher-to-checks-mapping-table).
3. **Verify via Compiler**: If migrating fully, remove the `import
'package:test/expect.dart';` line. Any remaining un-migrated `expect`
calls will immediately surface as compiler errors, making them easy to
find and fix.
### 4. Verification and Feedback Loops
- **Static Analysis**: Run static analysis on the target package:
```bash
dart analyze
```
Pay close attention to generic type parameters on `.isA<Type>()` and
ensure asynchronous expectations are properly awaited (check for
`unawaited_futures` warnings).
- **Run Tests**: Execute the tests to verify both behavior and correct
assertion runtime logic:
```bash
dart test
```
If a test fails, review the extremely detailed failure output of
`package:checks` to diagnose if the test is genuinely failing or if the
expectation was translated incorrectly.
---
## Key Syntax Differences and Pitfalls
> [!IMPORTANT]
> A line-for-line translation can sometimes introduce subtle bugs or false
> passes. Always review these key differences carefully:
### 1. Collection Equality Pitfall (`equals` vs `deepEquals`)
- **Legacy Matcher**: `expect(actual, expected)` or `expect(actual,
equals(expected))` performed a **deep equality check** if the arguments
were collections (Lists, Maps, Sets).
- **Package Checks**: `.equals(expected)` corresponds strictly to
`operator ==`. Since Dart collections do not override `operator ==` for
element-wise comparison, using `.equals` on a collection will check for
*identity* and almost certainly fail at runtime.
- **Remediation**: You **must** replace collection equality assertions with
`.deepEquals(expected)`.
```dart
// BEFORE (Matcher)
expect(myList, [1, 2, 3]);
// AFTER (Checks)
check(myList).deepEquals([1, 2, 3]);
```
### 2. The `reason` Parameter is now `because`
- **Legacy Matcher**: The explanation was passed as a trailing named
argument `reason` to `expect`:
```dart
expect(actual, expectation, reason: 'Explanation');
```
- **Package Checks**: The explanation is passed as the named argument
`because` to the `check` function *before* the actual subject:
```dart
check(because: 'Explanation', actual).expectation();
```
### 3. Regular Expression Matching (`matches` vs `matchesPattern`)
- **Legacy Matcher**: The `matches(pattern)` matcher automatically converted
a `String` argument into a `RegExp` (e.g., `matches(r'\d')` matched `'1'`).
- **Package Checks**: `.matchesPattern(pattern)` treats a `String` argument
as a literal string pattern.
- **Remediation**: To match using a regular expression, you must explicitly
pass a `RegExp` object:
```dart
// BEFORE (Matcher)
expect(someString, matches(r'\d+'));
// AFTER (Checks)
check(someString).matchesPattern(RegExp(r'\d+'));
```
### 4. Property Extraction (`TypeMatcher.having` vs `.has`)
- **Legacy Matcher**: Chained field/property expectations used
`TypeMatcher.having(feature, description, matcher)`:
```dart
expect(actual, isA<Person>().having((p) => p.name, 'name', startsWith('A')));
```
- **Package Checks**: The `.has(feature, description)` extension is
available on all `Subject`s, takes one fewer argument, and returns a new
`Subject` representing that property. You chain expectations directly off
it:
```dart
check(actual).isA<Person>().has((p) => p.name, 'name').startsWith('A');
```
### 5. Synchronous vs. Asynchronous `throws`
- **Legacy Matcher**: In `package:matcher`, `throwsA` behaved similarly for both
synchronous closures and asynchronous futures when wrapped in `expect` or
`expectLater`.
- **Package Checks**: The `.throws<E>()` expectation behaves differently and
has different return types depending on whether the subject is synchronous or
asynchronous:
- **Synchronous** (`Subject<T Function()>`): `.throws<E>()` returns a
`Subject<E>` synchronously. This **does not** accept a callback argument!
You chain or cascade expectations directly off the returned `Subject<E>`:
```dart
// YES (Synchronous chaining)
check(() => triggerSyncError()).throws<ArgumentError>()
..has((e) => e.message, 'message').equals('invalid input');
// NO (Passing a callback to sync throws will cause a compiler error!)
check(() => triggerSync").throws<ArgumentError>((it) => ...); // ERROR!
```
- **Asynchronous** (`Subject<Future<T>>`): `.throws<E>()` returns
`Future<void>`. Because you cannot chain directly off a `Future<void>`, this
**requires** an inspection callback:
```dart
// YES (Asynchronous callback)
await check(triggerAsyncError()).throws<ArgumentError>((it) => it
..has((e) => e.message, 'message').equals('invalid input'));
```
- **Crucial Pitfall**: Trying to chain expectations directly after an awaited
asynchronous `.throws<E>()` (e.g.,
`await check(future).throws<E>().equals(...)`) will fail to compile
because it returns `Future<void>`.
### 6. RegExp / Pattern Equality
- **Legacy Matcher**: In `package:matcher`, `expect(myPattern,`
`equals(RegExp('Hello')))` worked because the matcher comparison rules
handled RegExp instances.
- **Package Checks**: `.equals()` uses strict Dart `==` equality. Since separate
`RegExp` instances do not satisfy `==`, using `.equals()` will fail at runtime.
- **Remediation**: Use `.isA<RegExp>()` type refinement along with cascades to
assert on the properties of the `RegExp` object explicitly:
```dart
check(myPattern).isA<RegExp>()
..has((r) => r.pattern, 'pattern').equals('Hello')
..has((r) => r.isMultiLine, 'isMultiLine').isTrue();
```
### 7. Strict Nullable Boolean Safety (`bool?` fields)
- **Legacy Matcher**: Statically, `isTrue` and `isFalse` performed loose
dynamic checks at runtime, which silently accepted nullable booleans (`bool?`).
- **Package Checks**: `.isTrue()` and `.isFalse()` are defined strictly on
`Subject<bool>` (non-nullable). They are **not** available on `Subject<bool?>`.
- **Remediation**: For fields declared as `bool?`, you must either refine the
subject (e.g., `.isNotNull().isTrue()`) or simply use `.equals(true)` and
`.equals(false)` which are generic and work on all types:
```dart
// If options.flagOutdated is a bool?
check(options.flagOutdated).equals(true);
check(options.flagOutdated).equals(false);
```
### 8. Map Key Containment (`containsKey` vs `contains`)
- **Legacy Matcher**: In `package:matcher`, `contains(key)` was used to assert
that a `Map` contained a specific key.
- **Package Checks**: Calling `.contains(...)` on a `Subject<Map>` is not
defined and will fail compilation.
- **Remediation**: Use the map-specific `.containsKey(key)` matcher instead:
```dart
// BEFORE (Matcher)
expect(myMap, contains('my_key'));
// AFTER (Checks)
check(myMap).containsKey('my_key');
```
### 9. Explicit Generic Parameters for Extension Types
- **Legacy Matcher**: `expect(extensionTypeConst, 3)` compiled because of loose
dynamic equality.
- **Package Checks**: If `QrEciValue` is an extension type representation of `int`
(e.g., `extension type const QrEciValue(int value) implements int`), calling
`.equals(3)` on a `Subject<QrEciValue>` fails because `3` (an `int`) is not
assignable to `QrEciValue`. Casting with `as int` will trigger an
"Unnecessary cast" static analysis warning because `QrEciValue` statically
implements `int`.
- **Remediation**: Explicitly specify the generic type parameter on the `check`
function to force checks to treat it as the primitive type:
```dart
// YES (Type-safe and warning-free)
check<int>(QrEciValue.iso8859_1).equals(3);
```
### 10. Dynamic Map / JSON Lookup Casting
- **Legacy Matcher**: Loose dynamic typing allowed comparing nested json lookups
statically typed as `dynamic` directly against lists or maps.
- **Package Checks**: Strict type safety rejects the implicit assignment of
`dynamic` to `Iterable<Object?>` in `.deepEquals(...)`.
- **Remediation**: Statically cast the dynamic lookup result to a `List` or `Map`:
```dart
// YES (Explicit cast to List)
check(myIterable).deepEquals(json['data']['items'] as List);
```
---
## Matcher-to-Checks Mapping Table
Use this table as a quick reference for direct matcher replacements:
| Legacy Matcher | Package Checks Equivalent | Notes |
| :--- | :--- | :--- |
| `expect(actual, expected)` | `check(actual).equals(expected)` | Use `.deepEquals` for collections! |
| `expect(actual, equals(expected))` | `check(actual).equals(expected)` | Use `.deepEquals` for collections! |
| `isA<T>()` | `check(actual).isA<T>()` | Chaining is supported directly |
| `same(expected)` | `check(actual).identicalTo(expected)` | Verifies identity |
| `anyElement(matcher)` | `check(iterable).any(conditionCallback)` | E.g. `check(list).any((e) => e.equals(1))` |
| `everyElement(matcher)` | `check(iterable).every(conditionCallback)` | E.g. `check(list).every((e) => e.isGreaterThan(0))` |
| `hasLength(expected)` | `check(actual).length.equals(expected)` | Works on String, Map, Iterable, etc. |
| `isNot(matcher)` | `check(actual).not(conditionCallback)` | E.g. `check(val).not((it) => it.equals(5))` |
| `contains(element)` | `check(actual).contains(element)` | Works on String, Iterable (use `containsKey` for Map!) |
| `contains(key)` (on a Map) | `check(map).containsKey(key)` | Map key containment |
| `startsWith(prefix)` | `check(string).startsWith(prefix)` | String only |
| `endsWith(suffix)` | `check(string).endsWith(suffix)` | String only |
| `isEmpty` | `check(actual).isEmpty()` | Works on String, Map, Iterable |
| `isNotEmpty` | `check(actual).isNotEmpty()` | Works on String, Map, Iterable |
| `isNull` | `check(actual).isNull()` | |
| `isNotNull` | `check(actual).isNotNull()` | |
| `isTrue` / `true` | `check(actual).isTrue()` | Works on non-nullable `bool` only |
| `isFalse` / `false` | `check(actual).isFalse()` | Works on non-nullable `bool` only |
| `completion(matcher)` | `await check(future).completes(conditionCallback)` | Must be awaited! |
| `throwsA(matcher)` | `await check(future).throws<Type>()` | Must be awaited! |
| `emits(value)` | `await check(streamQueue).emits(conditionCallback)` | Must be awaited! |
| `emitsThrough(value)` | `await check(streamQueue).emitsThrough(conditionCallback)` | Must be awaited! |
| `stringContainsInOrder(list)` | `check(string).containsInOrder(list)` | String only |
| `pairwiseCompare(...)` | `check(actual).pairwiseMatches(...)` | |
---
## Matchers with No Direct Replacements
Some legacy matchers do not have a one-to-one equivalent in `package:checks`
due to API cleanup. Use these standard workarounds:
### 1. Specific Error Matchers
- **Legacy**: `throwsArgumentError`, `throwsStateError`,
`throwsUnsupportedError`, etc.
- **Checks**: Use `.throws<T>()` with the specific error type:
```dart
await check(triggerError()).throws<ArgumentError>();
```
### 2. The `anything` Matcher
- **Legacy**: `expect(actual, anything)`
- **Checks**: Pass an empty condition callback `(_) {}` when a condition is
syntactically required:
```dart
await check(someFuture).completes((_) {});
```
### 3. Specific Numeric Toggles
- **Legacy**: `isPositive`, `isNegative`, `isZero`, `isNonPositive`,
`isNonNegative`, `isNonZero`
- **Checks**: Use explicit comparative expectations:
- `isPositive` $\rightarrow$ `isGreaterThan(0)`
- `isNegative` $\rightarrow$ `isLessThan(0)`
- `isZero` $\rightarrow$ `equals(0)`
- `isNonNegative` $\rightarrow$ `isGreaterOrEqual(0)`
### 4. Numeric Ranges
- **Legacy**: `inClosedOpenRange(min, max)`, `inInclusiveRange(min, max)`,
etc.
- **Checks**: Chain the boundaries using the cascade operator (`..`):
```dart
check(actualValue)
..isGreaterOrEqual(min)
..isLessThan(max);
```
---
## Writing Custom Expectations (Replacing Custom Matchers)
When migrating from a legacy codebase, you may encounter custom `Matcher`
subclasses. In `package:checks`, custom assertions are implemented as
`extension` methods on `Subject<T>`.
To write custom expectations, you must import the checks context API:
```dart
import 'package:checks/context.dart';
```
### 1. Simple Custom Expectations (using `expect`)
Use `context.expect` to check a property and return a `Rejection` on failure:
```dart
extension CustomPersonChecks on Subject<Person> {
void isAdult() {
context.expect(
() => ['is an adult (age >= 18)'],
(actual) {
if (actual.age >= 18) return null; // Pass
return Rejection(
which: ['is only ${actual.age} years old'],
);
},
);
}
}
```
### 2. Nested Property Extraction (using `nest` or `has`)
To extract a property and allow further chained checks, use `nest` or the
simpler `has` helper:
- **Using `has` (Recommended for simple, non-failing field access)**:
```dart
extension CustomPersonChecks on Subject<Person> {
Subject<Address> get address => has((p) => p.address, 'address');
}
```
- **Using `nest` (For property extraction that can fail or reject)**:
```dart
extension CustomPersonChecks on Subject<Person> {
Subject<String> get ssn => context.nest(
'has a valid SSN',
(actual) {
final ssnValue = actual.ssn;
if (ssnValue == null) {
return Extracted.rejection(which: ['has no SSN']);
}
return Extracted.value(ssnValue);
},
);
}
```
### 3. Asynchronous Custom Expectations
If the expectation is asynchronous (e.g. checking a Future or Stream), use
`context.expectAsync` or `context.nestAsync` and return the resulting `Future`:
```dart
extension CustomFutureChecks<T> on Subject<Future<T>> {
Future<void> completesNormally() {
return context.expectAsync(
() => ['completes without throwing'],
(actual) async {
try {
await actual;
return null; // Pass
} catch (e) {
return Rejection(which: ['threw $e']);
}
},
);
}
}
```
---
## Strategies for Discovery
Execute these commands in the terminal to identify legacy matchers and files
requiring migration:
```bash
# 1. Find all test files containing legacy expect() or expectLater()
grep -rn "expect(" test/
grep -rn "expectLater(" test/
# 2. Find potential collection equality pitfalls (literal lists or maps)
grep -rn "expect(.*, \[" test/
grep -rn "expect(.*, {" test/
# 3. Find matches() calls (need conversion to RegExp + matchesPattern)
grep -rn "matches(" test/
# 4. Find legacy TypeMatcher.having() calls (which need conversion to .has())
grep -rn "having(" test/
```
---
## Examples
### Basic Assertions
**Before (Matcher):**
```dart
expect(someValue, isNotNull);
expect(result, isTrue, reason: 'should be successful');
expect(myString, startsWith('hello'));
```
**After (Checks):**
```dart
check(someValue).isNotNull();
check(because: 'should be successful', result).isTrue();
check(myString).startsWith('hello');
```
### Collection and Deep Equality
**Before (Matcher):**
```dart
expect(items, [1, 2, 3]);
expect(configMap, equals({'port': 8080}));
```
**After (Checks):**
```dart
check(items).deepEquals([1, 2, 3]);
check(configMap).deepEquals({'port': 8080});
```
### Chaining and Cascades
**Before (Matcher):**
```dart
expect(someString, allOf([
startsWith('a'),
contains('b'),
endsWith('c'),
]));
```
**After (Checks):**
```dart
check(someString)
..startsWith('a')
..contains('b')
..endsWith('c');
```
### Complex Property Matching (has)
**Before (Matcher):**
```dart
expect(response, isA<Response>()
.having((r) => r.statusCode, 'statusCode', 200)
.having((r) => r.body, 'body', contains('success')));
```
**After (Checks):**
```dart
check(response).isA<Response>()
..has((r) => r.statusCode, 'statusCode').equals(200)
..has((r) => r.body, 'body').contains('success');
```
### Asynchronous Futures
**Before (Matcher):**
```dart
expect(fetchData(), completes);
expect(fetchData(), completion(equals('data')));
expect(failingCall(), throwsA(isA<StateError>()));
```
**After (Checks):**
```dart
await check(fetchData()).completes();
await check(fetchData()).completes((it) => it.equals('data'));
await check(failingCall()).throws<StateError>();
```
### Asynchronous Streams
**Before (Matcher):**
```dart
var queue = StreamQueue(Stream.fromIterable([1, 2, 3]));
await expectLater(queue, emitsInOrder([1, 2, 3]));
```
**After (Checks):**
```dart
var queue = StreamQueue(Stream.fromIterable([1, 2, 3]));
await check(queue).inOrder([
(s) => s.emits((e) => e.equals(1)),
(s) => s.emits((e) => e.equals(2)),
(s) => s.emits((e) => e.equals(3)),
]);
```

116
.agents/skills/dart-resolve-package-conflicts/SKILL.md Normal file
View File

@ -0,0 +1,116 @@
---
name: dart-resolve-package-conflicts
description: Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 24 Apr 2026 15:11:14 GMT
---
# Managing Dart Dependencies
## Contents
- [Core Concepts](#core-concepts)
- [Version Constraints](#version-constraints)
- [Workflow: Auditing Dependencies](#workflow-auditing-dependencies)
- [Workflow: Upgrading Dependencies](#workflow-upgrading-dependencies)
- [Workflow: Resolving Version Conflicts](#workflow-resolving-version-conflicts)
- [Examples](#examples)
## Core Concepts
Dart enforces a strict single-version rule for dependencies: a project and all its transitive dependencies must resolve to a single, shared version of any given package. This prevents runtime type mismatches but introduces the risk of "version lock."
To mitigate version lock, Dart relies on version constraints rather than pinned versions in the `pubspec.yaml`. The `pubspec.lock` file maintains the exact resolved versions for reproducible builds.
Understand the output columns of `dart pub outdated`:
* **Current:** The version currently recorded in `pubspec.lock`.
* **Upgradable:** The latest version allowed by the constraints in `pubspec.yaml`. `dart pub upgrade` resolves to this.
* **Resolvable:** The absolute latest version that can be resolved when factoring in all other dependencies in the project.
* **Latest:** The latest published version of the package (excluding prereleases).
## Version Constraints
* **Use Caret Syntax:** Always use caret syntax (e.g., `^1.2.3`) for dependencies in `pubspec.yaml`. This allows `pub` to select newer, non-breaking versions (up to, but not including, the next major version) during resolution.
* **Tighten Dev Dependencies:** Set the lower bound of `dev_dependencies` to the exact version currently used. This reduces resolution complexity and prevents older, incompatible dev tools from being selected.
* **Enforce Lockfiles in CI:** Use `dart pub get --enforce-lockfile` in CI/CD pipelines to ensure the exact versions tested locally are used in production.
## Workflow: Auditing Dependencies
Run this workflow periodically to identify stale packages that may impact stability or performance.
**Task Progress:**
- [ ] Run `dart pub outdated`.
- [ ] Review the **Upgradable** column to identify packages that can be updated without modifying `pubspec.yaml`.
- [ ] Review the **Resolvable** column to identify packages that require constraint modifications in `pubspec.yaml` to update.
- [ ] Identify any packages marked as retracted or discontinued.
## Workflow: Upgrading Dependencies
Use conditional logic based on the audit results to upgrade dependencies.
**Task Progress:**
- [ ] **If updating to "Upgradable" versions:**
- [ ] Run `dart pub upgrade`.
- [ ] Run `dart pub upgrade --tighten` to automatically update the lower bounds in `pubspec.yaml` to match the newly resolved versions.
- [ ] **If updating to "Resolvable" versions (Major updates):**
- [ ] Manually edit `pubspec.yaml` to bump the version constraint to match the "Resolvable" column (e.g., change `^0.11.0` to `^0.12.1`).
- [ ] Run `dart pub upgrade` to resolve the new constraints and update `pubspec.lock`.
- [ ] **Feedback Loop:**
- [ ] Run `dart analyze` -> review errors -> fix breaking API changes.
- [ ] Run `dart test` -> review failures -> fix regressions.
## Workflow: Resolving Version Conflicts
When `pub` cannot find a set of concrete versions that satisfy all constraints, or when dealing with a retracted package version, manipulate the lockfile surgically.
**NEVER** delete the entire `pubspec.lock` file and run `dart pub get`. This causes uncontrolled upgrades across the entire dependency graph.
**Task Progress:**
- [ ] Open `pubspec.lock`.
- [ ] Locate the specific YAML block for the conflicting or retracted package.
- [ ] Delete ONLY that package's entry from the lockfile.
- [ ] Run `dart pub get` to fetch the newest compatible, non-retracted version for that specific package.
- [ ] **Feedback Loop:**
- [ ] Run `dart pub deps` -> verify the dependency graph resolves correctly.
- [ ] If resolution fails, identify the transitive dependency causing the lock, update its constraint in `pubspec.yaml`, and retry.
## Examples
### Tightening Constraints
When `dart pub outdated` shows a package is resolvable to a higher minor/patch version, use the `--tighten` flag to update the `pubspec.yaml` automatically.
**Input (`pubspec.yaml`):**
```yaml
dependencies:
http: ^0.13.0
```
**Command:**
```bash
dart pub upgrade --tighten http
```
**Output (`pubspec.yaml`):**
```yaml
dependencies:
http: ^0.13.5
```
### Surgical Lockfile Removal
If `package_a` is retracted or locked in a conflict, remove only its block from `pubspec.lock`.
**Before (`pubspec.lock`):**
```yaml
packages:
package_a:
dependency: "direct main"
description:
name: package_a
url: "https://pub.dev"
source: hosted
version: "1.0.0" # Retracted version
package_b:
dependency: "direct main"
# ...
```
**Action:** Delete the `package_a` block entirely. Leave `package_b` untouched. Run `dart pub get`.

104
.agents/skills/dart-run-static-analysis/SKILL.md Normal file
View File

@ -0,0 +1,104 @@
---
name: dart-run-static-analysis
description: Execute `dart analyze` to identify warnings and errors, and use `dart fix --apply` to automatically resolve mechanical lint issues. Use during development to ensure code quality and before committing changes.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 24 Apr 2026 15:09:34 GMT
---
# Analyzing and Fixing Dart Code
## Contents
- [Analysis Configuration](#analysis-configuration)
- [Diagnostic Suppression](#diagnostic-suppression)
- [Workflow: Executing Static Analysis](#workflow-executing-static-analysis)
- [Workflow: Applying Automated Fixes](#workflow-applying-automated-fixes)
- [Examples](#examples)
## Analysis Configuration
Configure the Dart analyzer using the `analysis_options.yaml` file located at the package root.
- **Base Configuration:** Always include a standard rule set (e.g., `package:lints/recommended.yaml` or `package:flutter_lints/flutter.yaml`) using the `include:` directive.
- **Strict Type Checks:** Enable strict type checks under the `analyzer: language:` node to prevent implicit downcasts and dynamic inferences. Set `strict-casts: true`, `strict-inference: true`, and `strict-raw-types: true`.
- **Linter Rules:** Explicitly enable or disable specific rules under the `linter: rules:` node. Use a key-value map (`rule_name: true/false`) when overriding included rules, or a list (`- rule_name`) when defining a fresh set. Do not mix list and map syntax in the same `rules` block.
- **Formatter Configuration:** Configure `dart format` behavior under the `formatter:` node. Set `page_width` (default 80) and `trailing_commas` (`automate` or `preserve`).
- **Analyzer Plugins:** Enable custom diagnostics by adding plugins under the `analyzer: plugins:` node. Ensure the plugin package is added as a `dev_dependency` in `pubspec.yaml`.
## Diagnostic Suppression
When a diagnostic (lint or warning) yields a false positive or applies to generated code, suppress it explicitly.
- **File-level Exclusion:** Use the `analyzer: exclude:` node in `analysis_options.yaml` to exclude entire files or directories (e.g., `**/*.g.dart`) using glob patterns.
- **File-level Suppression:** Add `// ignore_for_file: <diagnostic_code>` at the top of a Dart file to suppress specific diagnostics for the entire file. Use `// ignore_for_file: type=lint` to suppress all linter rules.
- **Line-level Suppression:** Add `// ignore: <diagnostic_code>` on the line directly above the offending code, or appended to the end of the offending line.
- **Pubspec Suppression:** Add `# ignore: <diagnostic_code>` above the offending line in `pubspec.yaml` files (e.g., `# ignore: sort_pub_dependencies`).
- **Plugin Diagnostics:** Prefix the diagnostic code with the plugin name when suppressing plugin-specific issues (e.g., `// ignore: some_plugin/some_code`).
## Workflow: Executing Static Analysis
Use this workflow to identify type-related bugs, style violations, and potential runtime errors.
**Task Progress:**
- [ ] 1. Verify `analysis_options.yaml` exists at the project root.
- [ ] 2. Run the analyzer using the `analyze_files` MCP tool (if available) or the CLI command `dart analyze <target_directory>`.
- [ ] 3. Review the diagnostic output.
- [ ] 4. If info-level issues must be treated as failures, append the `--fatal-infos` flag.
- [ ] 5. Resolve reported errors manually or proceed to the Automated Fixes workflow.
## Workflow: Applying Automated Fixes
Use this workflow to resolve outdated API usages, apply quick fixes, and migrate code (e.g., Dart 3 migrations).
**Task Progress:**
- [ ] 1. Execute a dry run to preview proposed changes using the `dart_fix` MCP tool or CLI command `dart fix --dry-run`.
- [ ] 2. Review the proposed fixes to ensure they align with the intended architecture.
- [ ] 3. If additional fixes are required, verify that the corresponding linter rules are enabled in `analysis_options.yaml`.
- [ ] 4. Apply the fixes using the `dart_fix` MCP tool or CLI command `dart fix --apply`.
- [ ] 5. Format the modified code using the `dart_format` MCP tool or CLI command `dart format .`.
- [ ] 6. Run the static analysis workflow to verify all diagnostics are resolved.
## Examples
### Comprehensive `analysis_options.yaml`
```yaml
include: package:flutter_lints/recommended.yaml
analyzer:
exclude:
- "**/*.g.dart"
- "lib/generated/**"
language:
strict-casts: true
strict-inference: true
strict-raw-types: true
errors:
todo: ignore
invalid_assignment: warning
missing_return: error
linter:
rules:
avoid_shadowing_type_parameters: false
await_only_futures: true
use_super_parameters: true
formatter:
page_width: 100
trailing_commas: preserve
```
### Inline Diagnostic Suppression
```dart
// Suppress for the entire file
// ignore_for_file: unused_local_variable, dead_code
void processData() {
// Suppress for a specific line
// ignore: invalid_assignment
int x = '';
const y = 10; // ignore: constant_identifier_names
}
```

419
.agents/skills/dart-setup-ffi-assets/SKILL.md Normal file
View File

@ -0,0 +1,419 @@
---
name: dart-setup-ffi-assets
description: "Guides agents in compiling and packaging C/C++ source code into dynamic or static libraries (Code Assets) using Dart's Native Assets hook system (via hook/build.dart and hook/link.dart utilizing package:hooks and package:native_toolchain_c). Use when a user asks to: 'setup native assets', 'compile C/C++ source code', 'bundle dynamic libraries', 'build native C code', 'link native assets', 'implement build.dart or link.dart hooks', or 'integrate C/C++ interop in Dart/Flutter'. Helps agents avoid manual toolchain orchestration and configures secure hash-validated binary downloads or advanced linker tree-shaking with package:record_use mapping."
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 29 May 2026 09:10:00 GMT
---
# Compiling C Code into Code Assets with Native Assets Hooks
Integrate and automate the compilation and packaging of native C/C++ source code into **Code Assets** under Dart's overarching **Native Assets** feature using build and link hooks.
## Contents
- [Introduction](#introduction)
- [Constraints](#constraints)
- [Native Interop Packages](#native-interop-packages)
- [Step-by-Step Workflow](#step-by-step-workflow)
- [Choosing an Integration Approach](#choosing-an-integration-approach)
- [Method 1: Local Compilation with Linker Tree-Shaking (Recommended)](#method-1-local-compilation-with-linker-tree-shaking-recommended)
- [Prerequisite Host Compiler Toolchains](#prerequisite-host-compiler-toolchains)
- [C Source and Bindings Setup](#c-source-and-bindings-setup)
- [Defining the C Library Build Spec](#defining-the-c-library-build-spec)
- [Implementing hook/build.dart](#implementing-hookbuilddart)
- [Implementing hook/link.dart](#implementing-hooklinkdart)
- [Method 2: Downloading Precompiled Dynamic Libraries](#method-2-downloading-precompiled-dynamic-libraries)
- [Why Download Precompiled Binaries?](#why-download-precompiled-binaries)
- [Implementing Precompiled Dynamic Downloads](#implementing-precompiled-dynamic-downloads)
- [Verification Checklist](#verification-checklist)
- [1. Local Execution Sandbox](#1-local-execution-sandbox)
- [2. Verify Target Outputs](#2-verify-target-outputs)
- [3. Verify Tree-Shaking Stripping](#3-verify-tree-shaking-stripping)
- [4. Verify Offline Compliance (User Defines)](#4-verify-offline-compliance-user-defines)
---
## Introduction
Under Dart's **Native Assets** feature, packages can package native code (like C/C++ libraries) as **Code Assets** and bundle them automatically during standard development cycles (e.g., `dart run`, `dart test`, `dart build`, and `flutter run`). The packaging of **Code Assets** is driven by two programmatic hook scripts placed inside a package's `hook/` folder:
1. `hook/build.dart`: Compiles local C sources to machine code or bundles prebuilt native binaries as code assets for a specific host/target architecture.
2. `hook/link.dart`: Links built code assets, applying advanced tree-shaking optimizations to strip unused native symbols and compress the runtime binary size.
---
## Constraints
> [!IMPORTANT]
> Keep all file resolving platform-independent. Never hardcode absolute target paths, shell scripts, or system command variables. Always use `Platform.script.resolve()` or `Uri`-based resolution to ensure scripts are fully portable.
* **Hook Locations**: Compiling and packaging hooks must reside strictly inside the `hook/` directory at the package's root:
* `hook/build.dart` (Build execution phase)
* `hook/link.dart` (Optional packaging/linking/tree-shaking phase)
* **Compile Toolchain Standard**: Use the programmatic APIs from `package:native_toolchain_c` (e.g. `CBuilder` and `CLibrary`) to run compile toolchains. Never invoke raw `gcc`, `clang`, or `msvc` via shell commands.
* **Preamble & License Headers**: Every handcrafted and generated source file (including bindings, helpers, and hooks) must strictly contain the target package's copyright and licensing header.
* **Tree Shaking Mapping**: If utilizing compiler tree-shaking, you must map the target Dart method names (e.g. `Method.name`) back to their raw native C symbol names using a record use mapping generated by FFIgen. The mapping file must reside under `lib/src/third_party/` and strictly use the `.g.dart` extension (e.g., `sqlite3.record_use_mapping.g.dart`).
* **Integrity Safeguards for Precompiled Libraries**: If adopting the dynamic download pattern:
* **Cryptographic Verification**: Downloaded prebuilt binaries must be checked against preconfigured lookup tables containing MD5 or SHA-256 hashes to guarantee binary integrity and prevent tampering.
* **Graceful Recovery**: Support offline developers by providing fallbacks (such as local compiler execution via flags like `local_build`).
---
## Native Interop Packages
Programmatic build and link hooks for **Code Assets** leverage three specialized native interop packages:
| Dependency | Purpose | Key API Abstractions |
| :--- | :--- | :--- |
| **`package:hooks`** | Main orchestrator defining execution bounds. | `build(args, callback)`, `link(args, callback)` |
| **`package:native_toolchain_c`** | Detects local compilers (MSVC, Xcode/Clang, GCC) and executes build toolchains. | `CLibrary`, `CBuilder`, `LinkerOptions.treeshake` |
| **`package:code_assets`** | Models code metadata records passed to dynamic loaders. | `CodeAsset`, `DynamicLoadingBundled` |
---
## Step-by-Step Workflow
### Step 1: Add Dependencies
Add Code Assets hook and toolchain dependencies to your package. You must fetch these dependencies directly from **pub.dev**.
You can add it automatically using the CLI:
```bash
dart pub add code_assets hooks native_toolchain_c record_use dev:ffigen
```
Or manually declare them in your target package's `pubspec.yaml`:
```yaml
dependencies:
code_assets: ^1.0.0
hooks: ^0.1.0
native_toolchain_c: ^0.1.0
record_use: ^0.6.0
dev_dependencies:
ffigen: ^20.1.1
```
### Step 2: Define C Specifications
Define your target C library compilation metadata inside `lib/src/c_library.dart`. This lets both the build and link hooks share a single source of truth for assets, names, and sources.
### Step 3: Implement Build and Link Hook Scripts
Write the compilation orchestration script inside `hook/build.dart` and the dead-code elimination logic inside `hook/link.dart`.
### Step 4: Run the Hook Cycle
Running standard test suites dynamically launches the build and link hook lifecycle in the background:
```bash
dart test
```
---
## Choosing an Integration Approach
There are two primary methods for integrating and delivering C/C++ native assets in Dart. Select the one that matches your project requirements:
| Aspect | Method 1: Local Compilation & Tree-Shaking | Method 2: Precompiled Downloads |
| :--- | :--- | :--- |
| **Primary Use Case** | When C/C++ source code is included directly in the package and you want maximum size optimization. | When compiling locally is slow/complex, or when avoiding developer host toolchain requirements. |
| **Host Toolchain Requirements** | Requires pre-installed platform C compiler (Xcode tools, MSVC, GCC). | Zero compiler setup required on developer/user machines. |
| **Binary Optimization** | Premium. Unused symbols are completely tree-shaken, decreasing library size. | Standard. Standard compiled binaries are shipped as-is. |
| **Offline Setup** | Fully compliant. Works completely offline. | Requires network access to download libraries, with offline fallback. |
---
## Method 1: Local Compilation with Linker Tree-Shaking (Recommended)
In this approach, the build hook invokes local toolchains (GCC, Clang, MSVC) to compile source files directly. The link hook subsequently filters output symbols utilizing compiler options, retaining only target methods invoked in user code. This represents the standard, robust SQLite pattern under `pkgs/code_assets/example/sqlite`.
### Prerequisite Host Compiler Toolchains
Since `package:native_toolchain_c` delegates actual dynamic compilation to the host operating system's default toolchain, the development machine **must** have one of the following compiler packages pre-installed:
* **macOS**: Xcode Command Line Tools. Install via:
```bash
xcode-select --install
```
* **Linux**: GCC or Clang. Install via:
```bash
sudo apt install build-essential
```
* **Windows**: MSVC (Microsoft Visual C++). Install the **Visual Studio Installer** and select the **Desktop development with C++** workload.
*Note: If no compatible toolchain is discovered on the host path, the build hook script will throw a compilation execution exception. Ensure to specify compiler constraints or adopt Method 2 if toolchains cannot be guaranteed.*
### C Source and Bindings Setup
Assume a C source defining simple math functions at `third_party/sqlite/sqlite3.c` with its entry point header at `third_party/sqlite/sqlite3.h`:
```c
#ifndef SQLITE3_H_
#define SQLITE3_H_
const char *sqlite3_libversion(void);
#endif // SQLITE3_H_
```
We utilize a programmatic FFIgen script (`tool/ffigen.dart`) to create FFI bindings in `lib/src/third_party/sqlite3.g.dart`, enabling recorded usage tracking and producing the lookup metadata map in `lib/src/third_party/sqlite3.record_use_mapping.g.dart`:
```dart
// AUTO-GENERATED FILE - DO NOT MODIFY.
// Generated via ffigen.
const recordUseMapping = {
'sqlite3_libversion': 'sqlite3_libversion',
};
```
### Defining the C Library Build Spec
Define the centralized library specification in `lib/src/c_library.dart`:
```dart
import 'package:native_toolchain_c/native_toolchain_c.dart';
/// The C build specification for the sqlite library.
final cLibrary = CLibrary(
name: 'sqlite3',
assetName: 'src/third_party/sqlite3.g.dart',
sources: ['third_party/sqlite/sqlite3.c'],
);
```
### Implementing `hook/build.dart`
Implement `hook/build.dart` using `CLibrary.build`. This builds the library to a dynamic library (e.g. `.so`, `.dylib`, or `.dll`) inside the hook's target directory:
```dart
import 'package:code_assets/code_assets.dart';
import 'package:hooks/hooks.dart';
import 'package:sqlite/src/c_library.dart';
void main(List<String> args) async {
await build(args, (input, output) async {
if (input.config.buildCodeAssets) {
await cLibrary.build(
input: input,
output: output,
defines: {
if (input.config.code.targetOS == OS.windows)
// Ensure C functions are explicitly exported in the Windows DLL
'SQLITE_API': '__declspec(dllexport)',
},
);
}
});
}
```
### Implementing `hook/link.dart`
Implement the link optimization phase in `hook/link.dart`. This utilizes compiler tree-shaking options (`LinkerOptions.treeshake`) to compile a minimized, dead-code-eliminated binary based on symbol usage records:
```dart
import 'package:hooks/hooks.dart';
import 'package:native_toolchain_c/native_toolchain_c.dart';
import 'package:record_use/record_use.dart';
import 'package:sqlite/src/c_library.dart';
import 'package:sqlite/src/third_party/sqlite3.record_use_mapping.g.dart';
void main(List<String> arguments) async {
await link(arguments, (input, output) async {
await cLibrary.link(
input: input,
output: output,
linkerOptions: LinkerOptions.treeshake(
// Map Dart Method references back to raw C symbol names
symbolsToKeep: input.recordedUses?.calls.keys.cast<Method>().map(
(e) => recordUseMapping[e.name]!,
),
),
);
});
}
```
---
## Method 2: Downloading Precompiled Dynamic Libraries
An alternative approach compiles binaries beforehand on a central build machine, archives them, and downloads the target binary during the build hook execution. This matches the paradigm demonstrated in the `download_asset` hook package.
### Why Download Precompiled Binaries?
* **Host Constraints**: Compiling large C/C++ libraries locally requires a complete compiler setup (GCC, Xcode/SDKs, Visual Studio) that the end-developer's host machine may not possess.
* **Compile Speed**: Precompiled downloads execute in milliseconds compared to potentially long multi-minute compilation processes.
* **Platform Bridging**: Allows cross-compiling constraints to be avoided if host architectures are limited.
---
### Implementing Precompiled Dynamic Downloads
We configure our build hook to detect local compiler flags (e.g. `local_build`). If not specified, the hook utilizes `HttpClient` to pull down platform-specific libraries, calculates the MD5 hash to confirm download safety against a configured hashes lookup table, and registers the binary file as a `CodeAsset`:
#### 1. Defining Target Hashes (`lib/src/hook_helpers/hashes.dart`)
Define target MD5 hash checks per platform file in your package sources:
```dart
const assetHashes = {
'libnative_add_macos_arm64.dylib': '4a88f50438a98402db2dbd47b59eb412',
'libnative_add_linux_x64.so': '9f5e15043aa98402dcdbbd47b59ea520',
'native_add_windows_x64.dll': 'a881e5043ba98402acdebd47b59fa321',
};
```
#### 2. Hook Downloader Helper (`lib/src/hook_helpers/download.dart`)
Implement the downloading and integrity check logic using dynamic target filename matching:
```dart
import 'dart:io';
import 'package:code_assets/code_assets.dart';
import 'package:crypto/crypto.dart';
const version = '1.0.0';
Uri downloadUri(String target) => Uri.parse(
'https://github.com/my-org/my-native-repo/releases/download/$version/$target',
);
Future<File> downloadAsset(
OS targetOS,
Architecture targetArchitecture,
Directory outputDir,
) async {
final fileName = targetOS.dylibFileName('native_add_${targetOS.name}_${targetArchitecture.name}');
final uri = downloadUri(fileName);
final client = HttpClient()..findProxy = HttpClient.findProxyFromEnvironment;
final request = await client.getUrl(uri);
final response = await request.close();
if (response.statusCode != 200) {
throw ArgumentError('Download target $uri failed: Code ${response.statusCode}');
}
final targetFile = File.fromUri(outputDir.uri.resolve(fileName));
await targetFile.create(recursive: true);
await response.pipe(targetFile.openWrite());
return targetFile;
}
Future<String> hashAsset(File file) async {
return md5.convert(await file.readAsBytes()).toString();
}
```
#### 3. Implementing `hook/build.dart`
Write the final download build hook incorporating local compilation fallback:
```dart
import 'dart:io';
import 'package:code_assets/code_assets.dart';
import 'package:hooks/hooks.dart';
import 'package:my_download_package/src/hook_helpers/hashes.dart';
import 'package:my_download_package/src/hook_helpers/download.dart';
import 'package:native_toolchain_c/native_toolchain_c.dart';
void main(List<String> args) async {
await build(args, (input, output) async {
final localBuild = input.userDefines['local_build'] as bool? ?? false;
if (localBuild) {
final name = 'native_add_${input.config.code.targetOS.name}_${input.config.code.targetArchitecture.name}';
final builder = CBuilder.library(
name: name,
assetName: 'native_add.dart',
sources: ['src/native_add.c'],
);
await builder.run(input: input, output: output);
} else {
final targetOS = input.config.code.targetOS;
final targetArch = input.config.code.targetArchitecture;
final outputDir = Directory.fromUri(input.outputDirectory);
final file = await downloadAsset(targetOS, targetArch, outputDir);
final fileHash = await hashAsset(file);
final expectedFileName = targetOS.dylibFileName('native_add_${targetOS.name}_${targetArch.name}');
final expectedHash = assetHashes[expectedFileName];
if (fileHash != expectedHash) {
throw Exception(
'Security Mismatch: File $expectedFileName hash verification failed! '
'Found hash: $fileHash, expected: $expectedHash.'
);
}
output.assets.code.add(
CodeAsset(
package: input.packageName,
name: 'native_add.dart',
linkMode: DynamicLoadingBundled(),
file: file.uri,
),
);
}
});
}
```
---
## Verification Checklist
Before declaring a build or link hook implementation complete, always perform the following checks:
### 1. Local Execution Sandbox
Run unit tests and confirm the native assets compile/link process completes with no runtime or build tool exceptions:
```bash
dart test
```
### 2. Verify Target Outputs
Navigate to your package target directory and verify that dynamic binary assets are created for the host system:
* **macOS**: Verify `.dart_tool/resources/` or target directories contain `.dylib` files.
* **Linux**: Verify `.dart_tool/resources/` or target directories contain `.so` files.
* **Windows**: Verify `.dart_tool/resources/` or target directories contain `.dll` files.
### 3. Verify Tree-Shaking Stripping
To ensure the link hook is actually stripping unused native symbols and compressing binary packaging, perform the following validation:
1. Compile a production bundle of the CLI/app:
```bash
dart build cli bin/main.dart
```
2. Navigate to the compiled build directory containing the dynamic library.
3. Query the exported dynamic symbol tables:
* **macOS**:
```bash
nm -gU build/cli/lib/libsqlite3.dylib
```
* **Linux**:
```bash
nm -D build/cli/lib/libsqlite3.so
```
* **Windows** (using MSVC Developer Command Prompt):
```cmd
dumpbin /EXPORTS build\cli\lib\sqlite3.dll
```
4. **Confirm Target Exports**: Verify that the command outputs **only** the explicitly kept entry point functions (e.g. `sqlite3_libversion`) and does not output any unreferenced/stripped symbols.
5. **No Bundle Scenario**: If the application does not import or invoke any methods from the native library:
- Verify that the link hook logs: `Skipping linking as no symbols are to be kept.`
- Verify that no library was built/placed in the production bundle (the `.dylib`/`.so`/`.dll` file is not generated, saving bundle size).
### 4. Verify Offline Compliance (User Defines)
Confirm offline compliance is fully active and the download fallback executes perfectly offline:
1. Configure the `local_build: true` define for your package in the package's `pubspec.yaml` (or the workspace root `pubspec.yaml`):
```yaml
hooks:
user_defines:
<your_package_name>:
local_build: true
```
2. Disable the machine's network adapter or run in a sandboxed offline shell.
3. Launch unit tests:
```bash
dart test
```
4. Verify the test suite successfully compiles local source files using host compilers, has no compile errors, and never attempts network download requests.

218
.agents/skills/dart-use-ffigen/SKILL.md Normal file
View File

@ -0,0 +1,218 @@
---
name: dart-use-ffigen
description: Guide agents to use `package:ffigen` to automatically generate FFI bindings instead of writing them manually. Use this skill when a task involves writing new FFI bindings, extending C/Objective-C/Swift integrations, or replacing hand-crafted `dart:ffi` setups.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Thu, 28 May 2026 07:21:07 GMT
---
# Generating FFI Bindings using package:ffigen
## Contents
- [Introduction](#introduction)
- [Constraints](#constraints)
- [FFIgen Overview](#ffigen-overview)
- [Step-by-Step Workflow](#step-by-step-workflow)
- [Concrete Example: Binding a C Library](#concrete-example-binding-a-c-library)
- [Verification Checklist](#verification-checklist)
## Introduction
Automate and standardize the generation of FFI bindings using `package:ffigen` (`FfiGenerator`). Writing FFI bindings by hand is error-prone, brittle, and highly discouraged.
## Constraints
* **No Hand-Written FFI Bindings**: If native headers (`.h` files) exist or are generated by a build step, never write manual `DynamicLibrary.lookup`, `@Native` external functions, or raw struct classes. Always use `FfiGenerator` to generate them.
* **Generator Location**: The generator script should be located at `tool/ffigen.dart` within the target package root.
* **Header Location**: If the native header files are third-party, they should be located in `third_party/` within the target package (otherwise placing them in a `src/` directory at the package root is also acceptable). If the headers are not in one of these standard locations, notify the user that it would be cleaner to move the header files to the standard location (e.g., `third_party/`).
* **Targeted Inclusion Filters**: Avoid importing an entire native library unless specifically needed. Always apply precise inclusion lists using positive matches to minimize the size and cognitive load of the generated code (e.g., using `Functions.includeSet` or filtering matches in `include` closures).
* **Output Setup**: If the generated FFI bindings interface with a third-party library (or reference third-party headers), the generated files must always be placed under `lib/src/third_party/`. The primary generated FFI bindings file must strictly use the `.g.dart` extension (e.g. `sqlite3.g.dart`).
* **Preamble & License Headers**: Always supply a premium `preamble` in the `Output` class to specify the license. This must match the native third-party library's license, explicitly include the copyright header of the target native header file, and contain an automatic generation warning (e.g. `// Generated by package:ffigen. Do not edit manually.`).
* **No Unnecessary Commits of Stale Bindings**: Ensure you run the generator script and check if the generated files have changed *before* finishing your task. Always verify the package by running `dart analyze`.
* **Record Usage and Tree Shaking**: If the package is integrated into standard runtime execution or compiles native assets via native hooks:
* Enable recorded usage on all functions by setting `recordUse: (_) => true` under `Functions`.
* Specify the `recordUseMapping` target in `Output` (which must strictly be a `.g.dart` file under `lib/src/third_party/`, e.g. `lib/src/third_party/sqlite3.record_use_mapping.g.dart`) to register bindings for symbol tree shaking.
## FFIgen Overview
To construct the programmatic generator, use the core configuration objects imported from `package:ffigen/ffigen.dart`:
### 1. `FfiGenerator`
The parent class that orchestrates the configuration, parsing, and code generation.
```dart
FfiGenerator({
Headers headers = const Headers(),
Enums enums = Enums.excludeAll,
Functions functions = Functions.excludeAll,
Globals globals = Globals.excludeAll,
Integers integers = const Integers(),
Macros macros = Macros.excludeAll,
Structs structs = Structs.excludeAll,
Typedefs typedefs = Typedefs.excludeAll,
Unions unions = Unions.excludeAll,
UnnamedEnums unnamedEnums = UnnamedEnums.excludeAll,
ObjectiveC? objectiveC,
required Output output,
}).generate();
```
### 2. `Headers`
Configures Clang header parsing targets and compiler flags.
* `entryPoints`: A list of target header `Uri` inputs.
* `include`: A filter function `bool Function(Uri header)` that handles transitive header imports.
* `compilerOptions`: Custom preprocessor/include compiler flags to pass directly to libclang.
* `ignoreSourceErrors`: Set to `true` to silence errors occurring inside third-party headers during parsing.
### 3. `Functions`
Specifies which native C/C++ functions to expose in Dart.
* `include`: A matcher function (e.g. `(decl) => {'my_func'}.contains(decl.originalName)` or `Functions.includeSet({'my_func'})`).
* `isLeaf`: Declares functions as leaf functions (`(decl) => true`) if they do not call back into Dart or block thread execution.
* `recordUse`: Enables metadata generation for native asset tree shaking (essential in `dart-lang/native`). Set to `(_) => true`.
### 4. `Output`
Configures target generated files.
* `dartFile`: Target `Uri` where the primary FFI bindings will be written.
* `recordUseMapping`: Target `Uri` for recorded usage metadata maps (crucial for linking-time tree shaking).
* `preamble`: Text inserted at the top of the generated file (licensing, annotations).
* `format`: Set to `true` to run the Dart formatter automatically.
## Step-by-Step Workflow
### Step 1: Check/Add Dependencies
Open the package's `pubspec.yaml` and verify the `dev_dependencies` contains `ffigen`. Use the Dart MCP server or look up the latest version on [pub.dev](https://pub.dev/packages/ffigen) (e.g., `^20.1.1`).
You can add it automatically using the CLI:
```bash
dart pub add dev:ffigen
```
### Step 2: Formulate Paths Dynamically
Create a programmatic generator script under the package's `tool/` directory (e.g., `tool/ffigen.dart`).
Resolve paths relative to `Platform.script` to make sure it runs successfully from any working directory:
```dart
final packageRoot = Platform.script.resolve('../');
final headerFile = packageRoot.resolve('third_party/library.h');
final targetBindings = packageRoot.resolve('lib/src/third_party/bindings.g.dart');
```
### Step 3: Write the Script (`tool/ffigen.dart`)
Define `void main()` and run `FfiGenerator` with dynamic options (see complete example below).
### Step 4: Run Code Generation
Execute the script from the terminal inside the target package folder:
```bash
dart run tool/ffigen.dart
```
### Step 5: Static Analysis
Verify that the generated bindings are correct and resolve any analysis issues. FFIgen automatically runs the Dart formatter on the output file (via `format: true` configuration), so manual formatting is not required.
1. Run the static analyzer inside the target package:
```bash
dart analyze
```
2. **Addressing Warnings/Lints**: If `dart analyze` reports style or lint warnings inside the generated file, append the corresponding warning codes to the `ignore_for_file:` list in your generator script's `preamble` configuration (e.g., adding `camel_case_types`, `non_constant_identifier_names`, etc.). Do not modify the package's global rules.
3. **Addressing Compilation Errors**: If `dart analyze` reports actual compiler or analysis errors (not warnings) inside the generated file, do not attempt to edit the generated file manually. Report these error details directly to the user so they can file an issue on the repository at [github.com/dart-lang/native](https://github.com/dart-lang/native).
## Concrete Example: Binding a C Library
Let's assume we are working with the SQLite package under `pkgs/code_assets/example/sqlite`, which embeds SQLite C library sources inside `third_party/sqlite/` and accesses it via FFI.
### The C Header File (`third_party/sqlite/sqlite3.h`)
```c
// The author disclaims copyright to this source code.
#ifndef SQLITE3_H_
#define SQLITE3_H_
const char *sqlite3_libversion(void);
#endif // SQLITE3_H_
```
### BEFORE: Manual FFI Binding (The Anti-Pattern)
A developer might attempt to handcraft this integration. It is fragile, blocks tree-shaking metadata, and is highly prone to ABI and structural mapping issues:
```dart
// lib/src/sqlite3_manual.dart
import 'dart:ffi' as ffi;
import 'package:ffi/ffi.dart';
// Flaw 1: Hardcoded DynamicLibrary lookup blocks integration with modern native asset compilation.
final ffi.DynamicLibrary _dylib = ffi.DynamicLibrary.open('libsqlite3.so');
// Flaw 2: Manual function type matching requires writing redundant dynamic lookup boilerplate and lacks tree-shaking metadata.
typedef _sqlite3_libversion_C = ffi.Pointer<ffi.Char> Function();
typedef _sqlite3_libversion_Dart = ffi.Pointer<ffi.Char> Function();
final _sqlite3_libversion_Dart sqlite3LibVersion = _dylib
.lookup<ffi.NativeFunction<_sqlite3_libversion_C>>('sqlite3_libversion')
.asFunction();
```
### AFTER: Generating via FFIgen (The Correct Pattern)
Create a programmatic script at `tool/ffigen.dart`:
```dart
// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
import 'dart:io';
import 'package:ffigen/ffigen.dart';
void main() {
// Resolve paths dynamically relative to Platform.script
final packageRoot = Platform.script.resolve('../');
final entryHeader = packageRoot.resolve('third_party/sqlite/sqlite3.h');
final bindingsOutput = packageRoot.resolve('lib/src/third_party/sqlite3.g.dart');
final treeShakeMapping = packageRoot.resolve('lib/src/third_party/sqlite3.record_use_mapping.g.dart');
FfiGenerator(
headers: Headers(
entryPoints: [entryHeader],
),
functions: Functions(
include: (decl) => {'sqlite3_libversion'}.contains(decl.originalName),
// Essential for package optimization and tree-shaking
recordUse: (_) => true,
),
output: Output(
dartFile: bindingsOutput,
recordUseMapping: treeShakeMapping,
format: true,
preamble: '''
// AUTO-GENERATED FILE - DO NOT MODIFY.
// Generated via ffigen.
// To regenerate: dart run tool/ffigen.dart
// ignore_for_file: type=lint, unused_import, unused_element, deprecated_member_use_from_same_package, experimental_member_use
''',
),
).generate();
print('Successfully generated sqlite3 FFI bindings.');
}
```
### Running the Generator script
Run this in the package root directory:
```bash
dart run tool/ffigen.dart
```
This will automatically create:
1. `lib/src/third_party/sqlite3.g.dart`
2. `lib/src/third_party/sqlite3.record_use_mapping.g.dart`
## Verification Checklist
Always perform the following verification before completing a binding generation task:
1. **Correct Setup**: Verify the target generated files are inside `lib/src/third_party/` (required for third-party licensed code) and the primary FFI bindings file strictly uses the `.g.dart` extension.
2. **Static Analysis**: Run `dart analyze` and ensure there are zero compiler/analyzer errors or warnings in the package.
* If static warnings are reported in the generated bindings, suppress them by adding `ignore_for_file` rules to the generator's `preamble` configuration (do not modify global package rules).
* If actual compiler or analyzer errors are reported in the generated bindings, do not edit the generated file manually. Report the details to the user and direct them to file an issue at [github.com/dart-lang/native](https://github.com/dart-lang/native).

146
.agents/skills/dart-use-pattern-matching/SKILL.md Normal file
View File

@ -0,0 +1,146 @@
---
name: dart-use-pattern-matching
description: Use switch expressions and pattern matching where appropriate
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Fri, 24 Apr 2026 15:08:55 GMT
---
# Implementing Dart Patterns
## Contents
- [Pattern Selection Strategy](#pattern-selection-strategy)
- [Switch Statements vs. Expressions](#switch-statements-vs-expressions)
- [Core Pattern Implementations](#core-pattern-implementations)
- [Workflows](#workflows)
- [Examples](#examples)
## Pattern Selection Strategy
Apply specific pattern types based on the data structure and desired outcome. Follow these conditional guidelines:
* **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns to simultaneously check structure and destructure key-value pairs.
* **If handling multiple return values:** Use Record patterns to destructure fields directly into local variables.
* **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns combined with `sealed` classes to ensure exhaustiveness.
* **If matching numeric ranges or conditions:** Use Relational (`>=`, `<=`) and Logical-and (`&&`) patterns.
* **If multiple cases share logic:** Use Logical-or (`||`) patterns to share a single case body or guard clause.
* **If ignoring specific values:** Use the Wildcard pattern (`_`) or a non-matching Rest element (`...`) in collections.
## Switch Statements vs. Expressions
Select the appropriate switch construct based on the execution context:
* **If producing a value:** Use a **switch expression**.
* Syntax: `switch (value) { pattern => expression, }`
* Rule: Each case must be a single expression. No implicit fallthrough. Must be exhaustive.
* **If executing statements or side effects:** Use a **switch statement**.
* Syntax: `switch (value) { case pattern: statements; }`
* Rule: Empty cases fall through to the next case. Non-empty cases implicitly break (no `break` keyword required).
## Core Pattern Implementations
Implement patterns using the following syntax and rules:
* **Logical-or (`||`):** `pattern1 || pattern2`. Both branches must define the exact same set of variables.
* **Logical-and (`&&`):** `pattern1 && pattern2`. Branches must *not* define overlapping variables.
* **Relational:** `==`, `!=`, `<`, `>`, `<=`, `>=` followed by a constant expression.
* **Cast (`as`):** `pattern as Type`. Throws if the value does not match the type. Use to forcibly assert types during destructuring.
* **Null-check (`?`):** `pattern?`. Fails the match if the value is null. Binds the variable to the non-nullable base type.
* **Null-assert (`!`):** `pattern!`. Throws if the value is null.
* **Variable:** `var name` or `Type name`. Binds the matched value to a new local variable.
* **Wildcard (`_`):** Matches any value and discards it.
* **List:** `[pattern1, pattern2]`. Matches lists of exact length unless a Rest element (`...` or `...var rest`) is used.
* **Map:** `{"key": pattern}`. Matches maps containing the specified keys. Ignores unmatched keys.
* **Record:** `(pattern1, named: pattern2)`. Matches records of the exact shape. Use `:var name` to infer the getter name.
* **Object:** `ClassName(field: pattern)`. Matches instances of `ClassName`. Use `:var field` to infer the getter name.
## Workflows
### Task Progress: Implementing Pattern Matching
Copy this checklist to track progress when implementing complex pattern matching logic:
- [ ] Identify the data structure being evaluated (JSON, Record, Class, Enum).
- [ ] Select the appropriate switch construct (Expression for values, Statement for side-effects).
- [ ] Define the required patterns (Object, Map, List, Record).
- [ ] Extract required data using Variable patterns (`var x`, `:var y`).
- [ ] Apply Guard clauses (`when condition`) for logic that cannot be expressed via patterns.
- [ ] Handle unmatched cases using a Wildcard (`_`) or `default` clause (if not using a sealed class).
- [ ] Run exhaustiveness validator.
### Feedback Loop: Exhaustiveness Checking
When switching over `sealed` classes or enums, you must ensure all subtypes are handled.
1. **Run validator:** Execute `dart analyze`.
2. **Review errors:** Look for "The type 'X' is not exhaustively matched by the switch cases" errors.
3. **Fix:** Add the missing Object patterns for the unhandled subtypes, or add a Wildcard (`_`) case if a default fallback is acceptable.
## Examples
### JSON Validation and Destructuring
Use Map and List patterns to validate structure and extract data in a single step.
**Input:**
```dart
var data = {
'user': ['Lily', 13],
};
```
**Implementation:**
```dart
if (data case {'user': [String name, int age]}) {
print('User $name is $age years old.');
} else {
print('Invalid JSON structure.');
}
```
### Algebraic Data Types (Sealed Classes)
Use Object patterns with switch expressions to handle family types exhaustively.
**Implementation:**
```dart
sealed class Shape {}
class Square implements Shape {
final double length;
Square(this.length);
}
class Circle implements Shape {
final double radius;
Circle(this.radius);
}
// Switch expression guarantees exhaustiveness due to `sealed` modifier.
double calculateArea(Shape shape) => switch (shape) {
Square(length: var l) => l * l,
Circle(:var radius) => math.pi * radius * radius,
};
```
### Variable Swapping and Destructuring
Use variable assignment patterns to swap values or extract record fields without temporary variables.
**Implementation:**
```dart
var (a, b) = ('left', 'right');
(b, a) = (a, b); // Swap values
// Destructuring a function return
var (name, age) = getUserInfo();
```
### Guard Clauses and Logical-or
Use `when` to evaluate arbitrary conditions after a pattern matches.
**Implementation:**
```dart
switch (shape) {
case Square(size: var s) || Circle(size: var s) when s > 0:
print('Valid symmetric shape with size $s');
case Square() || Circle():
print('Invalid or empty shape');
default:
print('Unknown shape');
}
```

163
.agents/skills/flutter-add-integration-test/SKILL.md Normal file
View File

@ -0,0 +1,163 @@
---
name: flutter-add-integration-test
description: Configures Flutter Driver for app interaction and converts MCP actions into permanent integration tests. Use when adding integration testing to a project, exploring UI components via MCP, or automating user flows with the integration_test package.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 18:29:20 GMT
---
# Implementing Flutter Integration Tests
## Contents
- [Project Setup and Dependencies](#project-setup-and-dependencies)
- [Interactive Exploration via MCP](#interactive-exploration-via-mcp)
- [Test Authoring Guidelines](#test-authoring-guidelines)
- [Execution and Profiling](#execution-and-profiling)
- [Workflow: End-to-End Integration Testing](#workflow-end-to-end-integration-testing)
- [Examples](#examples)
## Project Setup and Dependencies
Configure the project to support integration testing and Flutter Driver extensions.
1. Add required development dependencies to `pubspec.yaml`:
```bash
flutter pub add 'dev:integration_test:{"sdk":"flutter"}'
flutter pub add 'dev:flutter_test:{"sdk":"flutter"}'
```
2. Enable the Flutter Driver extension in your application entry point (typically `lib/main.dart` or a dedicated `lib/main_test.dart`):
- Import `package:flutter_driver/driver_extension.dart`.
- Call `enableFlutterDriverExtension();` before `runApp()`.
3. Add `Key` parameters (e.g., `ValueKey('login_button')`) to critical widgets in the application code to ensure reliable targeting during tests.
## Interactive Exploration via MCP
Use the Dart/Flutter MCP server tools to interactively explore and manipulate the application state before writing static tests.
- **Launch**: Execute `launch_app` with `target: "lib/main_test.dart"` to start the application and acquire the DTD URI.
- **Inspect**: Execute `get_widget_tree` to discover available `Key`s, `Text` nodes, and widget `Type`s.
- **Interact**: Execute `tap`, `enter_text`, and `scroll` to simulate user flows.
- **Wait**: Always execute `waitFor` or verify state with `get_health` when navigating or triggering animations.
- **Troubleshoot Unmounted Widgets**: If a widget is not found in the tree, it may be lazily loaded in a `SliverList` or `ListView`. Execute `scroll` or `scrollIntoView` to force the widget to mount before interacting with it.
## Test Authoring Guidelines
Structure integration tests using the `flutter_test` API paradigm.
- Create a dedicated `integration_test/` directory at the project root.
- Name all test files using the `<name>_test.dart` convention.
- Initialize the binding by calling `IntegrationTestWidgetsFlutterBinding.ensureInitialized();` at the start of `main()`.
- Load the application UI using `await tester.pumpWidget(MyApp());`.
- Trigger frames and wait for animations to complete using `await tester.pumpAndSettle();` after interactions like `tester.tap()`.
- Assert widget visibility using `expect(find.byKey(ValueKey('foo')), findsOneWidget);` or `findsNothing`.
- Scroll to specific off-screen widgets using `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder);`.
**Conditional Logic for Legacy `flutter_driver`:**
- If maintaining or migrating legacy `flutter_driver` tests, use `driver.waitFor()`, `driver.waitForAbsent()`, `driver.tap()`, and `driver.scroll()` instead of the `WidgetTester` APIs.
## Execution and Profiling
Execute tests using the `flutter drive` command. Require a host driver script located in `test_driver/integration_test.dart` that calls `integrationDriver()`.
**Conditional Execution Targets:**
- **If testing on Chrome:** Launch `chromedriver --port=4444` in a separate terminal, then run:
`flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d chrome`
- **If testing headless web:** Run with `-d web-server`.
- **If testing on Android (Local):** Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`.
- **If testing on Firebase Test Lab (Android):**
1. Build debug APK: `flutter build apk --debug`
2. Build test APK: `./gradlew app:assembleAndroidTest`
3. Upload both APKs to the Firebase Test Lab console.
## Workflow: End-to-End Integration Testing
Copy and follow this checklist to implement and verify integration tests.
- [ ] **Task Progress: Setup**
- [ ] Add `integration_test` and `flutter_test` to `pubspec.yaml`.
- [ ] Inject `enableFlutterDriverExtension()` into the app entry point.
- [ ] Assign `ValueKey`s to target widgets.
- [ ] **Task Progress: Exploration**
- [ ] Run `launch_app` via MCP.
- [ ] Map the widget tree using `get_widget_tree`.
- [ ] Validate interaction paths using MCP tools (`tap`, `enter_text`).
- [ ] **Task Progress: Authoring**
- [ ] Create `integration_test/app_test.dart`.
- [ ] Write test cases using `WidgetTester` APIs.
- [ ] Create `test_driver/integration_test.dart` with `integrationDriver()`.
- [ ] **Task Progress: Execution & Feedback Loop**
- [ ] Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`.
- [ ] **Feedback Loop**: Review test output -> If `PumpAndSettleTimedOutException` occurs, check for infinite animations -> If widget not found, add `scrollUntilVisible` -> Re-run test until passing.
## Examples
### Standard Integration Test (`integration_test/app_test.dart`)
```dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:my_app/main.dart';
void main() {
IntegrationTestWidgetsFlutterBinding.ensureInitialized();
group('End-to-end test', () {
testWidgets('tap on the floating action button, verify counter', (tester) async {
// Load app widget.
await tester.pumpWidget(const MyApp());
// Verify the counter starts at 0.
expect(find.text('0'), findsOneWidget);
// Find the floating action button to tap on.
final fab = find.byKey(const ValueKey('increment'));
// Emulate a tap on the floating action button.
await tester.tap(fab);
// Trigger a frame and wait for animations.
await tester.pumpAndSettle();
// Verify the counter increments by 1.
expect(find.text('1'), findsOneWidget);
});
});
}
```
### Host Driver Script (`test_driver/integration_test.dart`)
```dart
import 'package:integration_test/integration_test_driver.dart';
Future<void> main() => integrationDriver();
```
### Performance Profiling Driver Script (`test_driver/perf_driver.dart`)
Use this driver script if you wrap your test actions in `binding.traceAction()` to capture performance metrics.
```dart
import 'package:flutter_driver/flutter_driver.dart' as driver;
import 'package:integration_test/integration_test_driver.dart';
Future<void> main() {
return integrationDriver(
responseDataCallback: (data) async {
if (data != null) {
final timeline = driver.Timeline.fromJson(
data['scrolling_timeline'] as Map<String, dynamic>,
);
final summary = driver.TimelineSummary.summarize(timeline);
await summary.writeTimelineToFile(
'scrolling_timeline',
pretty: true,
includeSummary: true,
);
}
},
);
}
```

145
.agents/skills/flutter-add-widget-preview/SKILL.md Normal file
View File

@ -0,0 +1,145 @@
---
name: flutter-add-widget-preview
description: Adds interactive widget previews to the project using the previews.dart system. Use when creating new UI components or updating existing screens to ensure consistent design and interactive testing.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 20:05:23 GMT
---
# Previewing Flutter Widgets
## Contents
- [Preview Guidelines](#preview-guidelines)
- [Handling Limitations](#handling-limitations)
- [Workflows](#workflows)
- [Examples](#examples)
## Preview Guidelines
Use the Flutter Widget Previewer to render widgets in real-time, isolated from the full application context.
- **Target Elements:** Apply the `@Preview` annotation to top-level functions, static methods within a class, or public widget constructors/factories that have no required arguments and return a `Widget` or `WidgetBuilder`.
- **Imports:** Always import `package:flutter/widget_previews.dart` to access the preview annotations.
- **Custom Annotations:** Extend the `Preview` class to create custom annotations that inject common properties (e.g., themes, wrappers) across multiple widgets.
- **Multiple Configurations:** Apply multiple `@Preview` annotations to a single target to generate multiple preview instances. Alternatively, extend `MultiPreview` to encapsulate common multi-preview configurations.
- **Runtime Transformations:** Override the `transform()` method in custom `Preview` or `MultiPreview` classes to modify preview configurations dynamically at runtime (e.g., generating names based on dynamic values, which is impossible in a `const` context).
## Handling Limitations
Adhere to the following constraints when authoring previewable widgets, as the Widget Previewer runs in a web environment:
- **No Native APIs:** Do not use native plugins or APIs from `dart:io` or `dart:ffi`. Widgets with transitive dependencies on `dart:io` or `dart:ffi` will throw exceptions upon invocation. Use conditional imports to mock or bypass these in preview mode.
- **Asset Paths:** Use package-based paths for assets loaded via `dart:ui` `fromAsset` APIs (e.g., `packages/my_package_name/assets/my_image.png` instead of `assets/my_image.png`).
- **Public Callbacks:** Ensure all callback arguments provided to preview annotations are public and constant to satisfy code generation requirements.
- **Constraints:** Apply explicit constraints using the `size` parameter in the `@Preview` annotation if your widget is unconstrained, as the previewer defaults to constraining them to approximately half the viewport.
## Workflows
### Creating a Widget Preview
Copy and track this checklist when implementing a new widget preview:
- [ ] Import `package:flutter/widget_previews.dart`.
- [ ] Identify a valid target (top-level function, static method, or parameter-less public constructor).
- [ ] Apply the `@Preview` annotation to the target.
- [ ] Configure preview parameters (`name`, `group`, `size`, `theme`, `brightness`, etc.) as needed.
- [ ] If applying the same configuration to multiple widgets, extract the configuration into a custom class extending `Preview`.
### Interacting with Previews
Follow the appropriate conditional workflow to launch and interact with the Widget Previewer:
**If using a supported IDE (Android Studio, IntelliJ, VS Code with Flutter 3.38+):**
1. Launch the IDE. The Widget Previewer starts automatically.
2. Open the "Flutter Widget Preview" tab in the sidebar.
3. Toggle "Filter previews by selected file" at the bottom left if you want to view previews outside the currently active file.
**If using the Command Line:**
1. Navigate to the Flutter project's root directory.
2. Run `flutter widget-preview start`.
3. View the automatically opened Chrome environment.
**Feedback Loop: Preview Iteration**
1. Modify the widget code or preview configuration.
2. Observe the automatic update in the Widget Previewer.
3. If global state (e.g., static initializers) was modified: Click the global hot restart button at the bottom right.
4. If only the local widget state needs resetting: Click the individual hot restart button on the specific preview card.
5. Review errors in the IDE/CLI console -> fix -> repeat.
## Examples
### Basic Preview
```dart
import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';
@Preview(name: 'My Sample Text', group: 'Typography')
Widget mySampleText() {
return const Text('Hello, World!');
}
```
### Custom Preview with Runtime Transformation
```dart
import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';
final class TransformativePreview extends Preview {
const TransformativePreview({
super.name,
super.group,
});
PreviewThemeData _themeBuilder() {
return PreviewThemeData(
materialLight: ThemeData.light(),
materialDark: ThemeData.dark(),
);
}
@override
Preview transform() {
final originalPreview = super.transform();
final builder = originalPreview.toBuilder();
builder
..name = 'Transformed - ${originalPreview.name}'
..theme = _themeBuilder;
return builder.toPreview();
}
}
@TransformativePreview(name: 'Custom Themed Button')
Widget myButton() => const ElevatedButton(onPressed: null, child: Text('Click'));
```
### MultiPreview Implementation
```dart
import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';
/// Creates light and dark mode previews automatically.
final class MultiBrightnessPreview extends MultiPreview {
const MultiBrightnessPreview({required this.name});
final String name;
@override
List<Preview> get previews => const [
Preview(brightness: Brightness.light),
Preview(brightness: Brightness.dark),
];
@override
List<Preview> transform() {
final previews = super.transform();
return previews.map((preview) {
final builder = preview.toBuilder()
..group = 'Brightness'
..name = '$name - ${preview.brightness!.name}';
return builder.toPreview();
}).toList();
}
}
@MultiBrightnessPreview(name: 'Primary Card')
Widget cardPreview() => const Card(child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content')));
```

154
.agents/skills/flutter-add-widget-test/SKILL.md Normal file
View File

@ -0,0 +1,154 @@
---
name: flutter-add-widget-test
description: Implement a component-level test using `WidgetTester` to verify UI rendering and user interactions (tapping, scrolling, entering text). Use when validating that a specific widget displays correct data and responds to events as expected.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 21:15:41 GMT
---
# Writing Flutter Widget Tests
## Contents
- [Setup & Configuration](#setup--configuration)
- [Core Components](#core-components)
- [Workflow: Implementing a Widget Test](#workflow-implementing-a-widget-test)
- [Interaction & State Management](#interaction--state-management)
- [Examples](#examples)
## Setup & Configuration
Ensure the testing environment is properly configured before authoring widget tests.
1. Add the `flutter_test` dependency to the `dev_dependencies` section of `pubspec.yaml`.
2. Place all test files in the `test/` directory at the root of the project.
3. Suffix all test file names with `_test.dart` (e.g., `widget_test.dart`).
## Core Components
Utilize the following `flutter_test` components to interact with and validate the widget tree:
* **`WidgetTester`**: The primary interface for building and interacting with widgets in the test environment. Provided automatically by the `testWidgets()` function.
* **`Finder`**: Locates widgets in the test environment (e.g., `find.text('Submit')`, `find.byType(TextField)`, `find.byKey(Key('submit_btn'))`).
* **`Matcher`**: Verifies the presence or state of widgets located by a `Finder` (e.g., `findsOneWidget`, `findsNothing`, `findsNWidgets(2)`, `matchesGoldenFile`).
## Workflow: Implementing a Widget Test
Copy the following checklist to track progress when implementing a new widget test.
### Task Progress
- [ ] **Step 1: Define the test.** Use `testWidgets('description', (WidgetTester tester) async { ... })`.
- [ ] **Step 2: Build the widget.** Call `await tester.pumpWidget(MyWidget())` to render the UI. Wrap the widget in a `MaterialApp` or `Directionality` widget if it requires inherited directional or theme data.
- [ ] **Step 3: Locate elements.** Instantiate `Finder` objects for the target widgets.
- [ ] **Step 4: Verify initial state.** Use `expect(finder, matcher)` to validate the initial render.
- [ ] **Step 5: Simulate interactions.** Execute gestures or inputs (e.g., `await tester.tap(buttonFinder)`).
- [ ] **Step 6: Rebuild the tree.** Call `await tester.pump()` or `await tester.pumpAndSettle()` to process state changes.
- [ ] **Step 7: Verify updated state.** Use `expect()` to validate the UI after the interaction.
- [ ] **Step 8: Run and validate.** Execute `flutter test test/your_test_file_test.dart`.
- [ ] **Step 9: Feedback Loop.** Review test output -> identify failing matchers -> adjust widget logic or test assertions -> re-run until passing.
## Interaction & State Management
Apply the following conditional logic based on the type of interaction or state change being tested:
* **If testing static rendering:** Call `await tester.pumpWidget()` once, then immediately run `expect()` assertions.
* **If testing standard state changes (e.g., button taps):**
1. Call `await tester.tap(finder)`.
2. Call `await tester.pump()` to trigger a single frame rebuild.
* **If testing animations, transitions, or asynchronous UI updates:**
1. Trigger the action (e.g., `await tester.drag(finder, Offset(500, 0))`).
2. Call `await tester.pumpAndSettle()` to repeatedly pump frames until no more frames are scheduled (animation completes).
* **If testing text input:** Call `await tester.enterText(textFieldFinder, 'Input string')`.
* **If testing items in a dynamic or long list:** Call `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder)` to ensure the target widget is rendered before interacting with it.
## Examples
### High-Fidelity Widget Test Implementation
**Target Widget (`lib/todo_list.dart`):**
```dart
import 'package:flutter/material.dart';
class TodoList extends StatefulWidget {
const TodoList({super.key});
@override
State<TodoList> createState() => _TodoListState();
}
class _TodoListState extends State<TodoList> {
final todos = <String>[];
final controller = TextEditingController();
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
body: Column(
children: [
TextField(controller: controller),
Expanded(
child: ListView.builder(
itemCount: todos.length,
itemBuilder: (context, index) {
final todo = todos[index];
return Dismissible(
key: Key('$todo$index'),
onDismissed: (_) => setState(() => todos.removeAt(index)),
child: ListTile(title: Text(todo)),
);
},
),
),
],
),
floatingActionButton: FloatingActionButton(
onPressed: () {
setState(() {
todos.add(controller.text);
controller.clear();
});
},
child: const Icon(Icons.add),
),
),
);
}
}
```
**Test Implementation (`test/todo_list_test.dart`):**
```dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:my_app/todo_list.dart';
void main() {
testWidgets('Add and remove a todo item', (WidgetTester tester) async {
// 1. Build the widget
await tester.pumpWidget(const TodoList());
// 2. Verify initial state
expect(find.byType(ListTile), findsNothing);
// 3. Enter text into the TextField
await tester.enterText(find.byType(TextField), 'Buy groceries');
// 4. Tap the add button
await tester.tap(find.byType(FloatingActionButton));
// 5. Rebuild the widget to reflect the new state
await tester.pump();
// 6. Verify the item was added
expect(find.text('Buy groceries'), findsOneWidget);
// 7. Swipe the item to dismiss it
await tester.drag(find.byType(Dismissible), const Offset(500, 0));
// 8. Build the widget until the dismiss animation ends
await tester.pumpAndSettle();
// 9. Verify the item was removed
expect(find.text('Buy groceries'), findsNothing);
});
}
```

162
.agents/skills/flutter-apply-architecture-best-practices/SKILL.md Normal file
View File

@ -0,0 +1,162 @@
---
name: flutter-apply-architecture-best-practices
description: Architects a Flutter application using the recommended layered approach (UI, Logic, Data). Use when structuring a new project or refactoring for scalability.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 20:11:20 GMT
---
# Architecting Flutter Applications
## Contents
- [Architectural Layers](#architectural-layers)
- [Project Structure](#project-structure)
- [Workflow: Implementing a New Feature](#workflow-implementing-a-new-feature)
- [Examples](#examples)
## Architectural Layers
Enforce strict Separation of Concerns by dividing the application into distinct layers. Never mix UI rendering with business logic or data fetching.
### UI Layer (Presentation)
Implement the MVVM (Model-View-ViewModel) pattern to manage UI state and logic.
* **Views:** Write reusable, lean widgets. Restrict logic in Views to UI-specific operations (e.g., animations, layout constraints, simple routing). Pass all required data from the ViewModel.
* **ViewModels:** Manage UI state and handle user interactions. Extend `ChangeNotifier` (or use `Listenable`) to expose state. Expose immutable state snapshots to the View. Inject Repositories into ViewModels via the constructor.
### Data Layer
Implement the Repository pattern to isolate data access logic and create a single source of truth.
* **Services:** Create stateless classes to wrap external APIs (HTTP clients, local databases, platform plugins). Return raw API models or `Result` wrappers.
* **Repositories:** Consume one or more Services. Transform raw API models into clean Domain Models. Handle caching, offline synchronization, and retry logic. Expose Domain Models to ViewModels.
### Logic Layer (Domain - Optional)
* **Use Cases:** Implement this layer only if the application contains complex business logic that clutters the ViewModel, or if logic must be reused across multiple ViewModels. Extract this logic into dedicated Use Case (interactor) classes that sit between ViewModels and Repositories.
## Project Structure
Organize the codebase using a hybrid approach: group UI components by feature, and group Data/Domain components by type.
```text
lib/
├── data/
│ ├── models/ # API models
│ ├── repositories/ # Repository implementations
│ └── services/ # API clients, local storage wrappers
├── domain/
│ ├── models/ # Clean domain models
│ └── use_cases/ # Optional business logic classes
└── ui/
├── core/ # Shared widgets, themes, typography
└── features/
└── [feature_name]/
├── view_models/
└── views/
```
## Workflow: Implementing a New Feature
Follow this sequential workflow when adding a new feature to the application. Copy the checklist to track progress.
### Task Progress
- [ ] **Step 1: Define Domain Models.** Create immutable data classes for the feature using `freezed` or `built_value`.
- [ ] **Step 2: Implement Services.** Create or update Service classes to handle external API communication.
- [ ] **Step 3: Implement Repositories.** Create the Repository to consume Services and return Domain Models.
- [ ] **Step 4: Apply Conditional Logic (Domain Layer).**
- *If the feature requires complex data transformation or cross-repository logic:* Create a Use Case class.
- *If the feature is a simple CRUD operation:* Skip to Step 5.
- [ ] **Step 5: Implement the ViewModel.** Create the ViewModel extending `ChangeNotifier`. Inject required Repositories/Use Cases. Expose immutable state and command methods.
- [ ] **Step 6: Implement the View.** Create the UI widget. Use `ListenableBuilder` or `AnimatedBuilder` to listen to ViewModel changes.
- [ ] **Step 7: Inject Dependencies.** Register the new Service, Repository, and ViewModel in the dependency injection container (e.g., `provider` or `get_it`).
- [ ] **Step 8: Run Validator.** Execute unit tests for the ViewModel and Repository.
- *Feedback Loop:* Run tests -> Review failures -> Fix logic -> Re-run until passing.
## Examples
### Data Layer: Service and Repository
```dart
// 1. Service (Raw API interaction)
class ApiClient {
Future<UserApiModel> fetchUser(String id) async {
// HTTP GET implementation...
}
}
// 2. Repository (Single source of truth, returns Domain Model)
class UserRepository {
UserRepository({required ApiClient apiClient}) : _apiClient = apiClient;
final ApiClient _apiClient;
User? _cachedUser;
Future<User> getUser(String id) async {
if (_cachedUser != null) return _cachedUser!;
final apiModel = await _apiClient.fetchUser(id);
_cachedUser = User(id: apiModel.id, name: apiModel.fullName); // Transform to Domain Model
return _cachedUser!;
}
}
```
### UI Layer: ViewModel and View
```dart
// 3. ViewModel (State management and presentation logic)
class ProfileViewModel extends ChangeNotifier {
ProfileViewModel({required UserRepository userRepository})
: _userRepository = userRepository;
final UserRepository _userRepository;
User? _user;
User? get user => _user;
bool _isLoading = false;
bool get isLoading => _isLoading;
Future<void> loadProfile(String id) async {
_isLoading = true;
notifyListeners();
try {
_user = await _userRepository.getUser(id);
} finally {
_isLoading = false;
notifyListeners();
}
}
}
// 4. View (Dumb UI component)
class ProfileView extends StatelessWidget {
const ProfileView({super.key, required this.viewModel});
final ProfileViewModel viewModel;
@override
Widget build(BuildContext context) {
return ListenableBuilder(
listenable: viewModel,
builder: (context, _) {
if (viewModel.isLoading) {
return const Center(child: CircularProgressIndicator());
}
final user = viewModel.user;
if (user == null) {
return const Center(child: Text('User not found'));
}
return Column(
children: [
Text(user.name),
ElevatedButton(
onPressed: () => viewModel.loadProfile(user.id),
child: const Text('Refresh'),
),
],
);
},
);
}
}
```

139
.agents/skills/flutter-build-responsive-layout/SKILL.md Normal file
View File

@ -0,0 +1,139 @@
---
name: flutter-build-responsive-layout
description: Use `LayoutBuilder`, `MediaQuery`, or `Expanded/Flexible` to create a layout that adapts to different screen sizes. Use when you need the UI to look good on both mobile and tablet/desktop form factors.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 20:17:40 GMT
---
# Implementing Adaptive Layouts
## Contents
- [Space Measurement Guidelines](#space-measurement-guidelines)
- [Widget Sizing and Constraints](#widget-sizing-and-constraints)
- [Device and Orientation Behaviors](#device-and-orientation-behaviors)
- [Workflow: Constructing an Adaptive Layout](#workflow-constructing-an-adaptive-layout)
- [Workflow: Optimizing for Large Screens](#workflow-optimizing-for-large-screens)
- [Examples](#examples)
## Space Measurement Guidelines
Determine the available space accurately to ensure layouts adapt to the app window, not just the physical device.
* **Use `MediaQuery.sizeOf(context)`** to get the size of the entire app window.
* **Use `LayoutBuilder`** to make layout decisions based on the parent widget's allocated space. Evaluate `constraints.maxWidth` to determine the appropriate widget tree to return.
* **Do not use `MediaQuery.orientationOf` or `OrientationBuilder`** near the top of the widget tree to switch layouts. Device orientation does not accurately reflect the available app window space.
* **Do not check for hardware types** (e.g., "phone" vs. "tablet"). Flutter apps run in resizable windows, multi-window modes, and picture-in-picture. Base all layout decisions strictly on available window space.
## Widget Sizing and Constraints
Understand and apply Flutter's core layout rule: **Constraints go down. Sizes go up. Parent sets position.**
* **Distribute Space:** Use `Expanded` and `Flexible` within `Row`, `Column`, or `Flex` widgets.
* Use `Expanded` to force a child to fill all remaining available space (equivalent to `Flexible` with `fit: FlexFit.tight` and a `flex` factor of 1.0).
* Use `Flexible` to allow a child to size itself up to a specific limit while still expanding/contracting. Use the `flex` factor to define the ratio of space consumption among siblings.
* **Constrain Width:** Prevent widgets from consuming all horizontal space on large screens. Wrap widgets like `GridView` or `ListView` in a `ConstrainedBox` or `Container` and define a `maxWidth` in the `BoxConstraints`.
* **Lazy Rendering:** Always use `ListView.builder` or `GridView.builder` when rendering lists with an unknown or large number of items.
## Device and Orientation Behaviors
Ensure the app behaves correctly across all device form factors and input methods.
* **Do not lock screen orientation.** Locking orientation causes severe layout issues on foldable devices, often resulting in letterboxing (the app centered with black borders). Android large format tiers require both portrait and landscape support.
* **Fallback for Locked Orientation:** If business requirements strictly mandate a locked orientation, use the `Display API` to retrieve physical screen dimensions instead of `MediaQuery`. `MediaQuery` fails to receive the larger window size in compatibility modes.
* **Support Multiple Inputs:** Implement support for basic mice, trackpads, and keyboard shortcuts. Ensure touch targets are appropriately sized and keyboard navigation is accessible.
## Workflow: Constructing an Adaptive Layout
Follow this workflow to implement a layout that adapts to the available `BoxConstraints`.
**Task Progress:**
- [ ] Identify the target widget that requires adaptive behavior.
- [ ] Wrap the widget tree in a `LayoutBuilder`.
- [ ] Extract the `constraints.maxWidth` from the builder callback.
- [ ] Define an adaptive breakpoint (e.g., `largeScreenMinWidth = 600`).
- [ ] **If `maxWidth > largeScreenMinWidth`:** Return a large-screen layout (e.g., a `Row` placing a navigation sidebar and content area side-by-side).
- [ ] **If `maxWidth <= largeScreenMinWidth`:** Return a small-screen layout (e.g., a `Column` or standard navigation-style approach).
- [ ] Run validator -> resize the application window -> review layout transitions -> fix overflow errors.
## Workflow: Optimizing for Large Screens
Follow this workflow to prevent UI elements from stretching unnaturally on large displays.
**Task Progress:**
- [ ] Identify full-width components (e.g., `ListView`, text blocks, forms).
- [ ] **If optimizing a list:** Convert `ListView.builder` to `GridView.builder` using `SliverGridDelegateWithMaxCrossAxisExtent` to automatically adjust column counts based on window size.
- [ ] **If optimizing a form or text block:** Wrap the component in a `ConstrainedBox`.
- [ ] Apply `BoxConstraints(maxWidth: [optimal_width])` to the `ConstrainedBox`.
- [ ] Wrap the `ConstrainedBox` in a `Center` widget to keep the constrained content centered on large screens.
- [ ] Run validator -> test on desktop/tablet target -> review horizontal stretching -> adjust `maxWidth` or grid extents.
## Examples
### Adaptive Layout using LayoutBuilder
Demonstrates switching between a mobile and desktop layout based on available width.
```dart
import 'package:flutter/material.dart';
const double largeScreenMinWidth = 600.0;
class AdaptiveLayout extends StatelessWidget {
const AdaptiveLayout({super.key});
@override
Widget build(BuildContext context) {
return LayoutBuilder(
builder: (context, constraints) {
if (constraints.maxWidth > largeScreenMinWidth) {
return _buildLargeScreenLayout();
} else {
return _buildSmallScreenLayout();
}
},
);
}
Widget _buildLargeScreenLayout() {
return Row(
children: [
const SizedBox(width: 250, child: Placeholder(color: Colors.blue)),
const VerticalDivider(width: 1),
Expanded(child: const Placeholder(color: Colors.green)),
],
);
}
Widget _buildSmallScreenLayout() {
return const Placeholder(color: Colors.green);
}
}
```
### Constraining Width on Large Screens
Demonstrates preventing a widget from consuming all horizontal space.
```dart
import 'package:flutter/material.dart';
class ConstrainedContent extends StatelessWidget {
const ConstrainedContent({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
body: Center(
child: ConstrainedBox(
constraints: const BoxConstraints(
maxWidth: 800.0, // Maximum width for readability
),
child: ListView.builder(
itemCount: 50,
itemBuilder: (context, index) {
return ListTile(
title: Text('Item $index'),
);
},
),
),
),
);
}
}
```

130
.agents/skills/flutter-fix-layout-issues/SKILL.md Normal file
View File

@ -0,0 +1,130 @@
---
name: flutter-fix-layout-issues
description: Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 19:45:59 GMT
---
# Resolving Flutter Layout Errors
## Contents
- [Constraint Violation Diagnostics](#constraint-violation-diagnostics)
- [Layout Error Resolution Workflow](#layout-error-resolution-workflow)
- [Examples](#examples)
## Constraint Violation Diagnostics
Flutter layout operates on a strict rule: **Constraints go down. Sizes go up. Parent sets position.** Layout errors occur when this negotiation fails, typically due to unbounded constraints or unconstrained children.
Diagnose layout failures using the following error signatures:
* **"Vertical viewport was given unbounded height"**: Triggered when a scrollable widget (`ListView`, `GridView`) is placed inside an unconstrained vertical parent (`Column`). The parent provides infinite height, and the child attempts to expand infinitely.
* **"An InputDecorator...cannot have an unbounded width"**: Triggered when a `TextField` or `TextFormField` is placed inside an unconstrained horizontal parent (`Row`). The text field attempts to determine its width based on infinite available space.
* **"RenderFlex overflowed"**: Triggered when a child of a `Row` or `Column` requests a size larger than the parent's allocated constraints. Visually indicated by yellow and black warning stripes.
* **"Incorrect use of ParentData widget"**: Triggered when a `ParentDataWidget` is not a direct descendant of its required ancestor. (e.g., `Expanded` outside a `Flex`, `Positioned` outside a `Stack`).
* **"RenderBox was not laid out"**: A cascading side-effect error. Ignore this and look further up the stack trace for the primary constraint violation (usually an unbounded height/width error).
## Layout Error Resolution Workflow
Copy and use this checklist to systematically resolve layout constraint violations.
### Task Progress
- [ ] Run the application in debug mode to capture the exact layout exception in the console.
- [ ] Identify the primary error message (ignore cascading "RenderBox was not laid out" errors).
- [ ] Apply the conditional fix based on the specific error type:
- **If "Vertical viewport was given unbounded height"**: Wrap the scrollable child (`ListView`, `GridView`) in an `Expanded` widget to consume remaining space, or wrap it in a `SizedBox` to provide an absolute height constraint.
- **If "An InputDecorator...cannot have an unbounded width"**: Wrap the `TextField` or `TextFormField` in an `Expanded` or `Flexible` widget.
- **If "RenderFlex overflowed"**: Constrain the overflowing child by wrapping it in an `Expanded` widget (to force it to fit) or a `Flexible` widget (to allow it to be smaller than the allocated space).
- **If "Incorrect use of ParentData widget"**: Move the `ParentDataWidget` to be a direct child of its required parent. Ensure `Expanded`/`Flexible` are direct children of `Row`/`Column`/`Flex`. Ensure `Positioned` is a direct child of `Stack`.
- [ ] Execute Flutter hot reload.
- [ ] Run validator -> review errors -> fix: Inspect the UI to verify the red/grey error screen or yellow/black overflow stripes are resolved. If new layout errors appear, repeat the workflow.
## Examples
### Fixing Unbounded Height (ListView in Column)
**Input (Error State):**
```dart
// Throws "Vertical viewport was given unbounded height"
Column(
children: <Widget>[
const Text('Header'),
ListView(
children: const <Widget>[
ListTile(title: Text('Item 1')),
ListTile(title: Text('Item 2')),
],
),
],
)
```
**Output (Resolved State):**
```dart
// Wrap ListView in Expanded to constrain its height to the remaining Column space
Column(
children: <Widget>[
const Text('Header'),
Expanded(
child: ListView(
children: const <Widget>[
ListTile(title: Text('Item 1')),
ListTile(title: Text('Item 2')),
],
),
),
],
)
```
### Fixing Unbounded Width (TextField in Row)
**Input (Error State):**
```dart
// Throws "An InputDecorator...cannot have an unbounded width"
Row(
children: [
const Icon(Icons.search),
TextField(),
],
)
```
**Output (Resolved State):**
```dart
// Wrap TextField in Expanded to constrain its width to the remaining Row space
Row(
children: [
const Icon(Icons.search),
Expanded(
child: TextField(),
),
],
)
```
### Fixing RenderFlex Overflow
**Input (Error State):**
```dart
// Throws "A RenderFlex overflowed by X pixels on the right"
Row(
children: [
const Icon(Icons.info),
const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
],
)
```
**Output (Resolved State):**
```dart
// Wrap the Text widget in Expanded to force it to wrap within the available constraints
Row(
children: [
const Icon(Icons.info),
Expanded(
child: const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
),
],
)
```

153
.agents/skills/flutter-implement-json-serialization/SKILL.md Normal file
View File

@ -0,0 +1,153 @@
---
name: flutter-implement-json-serialization
description: Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 21:44:50 GMT
---
# Serializing JSON Manually in Flutter
## Contents
- [Core Guidelines](#core-guidelines)
- [Workflow: Implementing a Serializable Model](#workflow-implementing-a-serializable-model)
- [Workflow: Fetching and Parsing JSON](#workflow-fetching-and-parsing-json)
- [Examples](#examples)
## Core Guidelines
- **Import `dart:convert`**: Utilize Flutter's built-in `dart:convert` library for manual JSON encoding (`jsonEncode`) and decoding (`jsonDecode`).
- **Enforce Type Safety**: Always cast the `dynamic` result of `jsonDecode()` to the expected type, typically `Map<String, dynamic>` for objects or `List<dynamic>` for arrays.
- **Encapsulate Serialization Logic**: Define plain model classes containing properties corresponding to the JSON structure. Implement a `fromJson` factory constructor and a `toJson` method within the model.
- **Handle Background Parsing**: If parsing large JSON documents (execution time > 16ms), offload the parsing logic to a separate isolate using Flutter's `compute()` function to prevent UI jank.
- **Throw Exceptions on Failure**: When handling HTTP responses, throw an exception if the status code is not successful (e.g., not 200 OK or 201 Created). Do not return `null`.
## Workflow: Implementing a Serializable Model
Use this checklist to implement manual JSON serialization for a data model.
**Task Progress:**
- [ ] Define the plain model class with `final` properties.
- [ ] Implement the `factory Model.fromJson(Map<String, dynamic> json)` constructor.
- [ ] Implement the `Map<String, dynamic> toJson()` method.
- [ ] Write unit tests for both serialization methods.
- [ ] Run validator -> review type mismatch errors -> fix casting logic.
1. **Define the Model**: Create a class with properties matching the JSON keys.
2. **Implement `fromJson`**: Extract values from the `Map` and cast them to the appropriate Dart types. Use pattern matching or explicit casting.
3. **Implement `toJson`**: Return a `Map<String, dynamic>` mapping the class properties back to their JSON string keys.
4. **Validate**: Execute unit tests to ensure type safety, autocompletion, and compile-time exception handling function correctly.
## Workflow: Fetching and Parsing JSON
Use this conditional workflow when retrieving and parsing JSON from a network request.
**Task Progress:**
- [ ] Execute the HTTP request.
- [ ] Validate the response status code.
- [ ] Determine parsing strategy (Synchronous vs. Isolate).
- [ ] Decode and map the JSON to the model.
1. **Execute Request**: Use the `http` package to perform the network call.
2. **Validate Response**:
- If `response.statusCode == 200` (or 201 for POST), proceed to parsing.
- If the status code indicates failure, throw an `Exception`.
3. **Determine Parsing Strategy**:
- If parsing a **small payload** (e.g., a single object), parse synchronously on the main thread.
- If parsing a **large payload** (e.g., an array of thousands of objects), use `compute(parseFunction, response.body)` to parse in a background isolate.
4. **Decode and Map**: Pass the decoded JSON to your model's `fromJson` constructor.
## Examples
### High-Fidelity Model Implementation
```dart
import 'dart:convert';
class User {
final int id;
final String name;
final String email;
const User({
required this.id,
required this.name,
required this.email,
});
// Factory constructor for deserialization
factory User.fromJson(Map<String, dynamic> json) {
return switch (json) {
{
'id': int id,
'name': String name,
'email': String email,
} =>
User(
id: id,
name: name,
email: email,
),
_ => throw const FormatException('Failed to load User.'),
};
}
// Method for serialization
Map<String, dynamic> toJson() {
return {
'id': id,
'name': name,
'email': email,
};
}
}
```
### Synchronous Parsing (Small Payload)
```dart
import 'dart:convert';
import 'package:http/http.dart' as http;
Future<User> fetchUser(http.Client client, int userId) async {
final response = await client.get(
Uri.parse('https://api.example.com/users/$userId'),
headers: {'Accept': 'application/json'},
);
if (response.statusCode == 200) {
// Decode returns dynamic, cast to Map<String, dynamic>
final Map<String, dynamic> jsonMap = jsonDecode(response.body) as Map<String, dynamic>;
return User.fromJson(jsonMap);
} else {
throw Exception('Failed to load user');
}
}
```
### Background Parsing (Large Payload)
```dart
import 'dart:convert';
import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;
// Top-level function required for compute()
List<User> parseUsers(String responseBody) {
final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
return parsed.map<User>((json) => User.fromJson(json)).toList();
}
Future<List<User>> fetchUsers(http.Client client) async {
final response = await client.get(
Uri.parse('https://api.example.com/users'),
headers: {'Accept': 'application/json'},
);
if (response.statusCode == 200) {
// Offload expensive parsing to a background isolate
return compute(parseUsers, response.body);
} else {
throw Exception('Failed to load users');
}
}
```

255
.agents/skills/flutter-setup-declarative-routing/SKILL.md Normal file
View File

@ -0,0 +1,255 @@
---
name: flutter-setup-declarative-routing
description: Configure `MaterialApp.router` using a package like `go_router` for advanced URL-based navigation. Use when developing web applications or mobile apps that require specific deep linking and browser history support.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 21:08:03 GMT
---
# Implementing Routing and Deep Linking
## Contents
- [Core Concepts](#core-concepts)
- [Workflow: Initializing the Application and Router](#workflow-initializing-the-application-and-router)
- [Workflow: Configuring Platform Deep Linking](#workflow-configuring-platform-deep-linking)
- [Workflow: Implementing Nested Navigation](#workflow-implementing-nested-navigation)
- [Examples](#examples)
## Core Concepts
Use the `go_router` package for declarative routing in Flutter. It provides a robust API for complex routing scenarios, deep linking, and nested navigation.
- **GoRouter**: The central configuration object defining the application's route tree.
- **GoRoute**: A standard route mapping a URL path to a Flutter screen.
- **ShellRoute / StatefulShellRoute**: Wraps child routes in a persistent UI shell (e.g., a `BottomNavigationBar`). `StatefulShellRoute` maintains the state of parallel navigation branches.
- **Path URL Strategy**: Removes the default `#` fragment from web URLs, essential for clean deep linking across platforms.
## Workflow: Initializing the Application and Router
Follow this workflow to bootstrap a new Flutter application with `go_router` and configure the root routing mechanism.
### Task Progress
- [ ] Create the Flutter application.
- [ ] Add the `go_router` dependency.
- [ ] Configure the URL strategy for web/deep linking.
- [ ] Implement the `GoRouter` configuration.
- [ ] Bind the router to `MaterialApp.router`.
### 1. Scaffold the Application
Run the following commands to create the app and add the required routing package:
```bash
flutter create <app-name>
cd <app-name>
flutter pub add go_router
```
### 2. Configure the Router
Define a top-level `GoRouter` instance. Handle authentication or state-based routing using the `redirect` parameter.
```dart
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:flutter_web_plugins/url_strategy.dart';
void main() {
// Use path URL strategy to remove the '#' from web URLs
usePathUrlStrategy();
runApp(const MyApp());
}
final GoRouter _router = GoRouter(
initialLocation: '/',
routes: [
GoRoute(
path: '/',
builder: (context, state) => const HomeScreen(),
routes: [
GoRoute(
path: 'details/:id',
builder: (context, state) => DetailsScreen(id: state.pathParameters['id']!),
),
],
),
],
errorBuilder: (context, state) => ErrorScreen(error: state.error),
);
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp.router(
routerConfig: _router,
title: 'Routing App',
);
}
}
```
## Workflow: Configuring Platform Deep Linking
Configure the native platforms to intercept specific URLs and route them into the Flutter application.
### Task Progress
- [ ] Determine target platforms (iOS, Android, or both).
- [ ] Apply conditional configuration for Android (Manifest + Asset Links).
- [ ] Apply conditional configuration for iOS (Plist + Entitlements + AASA).
- [ ] Run validator -> review errors -> fix.
### If configuring for Android:
1. **Modify `AndroidManifest.xml`**: Add the intent filter inside the `<activity>` tag for `.MainActivity`.
```xml
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="http" android:host="yourdomain.com" />
<data android:scheme="https" />
</intent-filter>
```
2. **Host `assetlinks.json`**: Serve the following JSON at `https://yourdomain.com/.well-known/assetlinks.json`.
```json
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.yourcompany.yourapp",
"sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
}
}]
```
### If configuring for iOS:
1. **Modify `Info.plist`**: Opt-in to Flutter's default deep link handler.
*Note: If using a third-party deep linking plugin (e.g., `app_links`), set this to `NO` to prevent conflicts.*
```xml
<key>FlutterDeepLinkingEnabled</key>
<true/>
```
2. **Modify `Runner.entitlements`**: Add the associated domain.
```xml
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:yourdomain.com</string>
</array>
```
3. **Host `apple-app-site-association`**: Serve the following JSON (without a `.json` extension) at `https://yourdomain.com/.well-known/apple-app-site-association`.
```json
{
"applinks": {
"apps": [],
"details": [{
"appIDs": ["TEAM_ID.com.yourcompany.yourapp"],
"paths": ["*"],
"components": [{"/": "/*"}]
}]
}
}
```
### Validation Loop
Run validator -> review errors -> fix.
- **Android**: Test using ADB.
```bash
adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://yourdomain.com/details/123"' com.yourcompany.yourapp
```
- **iOS**: Test using `xcrun` on a booted simulator.
```bash
xcrun simctl openurl booted https://yourdomain.com/details/123
```
## Workflow: Implementing Nested Navigation
Use `StatefulShellRoute` to implement persistent UI shells (like a bottom navigation bar) that maintain the state of their child routes.
### Task Progress
- [ ] Define `StatefulShellRoute.indexedStack` in the `GoRouter` configuration.
- [ ] Create `StatefulShellBranch` instances for each navigation tab.
- [ ] Implement the shell widget using `StatefulNavigationShell`.
```dart
final GoRouter _router = GoRouter(
initialLocation: '/home',
routes: [
StatefulShellRoute.indexedStack(
builder: (context, state, navigationShell) {
return ScaffoldWithNavBar(navigationShell: navigationShell);
},
branches: [
StatefulShellBranch(
routes: [
GoRoute(
path: '/home',
builder: (context, state) => const HomeScreen(),
),
],
),
StatefulShellBranch(
routes: [
GoRoute(
path: '/settings',
builder: (context, state) => const SettingsScreen(),
),
],
),
],
),
],
);
```
## Examples
### High-Fidelity Shell Widget Implementation
Implement the UI shell that consumes the `StatefulNavigationShell` to handle branch switching.
```dart
class ScaffoldWithNavBar extends StatelessWidget {
const ScaffoldWithNavBar({
required this.navigationShell,
super.key,
});
final StatefulNavigationShell navigationShell;
void _goBranch(int index) {
navigationShell.goBranch(
index,
// Support navigating to the initial location when tapping the active tab.
initialLocation: index == navigationShell.currentIndex,
);
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: navigationShell,
bottomNavigationBar: NavigationBar(
selectedIndex: navigationShell.currentIndex,
onDestinationSelected: _goBranch,
destinations: const [
NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'),
],
),
);
}
}
```
### Programmatic Navigation
Use the `context.go()` and `context.push()` extension methods provided by `go_router`.
```dart
// Replaces the current route stack with the target route (Declarative)
context.go('/details/123');
// Pushes the target route onto the existing stack (Imperative)
context.push('/details/123');
// Navigates using a named route and path parameters
context.goNamed('details', pathParameters: {'id': '123'});
// Pops the current route
context.pop();
```

210
.agents/skills/flutter-setup-localization/SKILL.md Normal file
View File

@ -0,0 +1,210 @@
---
name: flutter-setup-localization
description: Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 21:27:35 GMT
---
# Internationalizing Flutter Applications
## Contents
- [Core Concepts](#core-concepts)
- [Setup Workflow](#setup-workflow)
- [Implementation Workflow](#implementation-workflow)
- [Advanced Formatting](#advanced-formatting)
- [Examples](#examples)
## Core Concepts
Flutter handles internationalization (i18n) and localization (l10n) via the `flutter_localizations` and `intl` packages. The standard approach uses App Resource Bundle (`.arb`) files to define localized strings, which are then compiled into a generated `AppLocalizations` class for type-safe access within the widget tree.
## Setup Workflow
Copy and track this checklist when initializing internationalization in a Flutter project:
- [ ] **Task Progress**
- [ ] 1. Add dependencies to `pubspec.yaml`.
- [ ] 2. Enable the `generate` flag.
- [ ] 3. Create the `l10n.yaml` configuration file.
- [ ] 4. Configure `MaterialApp` or `CupertinoApp`.
### 1. Add Dependencies
Add the required localization packages to the project. Execute the following commands in the terminal:
```bash
flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any
```
Verify your `pubspec.yaml` includes the following under `dependencies`:
```yaml
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any
```
### 2. Enable Code Generation
Open `pubspec.yaml` and enable the `generate` flag within the `flutter` section to automate localization tasks:
```yaml
flutter:
generate: true
```
### 3. Create Configuration File
Create a new file named `l10n.yaml` in the root directory of the Flutter project. Define the input directory, template file, and output file:
```yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
```
### 4. Configure the App Entry Point
Import the generated localizations and the `flutter_localizations` library in your `main.dart`. Inject the delegates and supported locales into your `MaterialApp` or `CupertinoApp`.
```dart
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Adjust path if synthetic-package is false
// ... inside build method
return MaterialApp(
localizationsDelegates: const [
AppLocalizations.delegate,
GlobalMaterialLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
GlobalCupertinoLocalizations.delegate,
],
supportedLocales: const [
Locale('en'), // English
Locale('es'), // Spanish
],
home: const MyHomePage(),
);
```
## Implementation Workflow
Follow this workflow when adding or modifying localized content.
### 1. Define ARB Files
* **If creating NEW content:** Add the base string to the template file (`lib/l10n/app_en.arb`). Include a description for context.
* **If EDITING existing content:** Locate the key in all supported `.arb` files and update the values.
```json
{
"helloWorld": "Hello World!",
"@helloWorld": {
"description": "The conventional newborn programmer greeting"
}
}
```
Create corresponding files for other locales (e.g., `app_es.arb`):
```json
{
"helloWorld": "¡Hola Mundo!"
}
```
### 2. Generate Localization Classes
Run the following command to trigger code generation:
```bash
flutter pub get
```
*Feedback Loop:* Run validator -> review terminal output for ARB syntax errors -> fix missing commas or mismatched placeholders -> re-run `flutter pub get`.
### 3. Consume Localized Strings
Access the localized strings in your widget tree using `AppLocalizations.of(context)`. Ensure the widget calling this is a descendant of `MaterialApp`.
```dart
Text(AppLocalizations.of(context)!.helloWorld)
```
## Advanced Formatting
Use placeholders for dynamic data, plurals, and conditional selects.
### Placeholders
Define parameters within curly braces and specify their type in the metadata object.
```json
"hello": "Hello {userName}",
"@hello": {
"description": "A message with a single parameter",
"placeholders": {
"userName": {
"type": "String",
"example": "Bob"
}
}
}
```
### Plurals
Use the `plural` syntax to handle quantity-based string variations. The `other` case is mandatory.
```json
"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
"@nWombats": {
"description": "A plural message",
"placeholders": {
"count": {
"type": "num",
"format": "compact"
}
}
}
```
### Selects
Use the `select` syntax for conditional strings, such as gendered text.
```json
"pronoun": "{gender, select, male{he} female{she} other{they}}",
"@pronoun": {
"description": "A gendered message",
"placeholders": {
"gender": {
"type": "String"
}
}
}
```
## Examples
### Complete `l10n.yaml`
```yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
use-escaping: true
```
### Complete Widget Implementation
```dart
import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
class GreetingWidget extends StatelessWidget {
final String userName;
final int notificationCount;
const GreetingWidget({
super.key,
required this.userName,
required this.notificationCount,
});
@override
Widget build(BuildContext context) {
final l10n = AppLocalizations.of(context)!;
return Column(
children: [
Text(l10n.hello(userName)),
Text(l10n.nWombats(notificationCount)),
],
);
}
}
```

174
.agents/skills/flutter-use-http-package/SKILL.md Normal file
View File

@ -0,0 +1,174 @@
---
name: flutter-use-http-package
description: Use the `http` package to execute GET, POST, PUT, or DELETE requests. Use when you need to fetch from or send data to a REST API.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 21:36:42 GMT
---
# Implementing Flutter Networking
## Contents
- [Configuration & Permissions](#configuration--permissions)
- [Request Execution & Response Handling](#request-execution--response-handling)
- [Background Parsing](#background-parsing)
- [Workflow: Executing Network Operations](#workflow-executing-network-operations)
- [Examples](#examples)
## Configuration & Permissions
Configure the environment and platform-specific permissions required for network access.
1. Add the `http` package dependency via the terminal:
```bash
flutter pub add http
```
2. Import the package in your Dart files:
```dart
import 'package:http/http.dart' as http;
```
3. Configure Android permissions by adding the Internet permission to `android/app/src/main/AndroidManifest.xml`:
```xml
<uses-permission android:name="android.permission.INTERNET" />
```
4. Configure macOS entitlements by adding the network client key to both `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`:
```xml
<key>com.apple.security.network.client</key>
<true/>
```
## Request Execution & Response Handling
Execute HTTP operations and map responses to strongly typed Dart objects.
* **URIs:** Always parse URL strings using `Uri.parse('your_url')`.
* **Headers:** Inject authorization and content-type headers via the `headers` parameter map. Use `HttpHeaders.authorizationHeader` for auth tokens.
* **Payloads:** For POST and PUT requests, encode the body using `jsonEncode()` from `dart:convert`.
* **Status Validation:** Evaluate `response.statusCode`. Treat `200 OK` (GET/PUT/DELETE) and `201 CREATED` (POST) as success.
* **Error Handling:** Throw explicit exceptions for non-success status codes. Never return `null` on failure, as this prevents `FutureBuilder` from triggering its error state and causes infinite loading indicators.
* **Deserialization:** Parse the raw string using `jsonDecode(response.body)` and map it to a custom Dart object using a factory constructor (e.g., `fromJson`).
## Background Parsing
Offload expensive JSON parsing to a separate Isolate to prevent UI jank (frame drops).
* Import `package:flutter/foundation.dart`.
* Use the `compute()` function to run the parsing logic in a background isolate.
* Ensure the parsing function passed to `compute()` is a top-level function or a static method, as closures or instance methods cannot be passed across isolates.
## Workflow: Executing Network Operations
Use the following checklist to implement and validate network operations.
**Task Progress:**
- [ ] 1. Define the strongly typed Dart model with a `fromJson` factory constructor.
- [ ] 2. Implement the network request method returning a `Future<Model>`.
- [ ] 3. Apply conditional logic based on the operation type:
- **If fetching data (GET):** Append query parameters to the URI.
- **If mutating data (POST/PUT):** Set `'Content-Type': 'application/json; charset=UTF-8'` and attach the `jsonEncode` body.
- **If deleting data (DELETE):** Return an empty model instance on success (`200 OK`).
- [ ] 4. Validate the `statusCode` and throw an `Exception` on failure.
- [ ] 5. Integrate the `Future` into the UI using `FutureBuilder`.
- [ ] 6. Handle `snapshot.hasData`, `snapshot.hasError`, and default to a `CircularProgressIndicator`.
- [ ] 7. **Feedback Loop:** Run the app -> trigger the network request -> review console for unhandled exceptions -> fix parsing or permission errors.
## Examples
### High-Fidelity Implementation: Fetching and Parsing in the Background
```dart
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
// 1. Top-level parsing function for Isolate
List<Photo> parsePhotos(String responseBody) {
final parsed = (jsonDecode(responseBody) as List<Object?>)
.cast<Map<String, Object?>>();
return parsed.map<Photo>(Photo.fromJson).toList();
}
// 2. Network execution with background parsing
Future<List<Photo>> fetchPhotos() async {
final response = await http.get(
Uri.parse('https://jsonplaceholder.typicode.com/photos'),
headers: {
HttpHeaders.authorizationHeader: 'Bearer your_token_here',
HttpHeaders.acceptHeader: 'application/json',
},
);
if (response.statusCode == 200) {
// Offload heavy parsing to a background isolate
return compute(parsePhotos, response.body);
} else {
throw Exception('Failed to load photos. Status: ${response.statusCode}');
}
}
// 3. Strongly typed model
class Photo {
final int id;
final String title;
final String thumbnailUrl;
const Photo({
required this.id,
required this.title,
required this.thumbnailUrl,
});
factory Photo.fromJson(Map<String, dynamic> json) {
return Photo(
id: json['id'] as int,
title: json['title'] as String,
thumbnailUrl: json['thumbnailUrl'] as String,
);
}
}
// 4. UI Integration
class PhotoGallery extends StatefulWidget {
const PhotoGallery({super.key});
@override
State<PhotoGallery> createState() => _PhotoGalleryState();
}
class _PhotoGalleryState extends State<PhotoGallery> {
late Future<List<Photo>> _futurePhotos;
@override
void initState() {
super.initState();
// Initialize Future once to prevent re-fetching on rebuilds
_futurePhotos = fetchPhotos();
}
@override
Widget build(BuildContext context) {
return FutureBuilder<List<Photo>>(
future: _futurePhotos,
builder: (context, snapshot) {
if (snapshot.hasData) {
final photos = snapshot.data!;
return ListView.builder(
itemCount: photos.length,
itemBuilder: (context, index) => ListTile(
leading: Image.network(photos[index].thumbnailUrl),
title: Text(photos[index].title),
),
);
} else if (snapshot.hasError) {
return Center(child: Text('Error: ${snapshot.error}'));
}
// Default loading state
return const Center(child: CircularProgressIndicator());
},
);
}
}
```

782
CLAUDE.md
View File

@ -101,3 +101,785 @@ estimate / refs` sections.
- Run `dart format` + `flutter analyze` (clean) before every commit. - Run `dart format` + `flutter analyze` (clean) before every commit.
- Comments explain intent/trade-offs, not syntax. - Comments explain intent/trade-offs, not syntax.
- Keep the app buttery-smooth and low on CPU/RAM — it's a quick-capture tool. - Keep the app buttery-smooth and low on CPU/RAM — it's a quick-capture tool.
## Flutter/Dart AI rules
_Appended from [flutter/flutter docs/rules/rules.md](https://github.com/flutter/flutter/blob/main/docs/rules/rules.md) via `/home/kuhy/.claude/CLAUDE.md` Flutter AI tooling setup. Re-fetch periodically to stay current._
## AI rules for Flutter
You are an expert in Flutter and Dart development. Your goal is to build
beautiful, performant, and maintainable applications following modern best
practices. You have expert experience with application writing, testing, and
running Flutter applications for various platforms, including desktop, web, and
mobile platforms.
### Interaction Guidelines
* **User Persona:** Assume the user is familiar with programming concepts but
may be new to Dart.
* **Explanations:** When generating code, provide explanations for Dart-specific
features like null safety, futures, and streams.
* **Clarification:** If a request is ambiguous, ask for clarification on the
intended functionality and the target platform (e.g., command-line, web,
server).
* **Dependencies:** When suggesting new dependencies from `pub.dev`, explain
their benefits.
* **Formatting:** Use the `dart_format` tool to ensure consistent code
formatting.
* **Fixes:** Use the `dart_fix` tool to automatically fix many common errors,
and to help code conform to configured analysis options.
* **Linting:** Use the Dart linter with a recommended set of rules to catch
common issues. Use the `analyze_files` tool to run the linter.
### Project Structure
* **Standard Structure:** Assumes a standard Flutter project structure with
`lib/main.dart` as the primary application entry point.
### Flutter style guide
* **SOLID Principles:** Apply SOLID principles throughout the codebase.
* **Concise and Declarative:** Write concise, modern, technical Dart code.
Prefer functional and declarative patterns.
* **Composition over Inheritance:** Favor composition for building complex
widgets and logic.
* **Immutability:** Prefer immutable data structures. Widgets (especially
`StatelessWidget`) should be immutable.
* **State Management:** Separate ephemeral state and app state. Use a state
management solution for app state to handle the separation of concerns.
* **Widgets are for UI:** Everything in Flutter's UI is a widget. Compose
complex UIs from smaller, reusable widgets.
* **Navigation:** Use a modern routing package like `auto_route` or `go_router`.
For more guidelines around navigation, see the section on [routing](#routing).
### Package Management
* **Pub Tool:** To manage packages, use the `pub` tool, if available.
* **External Packages:** If a new feature requires an external package, use the
`pub_dev_search` tool, if it is available. Otherwise, identify the most
suitable and stable package from pub.dev.
* **Adding Dependencies:** To add a regular dependency, use the `pub` tool, if
it is available. Otherwise, run `flutter pub add <package_name>`.
* **Adding Dev Dependencies:** To add a development dependency, use the `pub`
tool, if it is available, with `dev:<package name>`. Otherwise, run `flutter
pub add dev:<package_name>`.
* **Dependency Overrides:** To add a dependency override, use the `pub` tool, if
it is available, with `override:<package name>:1.0.0`. Otherwise, run `flutter
pub add override:<package_name>:1.0.0`.
* **Removing Dependencies:** To remove a dependency, use the `pub` tool, if it
is available. Otherwise, run `dart pub remove <package_name>`.
### Code Quality
* **Code structure:** Adhere to maintainable code structure and separation of
concerns (e.g., UI logic separate from business logic).
* **Naming conventions:** Avoid abbreviations and use meaningful, consistent,
descriptive names for variables, functions, and classes.
* **Conciseness:** Write code that is as short as it can be while remaining
clear.
* **Simplicity:** Write straightforward code. Code that is clever or
obscure is difficult to maintain.
* **Error Handling:** Anticipate and handle potential errors. Don't let your
code fail silently.
* **Styling:**
* Line length: Lines should be 80 characters or fewer.
* Use `PascalCase` for classes, `camelCase` for
members/variables/functions/enums, and `snake_case` for files.
* **Functions:**
* Keep functions short and with a single purpose.
Strive for less than 20 lines.
* **Testing:** Write code with testing in mind. Use the `file`, `process`, and
`platform` packages, if appropriate, so you can inject in-memory and fake
versions of the objects.
* **Logging:** Use the `logging` package instead of `print`.
### Dart Best Practices
* **Effective Dart:** Follow the official Effective Dart guidelines
(https://dart.dev/effective-dart)
* **Class Organization:** Define related classes within the same library file.
For large libraries, export smaller, private libraries from a single top-level
library.
* **Library Organization:** Group related libraries in the same folder.
* **API Documentation:** Add documentation comments to all public APIs,
including classes, constructors, methods, and top-level functions.
* **Comments:** Write clear comments for complex or non-obvious code. Avoid
over-commenting.
* **Trailing Comments:** Don't add trailing comments.
* **Async/Await:** Ensure proper use of `async`/`await` for asynchronous
operations with robust error handling.
* Use `Future`s, `async`, and `await` for asynchronous operations.
* Use `Stream`s for sequences of asynchronous events.
* **Null Safety:** Write code that is soundly null-safe. Leverage Dart's null
safety features. Avoid `!` unless the value is guaranteed to be non-null.
* **Pattern Matching:** Use pattern matching features where they simplify the
code.
* **Records:** Use records to return multiple types in situations where defining
an entire class is cumbersome.
* **Switch Statements:** Prefer using exhaustive `switch` statements or
expressions, which don't require `break` statements.
* **Exception Handling:** Use `try-catch` blocks for handling exceptions, and
use exceptions appropriate for the type of exception. Use custom exceptions
for situations specific to your code.
* **Arrow Functions:** Use arrow syntax for simple one-line functions.
### Flutter Best Practices
* **Immutability:** Widgets (especially `StatelessWidget`) are immutable; when
the UI needs to change, Flutter rebuilds the widget tree.
* **Composition:** Prefer composing smaller widgets over extending existing
ones. Use this to avoid deep widget nesting.
* **Private Widgets:** Use small, private `Widget` classes instead of private
helper methods that return a `Widget`.
* **Build Methods:** Break down large `build()` methods into smaller, reusable
private Widget classes.
* **List Performance:** Use `ListView.builder` or `SliverList` for long lists to
create lazy-loaded lists for performance.
* **Isolates:** Use `compute()` to run expensive calculations in a separate
isolate to avoid blocking the UI thread, such as JSON parsing.
* **Const Constructors:** Use `const` constructors for widgets and in `build()`
methods whenever possible to reduce rebuilds.
* **Build Method Performance:** Avoid performing expensive operations, like
network calls or complex computations, directly within `build()` methods.
### API Design Principles
When building reusable APIs, such as a library, follow these principles.
* **Consider the User:** Design APIs from the perspective of the person who will
be using them. The API should be intuitive and easy to use correctly.
* **Documentation is Essential:** Good documentation is a part of good API
design. It should be clear, concise, and provide examples.
### Application Architecture
* **Separation of Concerns:** Aim for separation of concerns similar to MVC/MVVM, with defined Model,
View, and ViewModel/Controller roles.
* **Logical Layers:** Organize the project into logical layers:
* Presentation (widgets, screens)
* Domain (business logic classes)
* Data (model classes, API clients)
* Core (shared classes, utilities, and extension types)
* **Feature-based Organization:** For larger projects, organize code by feature,
where each feature has its own presentation, domain, and data subfolders. This
improves navigability and scalability.
### Lint Rules
Include the package in the `analysis_options.yaml` file. Use the following
`analysis_options.yaml` file as a starting point:
```yaml
include: package:flutter_lints/flutter.yaml
linter:
rules:
# Add additional lint rules here:
# avoid_print: false
# prefer_single_quotes: true
```
#### State Management
* **Built-in Solutions:** Prefer Flutter's built-in state management solutions.
Do not use a third-party package unless explicitly requested.
* **Streams:** Use `Streams` and `StreamBuilder` for handling a sequence of
asynchronous events.
* **Futures:** Use `Futures` and `FutureBuilder` for handling a single
asynchronous operation that will complete in the future.
* **ValueNotifier:** Use `ValueNotifier` with `ValueListenableBuilder` for
simple, local state that involves a single value.
```dart
// Define a ValueNotifier to hold the state.
final ValueNotifier<int> _counter = ValueNotifier<int>(0);
// Use ValueListenableBuilder to listen and rebuild.
ValueListenableBuilder<int>(
valueListenable: _counter,
builder: (context, value, child) {
return Text('Count: $value');
},
);
```
* **ChangeNotifier:** For state that is more complex or shared across multiple
widgets, use `ChangeNotifier`.
* **ListenableBuilder:** Use `ListenableBuilder` to listen to changes from a
`ChangeNotifier` or other `Listenable`.
* **MVVM:** When a more robust solution is needed, structure the app using the
Model-View-ViewModel (MVVM) pattern.
* **Dependency Injection:** Use simple manual constructor dependency injection
to make a class's dependencies explicit in its API, and to manage dependencies
between different layers of the application.
* **Provider:** If a dependency injection solution beyond manual constructor
injection is explicitly requested, `provider` can be used to make services,
repositories, or complex state objects available to the UI layer without tight
coupling (note: this document generally defaults against third-party packages
for state management unless explicitly requested).
#### Data Flow
* **Data Structures:** Define data structures (classes) to represent the data
used in the application.
* **Data Abstraction:** Abstract data sources (e.g., API calls, database
operations) using Repositories/Services to promote testability.
#### Routing
* **GoRouter:** Use the `go_router` package for declarative navigation, deep
linking, and web support.
* **GoRouter Setup:** To use `go_router`, first add it to your `pubspec.yaml`
using the `pub` tool's `add` command.
```dart
// 1. Add the dependency
// flutter pub add go_router
// 2. Configure the router
final GoRouter _router = GoRouter(
routes: <RouteBase>[
GoRoute(
path: '/',
builder: (context, state) => const HomeScreen(),
routes: <RouteBase>[
GoRoute(
path: 'details/:id', // Route with a path parameter
builder: (context, state) {
final String id = state.pathParameters['id']!;
return DetailScreen(id: id);
},
),
],
),
],
);
// 3. Use it in your MaterialApp
MaterialApp.router(
routerConfig: _router,
);
```
* **Authentication Redirects:** Configure `go_router`'s `redirect` property to
handle authentication flows, ensuring users are redirected to the login screen
when unauthorized, and back to their intended destination after successful
login.
* **Navigator:** Use the built-in `Navigator` for short-lived screens that do
not need to be deep-linkable, such as dialogs or temporary views.
```dart
// Push a new screen onto the stack
Navigator.push(
context,
MaterialPageRoute(builder: (context) => const DetailsScreen()),
);
// Pop the current screen to go back
Navigator.pop(context);
```
#### Data Handling & Serialization
* **JSON Serialization:** Use `json_serializable` and `json_annotation` for
parsing and encoding JSON data.
* **Field Renaming:** When encoding data, use `fieldRename: FieldRename.snake`
to convert Dart's camelCase fields to snake_case JSON keys.
```dart
// In your model file
import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';
@JsonSerializable(fieldRename: FieldRename.snake)
class User {
final String firstName;
final String lastName;
User({required this.firstName, required this.lastName});
factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
Map<String, dynamic> toJson() => _$UserToJson(this);
}
```
#### Logging
* **Structured Logging:** Use the `log` function from `dart:developer` for
structured logging that integrates with Dart DevTools.
```dart
import 'dart:developer' as developer;
// For simple messages
developer.log('User logged in successfully.');
// For structured error logging
try {
// ... code that might fail
} catch (e, s) {
developer.log(
'Failed to fetch data',
name: 'myapp.network',
level: 1000, // SEVERE
error: e,
stackTrace: s,
);
}
```
### Code Generation
* **Build Runner:** If the project uses code generation, ensure that
`build_runner` is listed as a dev dependency in `pubspec.yaml`.
* **Code Generation Tasks:** Use `build_runner` for all code generation tasks,
such as for `json_serializable`.
* **Running Build Runner:** After modifying files that require code generation,
run the build command:
```shell
dart run build_runner build --delete-conflicting-outputs
```
### Testing
* **Running Tests:** To run tests, use the `run_tests` tool if it is available,
otherwise use `flutter test`.
* **Unit Tests:** Use `package:test` for unit tests.
* **Widget Tests:** Use `package:flutter_test` for widget tests.
* **Integration Tests:** Use `package:integration_test` for integration tests.
* **Assertions:** Prefer using `package:checks` for more expressive and readable
assertions over the default `matchers`.
#### Testing Best practices
* **Convention:** Follow the Arrange-Act-Assert (or Given-When-Then) pattern.
* **Unit Tests:** Write unit tests for domain logic, data layer, and state
management.
* **Widget Tests:** Write widget tests for UI components.
* **Integration Tests:** For broader application validation, use integration
tests to verify end-to-end user flows.
* **integration_test package:** Use the `integration_test` package from the
Flutter SDK for integration tests. Add it as a `dev_dependency` in
`pubspec.yaml` by specifying `sdk: flutter`.
* **Mocks:** Prefer fakes or stubs over mocks. If mocks are absolutely
necessary, use `mockito` or `mocktail` to create mocks for dependencies. While
code generation is common for state management (e.g., with `freezed`), try to
avoid it for mocks.
* **Coverage:** Aim for high test coverage.
### Visual Design & Theming
* **UI Design:** Build beautiful and intuitive user interfaces that follow
modern design guidelines.
* **Responsiveness:** Ensure the app is mobile responsive and adapts to
different screen sizes, working perfectly on mobile and web.
* **Navigation:** If there are multiple pages for the user to interact with,
provide an intuitive and easy navigation bar or controls.
* **Typography:** Stress and emphasize font sizes to ease understanding, e.g.,
hero text, section headlines, list headlines, keywords in paragraphs.
* **Background:** Apply subtle noise texture to the main background to add a
premium, tactile feel.
* **Shadows:** Multi-layered drop shadows create a strong sense of depth; cards
have a soft, deep shadow to look "lifted."
* **Icons:** Incorporate icons to enhance the user’s understanding and the
logical navigation of the app.
* **Interactive Elements:** Buttons, checkboxes, sliders, lists, charts, graphs,
and other interactive elements have a shadow with elegant use of color to
create a "glow" effect.
#### Theming
* **Centralized Theme:** Define a centralized `ThemeData` object to ensure a
consistent application-wide style.
* **Light and Dark Themes:** Implement support for both light and dark themes,
ideal for a user-facing theme toggle (`ThemeMode.light`, `ThemeMode.dark`,
`ThemeMode.system`).
* **Color Scheme Generation:** Generate harmonious color palettes from a single
color using `ColorScheme.fromSeed`.
```dart
final ThemeData lightTheme = ThemeData(
colorScheme: ColorScheme.fromSeed(
seedColor: Colors.deepPurple,
brightness: Brightness.light,
),
// ... other theme properties
);
```
* **Color Palette:** Include a wide range of color concentrations and hues in
the palette to create a vibrant and energetic look and feel.
* **Component Themes:** Use specific theme properties (e.g., `appBarTheme`,
`elevatedButtonTheme`) to customize the appearance of individual Material
components.
* **Custom Fonts:** For custom fonts, use the `google_fonts` package. Define a
`TextTheme` to apply fonts consistently.
```dart
// 1. Add the dependency
// flutter pub add google_fonts
// 2. Define a TextTheme with a custom font
final TextTheme appTextTheme = TextTheme(
displayLarge: GoogleFonts.oswald(fontSize: 57, fontWeight: FontWeight.bold),
titleLarge: GoogleFonts.roboto(fontSize: 22, fontWeight: FontWeight.w500),
bodyMedium: GoogleFonts.openSans(fontSize: 14),
);
```
#### Assets and Images
* **Image Guidelines:** If images are needed, make them relevant and meaningful,
with appropriate size, layout, and licensing (e.g., freely available). Provide
placeholder images if real ones are not available.
* **Asset Declaration:** Declare all asset paths in your `pubspec.yaml` file.
```yaml
flutter:
uses-material-design: true
assets:
- assets/images/
```
* **Local Images:** Use `Image.asset` for local images from your asset
bundle.
```dart
Image.asset('assets/images/placeholder.png')
```
* **Network images:** Use NetworkImage for images loaded from the network.
* **Cached images:** For cached images, use NetworkImage a package like
`cached_network_image`.
* **Custom Icons:** Use `ImageIcon` to display an icon from an `ImageProvider`,
useful for custom icons not in the `Icons` class.
* **Network Images:** Use `Image.network` to display images from a URL, and
always include `loadingBuilder` and `errorBuilder` for a better user
experience.
```dart
// When using network images, always provide an errorBuilder.
Image.network(
'https://picsum.photos/200/300',
loadingBuilder: (context, child, progress) {
if (progress == null) return child;
return const Center(child: CircularProgressIndicator());
},
errorBuilder: (context, error, stackTrace) {
return const Icon(Icons.error);
},
)
```
### UI Theming and Styling Code
* **Responsiveness:** Use `LayoutBuilder` or `MediaQuery` to create responsive
UIs.
* **Text:** Use `Theme.of(context).textTheme` for text styles.
* **Text Fields:** Configure `textCapitalization`, `keyboardType`, and
`placeholder`.
### Material Theming Best Practices
#### Embrace `ThemeData` and Material 3
* **Use `ColorScheme.fromSeed()`:** Use this to generate a complete, harmonious
color palette for both light and dark modes from a single seed color.
* **Define Light and Dark Themes:** Provide both `theme` and `darkTheme` to your
`MaterialApp` to support system brightness settings seamlessly.
* **Centralize Component Styles:** Customize specific component themes (e.g.,
`elevatedButtonTheme`, `cardTheme`, `appBarTheme`) within `ThemeData` to
ensure consistency.
* **Dark/Light Mode and Theme Toggle:** Implement support for both light and
dark themes using `theme` and `darkTheme` properties of `MaterialApp`. The
`themeMode` property can be dynamically controlled (e.g., via a
`ChangeNotifierProvider`) to allow for toggling between `ThemeMode.light`,
`ThemeMode.dark`, or `ThemeMode.system`.
```dart
// main.dart
MaterialApp(
theme: ThemeData(
colorScheme: ColorScheme.fromSeed(
seedColor: Colors.deepPurple,
brightness: Brightness.light,
),
textTheme: const TextTheme(
displayLarge: TextStyle(fontSize: 57.0, fontWeight: FontWeight.bold),
bodyMedium: TextStyle(fontSize: 14.0, height: 1.4),
),
),
darkTheme: ThemeData(
colorScheme: ColorScheme.fromSeed(
seedColor: Colors.deepPurple,
brightness: Brightness.dark,
),
),
home: const MyHomePage(),
);
```
#### Implement Design Tokens with `ThemeExtension`
For custom styles that aren't part of the standard `ThemeData`, use
`ThemeExtension` to define reusable design tokens.
* **Create a Custom Theme Extension:** Define a class that extends
`ThemeExtension<T>` and include your custom properties.
* **Implement `copyWith` and `lerp`:** These methods are required for the
extension to work correctly with theme transitions.
* **Register in `ThemeData`:** Add your custom extension to the `extensions`
list in your `ThemeData`.
* **Access Tokens in Widgets:** Use `Theme.of(context).extension<MyColors>()!`
to access your custom tokens.
```dart
// 1. Define the extension
@immutable
class MyColors extends ThemeExtension<MyColors> {
const MyColors({required this.success, required this.danger});
final Color? success;
final Color? danger;
@override
ThemeExtension<MyColors> copyWith({Color? success, Color? danger}) {
return MyColors(success: success ?? this.success, danger: danger ?? this.danger);
}
@override
ThemeExtension<MyColors> lerp(ThemeExtension<MyColors>? other, double t) {
if (other is! MyColors) return this;
return MyColors(
success: Color.lerp(success, other.success, t),
danger: Color.lerp(danger, other.danger, t),
);
}
}
// 2. Register it in ThemeData
theme: ThemeData(
extensions: const <ThemeExtension<dynamic>>[
MyColors(success: Colors.green, danger: Colors.red),
],
),
// 3. Use it in a widget
Container(
color: Theme.of(context).extension<MyColors>()!.success,
)
```
#### Styling with `WidgetStateProperty`
* **`WidgetStateProperty.resolveWith`:** Provide a function that receives a
`Set<WidgetState>` and returns the appropriate value for the current state.
* **`WidgetStateProperty.all`:** A shorthand for when the value is the same for
all states.
```dart
// Example: Creating a button style that changes color when pressed.
final ButtonStyle myButtonStyle = ButtonStyle(
backgroundColor: WidgetStateProperty.resolveWith<Color>(
(Set<WidgetState> states) {
if (states.contains(WidgetState.pressed)) {
return Colors.green; // Color when pressed
}
return Colors.red; // Default color
},
),
);
```
### Layout Best Practices
#### Building Flexible and Overflow-Safe Layouts
##### For Rows and Columns
* **`Expanded`:** Use to make a child widget fill the remaining available space
along the main axis.
* **`Flexible`:** Use when you want a widget to shrink to fit, but not
necessarily grow. Don't combine `Flexible` and `Expanded` in the same `Row` or
`Column`.
* **`Wrap`:** Use when you have a series of widgets that would overflow a `Row`
or `Column`, and you want them to move to the next line.
##### For General Content
* **`SingleChildScrollView`:** Use when your content is intrinsically larger
than the viewport, but is a fixed size.
* **`ListView` / `GridView`:** For long lists or grids of content, always use a
builder constructor (`.builder`).
* **`FittedBox`:** Use to scale or fit a single child widget within its parent.
* **`LayoutBuilder`:** Use for complex, responsive layouts to make decisions
based on the available space.
#### Layering Widgets with Stack
* **`Positioned`:** Use to precisely place a child within a `Stack` by anchoring it to the edges.
* **`Align`:** Use to position a child within a `Stack` using alignments like `Alignment.center`.
#### Advanced Layout with Overlays
* **`OverlayPortal`:** Use this widget to show UI elements (like custom
dropdowns or tooltips) "on top" of everything else. It manages the
`OverlayEntry` for you.
```dart
class MyDropdown extends StatefulWidget {
const MyDropdown({super.key});
@override
State<MyDropdown> createState() => _MyDropdownState();
}
class _MyDropdownState extends State<MyDropdown> {
final _controller = OverlayPortalController();
@override
Widget build(BuildContext context) {
return OverlayPortal(
controller: _controller,
overlayChildBuilder: (BuildContext context) {
return const Positioned(
top: 50,
left: 10,
child: Card(
child: Padding(
padding: EdgeInsets.all(8.0),
child: Text('I am an overlay!'),
),
),
);
},
child: ElevatedButton(
onPressed: _controller.toggle,
child: const Text('Toggle Overlay'),
),
);
}
}
```
### Color Scheme Best Practices
#### Contrast Ratios
* **WCAG Guidelines:** Aim to meet the Web Content Accessibility Guidelines
(WCAG) 2.1 standards.
* **Minimum Contrast:**
* **Normal Text:** A contrast ratio of at least **4.5:1**.
* **Large Text:** (18pt or 14pt bold) A contrast ratio of at least **3:1**.
#### Palette Selection
* **Primary, Secondary, and Accent:** Define a clear color hierarchy.
* **The 60-30-10 Rule:** A classic design rule for creating a balanced color scheme.
* **60%** Primary/Neutral Color (Dominant)
* **30%** Secondary Color
* **10%** Accent Color
#### Complementary Colors
* **Use with Caution:** They can be visually jarring if overused.
* **Best Use Cases:** They are excellent for accent colors to make specific
elements pop, but generally poor for text and background pairings as they can
cause eye strain.
#### Example Palette
* **Primary:** #0D47A1 (Dark Blue)
* **Secondary:** #1976D2 (Medium Blue)
* **Accent:** #FFC107 (Amber)
* **Neutral/Text:** #212121 (Almost Black)
* **Background:** #FEFEFE (Almost White)
### Font Best Practices
#### Font Selection
* **Limit Font Families:** Stick to one or two font families for the entire
application.
* **Prioritize Legibility:** Choose fonts that are easy to read on screens of
all sizes. Sans-serif fonts are generally preferred for UI body text.
* **System Fonts:** Consider using platform-native system fonts.
* **Google Fonts:** For a wide selection of open-source fonts, use the
`google_fonts` package.
#### Hierarchy and Scale
* **Establish a Scale:** Define a set of font sizes for different text elements
(e.g., headlines, titles, body text, captions).
* **Use Font Weight:** Differentiate text effectively using font weights.
* **Color and Opacity:** Use color and opacity to de-emphasize less important
text.
#### Readability
* **Line Height (Leading):** Set an appropriate line height, typically **1.4x to
1.6x** the font size.
* **Line Length:** For body text, aim for a line length of **45-75 characters**.
* **Avoid All Caps:** Do not use all caps for long-form text.
#### Example Typographic Scale
```dart
// In your ThemeData
textTheme: const TextTheme(
displayLarge: TextStyle(fontSize: 57.0, fontWeight: FontWeight.bold),
titleLarge: TextStyle(fontSize: 22.0, fontWeight: FontWeight.bold),
bodyLarge: TextStyle(fontSize: 16.0, height: 1.5),
bodyMedium: TextStyle(fontSize: 14.0, height: 1.4),
labelSmall: TextStyle(fontSize: 11.0, color: Colors.grey),
),
```
### Documentation
* **`dartdoc`:** Write `dartdoc`-style comments for all public APIs.
#### Documentation Philosophy
* **Comment wisely:** Use comments to explain why the code is written a certain
way, not what the code does. The code itself should be self-explanatory.
* **Document for the user:** Write documentation with the reader in mind. If you
had a question and found the answer, add it to the documentation where you
first looked. This ensures the documentation answers real-world questions.
* **No useless documentation:** If the documentation only restates the obvious
from the code's name, it's not helpful. Good documentation provides context
and explains what isn't immediately apparent.
* **Consistency is key:** Use consistent terminology throughout your
documentation.
#### Commenting Style
* **Use `///` for doc comments:** This allows documentation generation tools to
pick them up.
* **Start with a single-sentence summary:** The first sentence should be a
concise, user-centric summary ending with a period.
* **Separate the summary:** Add a blank line after the first sentence to create
a separate paragraph. This helps tools create better summaries.
* **Avoid redundancy:** Don't repeat information that's obvious from the code's
context, like the class name or signature.
* **Don't document both getter and setter:** For properties with both, only
document one. The documentation tool will treat them as a single field.
#### Writing Style
* **Be brief:** Write concisely.
* **Avoid jargon and acronyms:** Don't use abbreviations unless they are widely
understood.
* **Use Markdown sparingly:** Avoid excessive markdown and never use HTML for
formatting.
* **Use backticks for code:** Enclose code blocks in backtick fences, and
specify the language.
#### What to Document
* **Public APIs are a priority:** Always document public APIs.
* **Consider private APIs:** It's a good idea to document private APIs as well.
* **Library-level comments are helpful:** Consider adding a doc comment at the
library level to provide a general overview.
* **Include code samples:** Where appropriate, add code samples to illustrate usage.
* **Explain parameters, return values, and exceptions:** Use prose to describe
what a function expects, what it returns, and what errors it might throw.
* **Place doc comments before annotations:** Documentation should come before
any metadata annotations.
### Accessibility (A11Y)
Implement accessibility features to empower all users, assuming a wide variety
of users with different physical abilities, mental abilities, age groups,
education levels, and learning styles.
* **Color Contrast:** Ensure text has a contrast ratio of at least **4.5:1**
against its background.
* **Dynamic Text Scaling:** Test your UI to ensure it remains usable when users
increase the system font size.
* **Semantic Labels:** Use the `Semantics` widget to provide clear, descriptive
labels for UI elements.
* **Screen Reader Testing:** Regularly test your app with TalkBack (Android) and
VoiceOver (iOS).

131
skills-lock.json Normal file
View File

@ -0,0 +1,131 @@
{
"version": 1,
"skills": {
"dart-add-unit-test": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-add-unit-test/SKILL.md",
"computedHash": "326a2b6cb57bcb4f40203e063a1060e9549a8cea0ece1a5c9a0d39a2f2b85bc8"
},
"dart-build-cli-app": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-build-cli-app/SKILL.md",
"computedHash": "2c693ba718e23155fd9acd8d2e14f5c311258ed900131b2ad12fda46ae5eebfa"
},
"dart-collect-coverage": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-collect-coverage/SKILL.md",
"computedHash": "36d77c4ebc2edc7ade399ae8461776dd33a461899afda4b2b9d8e7f599d2ef6c"
},
"dart-fix-runtime-errors": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-fix-runtime-errors/SKILL.md",
"computedHash": "7b13cb0df76693d8c798432a1f86325b093a35e9687f231a012763fcad54fb2c"
},
"dart-generate-test-mocks": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-generate-test-mocks/SKILL.md",
"computedHash": "7bf12a98d63e96ed51ba077a24426be1b11a9fc508f7dfca60fc6e118c3fc923"
},
"dart-migrate-to-checks-package": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-migrate-to-checks-package/SKILL.md",
"computedHash": "00b7fa026dcf004421650f20147d020244886321f715ff57ee38a96b3a9945bc"
},
"dart-resolve-package-conflicts": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-resolve-package-conflicts/SKILL.md",
"computedHash": "e25c789387152d9d0c437610caa5746e337a789bcb8e9c9887b0425b94b734ef"
},
"dart-run-static-analysis": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-run-static-analysis/SKILL.md",
"computedHash": "e64ea092e216ecdc9b4a8b49b06d0b9a0b49f680c1116ada1d247b2de3fa6fe1"
},
"dart-setup-ffi-assets": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-setup-ffi-assets/SKILL.md",
"computedHash": "c27f5a4e79a4f291e09a9cfeab2842bb04d3570bb64c56bf309e573c3f244ef8"
},
"dart-use-ffigen": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-use-ffigen/SKILL.md",
"computedHash": "688ec3e0218b3a96437916be5bdcaea87fe4f90ba869c3deec2f3392f1c6b626"
},
"dart-use-pattern-matching": {
"source": "dart-lang/skills",
"sourceType": "github",
"skillPath": "skills/dart-use-pattern-matching/SKILL.md",
"computedHash": "86ea49e8f82ebcdbfd00579c0bcaca16d3f33839c96f9d3875bee95c553daa4b"
},
"flutter-add-integration-test": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-add-integration-test/SKILL.md",
"computedHash": "9ead37fef54371fed6ad07a9ba3de7a908135a0867b05baf74c28b7095343999"
},
"flutter-add-widget-preview": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-add-widget-preview/SKILL.md",
"computedHash": "1b59c009558aab7a8e4b7b101fbe535b06054c0672780e9cea7e5c98a9c48dc4"
},
"flutter-add-widget-test": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-add-widget-test/SKILL.md",
"computedHash": "c4f263c59cfe331ef42dba2aa81e25142aa4f7284518907c6b847e04502676b0"
},
"flutter-apply-architecture-best-practices": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-apply-architecture-best-practices/SKILL.md",
"computedHash": "2b1b63214d6b153c50aacd4bbcb76ce91dece449de9e06f477f8aad3163d667f"
},
"flutter-build-responsive-layout": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-build-responsive-layout/SKILL.md",
"computedHash": "f762ea2ee83d4f1f35d9093b41d2520dd024ab80c9539d4860b9ae7f2a4dc6a0"
},
"flutter-fix-layout-issues": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-fix-layout-issues/SKILL.md",
"computedHash": "1aaba922c951159118f9b141788f7bb7b8167bdc0bd5c6f0738ebb90c29b9532"
},
"flutter-implement-json-serialization": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-implement-json-serialization/SKILL.md",
"computedHash": "0eed26f25308d78c6a9036ec936db93342f064d64f2cbac5e0e8648ba6b9db3f"
},
"flutter-setup-declarative-routing": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-setup-declarative-routing/SKILL.md",
"computedHash": "2341440c8bce0f176663695eaa71f9f7d7c967772a1dcd0d833c9778504b227e"
},
"flutter-setup-localization": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-setup-localization/SKILL.md",
"computedHash": "671bf254ca8f3172b6bda5287d9e756e9fd5b49165a815f710c5b707ebaa38f8"
},
"flutter-use-http-package": {
"source": "flutter/skills",
"sourceType": "github",
"skillPath": "skills/flutter-use-http-package/SKILL.md",
"computedHash": "17efcf4da9933afaf9c1d41940bd6b92f1ae73dcae4bf6c59cfe24f7e487ee9f"
}
}
}