reis-mobile 0.3.5

package/skills/flutter-add-widget-preview/SKILL.md

@@ -0,0 +1,149 @@
+---
+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
+routing: manual
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# 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')));
+```

package/skills/flutter-add-widget-test/SKILL.md

@@ -0,0 +1,158 @@
+---
+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
+intents: [test]
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# 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);
+  });
+}
+```

package/skills/flutter-adding-home-screen-widgets/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: flutter-adding-home-screen-widgets
+description: Adds home screen widgets to a Flutter app for Android and iOS. Use when providing glanceable app information or quick actions on the device home screen.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:23:50 GMT
+routing: manual
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Implementing Flutter Home Screen Widgets
+
+## Contents
+- [Architecture & Data Flow](#architecture--data-flow)
+- [Flutter Integration Workflow](#flutter-integration-workflow)
+- [iOS Implementation Workflow](#ios-implementation-workflow)
+- [Android Implementation Workflow](#android-implementation-workflow)
+- [Advanced Techniques](#advanced-techniques)
+- [Examples](#examples)
+
+## Architecture & Data Flow
+Home Screen Widgets require native UI implementation (SwiftUI for iOS, XML/Kotlin for Android). The Flutter app communicates with these native widgets via shared local storage (`UserDefaults` on iOS, `SharedPreferences` on Android) using the `home_widget` package. 
+
+- **Data Write:** Flutter app writes key-value pairs or renders images to a shared container.
+- **Trigger:** Flutter app signals the native OS to update the widget.
+- **Data Read:** Native widget wakes up, reads the key-value pairs or images from the shared container, and updates its UI.
+
+## Flutter Integration Workflow
+
+Use this checklist to implement the Dart side of the Home Screen Widget integration.
+
+- [ ] **Step 1: Initialize the App Group.** Call `HomeWidget.setAppGroupId('<YOUR_APP_GROUP>')` in `initState()` or app startup.
+- [ ] **Step 2: Save Data.** Use `HomeWidget.saveWidgetData<T>('key', value)` to write data to shared storage.
+- [ ] **Step 3: Trigger Update.** Call `HomeWidget.updateWidget(iOSName: 'YourIOSWidget', androidName: 'YourAndroidWidget')` to notify the OS.
+- [ ] **Step 4: Validate.** Run Flutter build -> review console for missing plugin registrations -> fix.
+
+## iOS Implementation Workflow
+
+If targeting iOS, implement the widget using Xcode and SwiftUI.
+
+- [ ] **Step 1: Create Target.** Open `ios/Runner.xcworkspace` in Xcode. Add a new **Widget Extension** target. Disable "Include Live Activity" and "Include Configuration Intent" unless explicitly required.
+- [ ] **Step 2: Configure App Groups.** Add the **App Groups** capability to *both* the Runner target and the Widget Extension target. Ensure the App Group ID matches the one used in Dart.
+- [ ] **Step 3: Define TimelineEntry.** Create a struct conforming to `TimelineEntry` to hold the data passed from shared storage.
+- [ ] **Step 4: Implement TimelineProvider.** 
+  - In `getSnapshot` and `getTimeline`, instantiate `UserDefaults(suiteName: "<YOUR_APP_GROUP>")`.
+  - Extract values using `userDefaults?.string(forKey: "your_key")`.
+  - Return the populated `TimelineEntry`.
+- [ ] **Step 5: Build UI.** Implement the SwiftUI `View` to display the data from the `TimelineEntry`.
+- [ ] **Step 6: Validate.** Run Xcode build for the Widget Extension -> review provisioning/App Group errors -> fix.
+
+## Android Implementation Workflow
+
+If targeting Android, implement the widget using Android Studio and XML/Kotlin.
+
+- [ ] **Step 1: Create App Widget.** Open the `android` folder in Android Studio. Right-click the app directory -> **New -> Widget -> App Widget**.
+- [ ] **Step 2: Define Layout.** Edit `res/layout/<widget_name>.xml` to define the UI using standard Android XML layouts (e.g., `RelativeLayout`, `TextView`, `ImageView`).
+- [ ] **Step 3: Implement AppWidgetProvider.** 
+  - Open the generated Kotlin class extending `AppWidgetProvider`.
+  - In the `onUpdate` method, retrieve shared data using `HomeWidgetPlugin.getData(context)`.
+  - Extract values using `widgetData.getString("your_key", null)`.
+  - Update the UI using `RemoteViews` and `setTextViewText` or `setImageViewBitmap`.
+  - Call `appWidgetManager.updateAppWidget(appWidgetId, views)`.
+- [ ] **Step 4: Validate.** Run Android build -> review Manifest registration errors -> fix.
+
+## Advanced Techniques
+
+### Rendering Flutter Widgets as Images
+If the UI is too complex to recreate natively (e.g., custom charts), render the Flutter widget to an image and display the image in the native widget.
+
+1. Wrap the target Flutter widget with a `GlobalKey`.
+2. Call `HomeWidget.renderFlutterWidget()`, passing the widget, a filename, and the key.
+3. **iOS:** Read the file path from `UserDefaults` and render using `UIImage(contentsOfFile:)` inside a SwiftUI `Image`.
+4. **Android:** Read the file path from `SharedPreferences`, decode using `BitmapFactory.decodeFile()`, and render using `setImageViewBitmap()`.
+
+### Using Custom Flutter Fonts (iOS Only)
+If utilizing custom fonts defined in Flutter on iOS Home Screen Widgets:
+
+1. Extract the Flutter asset bundle path in Swift.
+2. Register the font using `CTFontManagerRegisterFontsForURL`.
+3. Apply the font in SwiftUI using `Font.custom()`.
+
+## Examples
+
+### Example: Flutter Data Update
+```dart
+import 'package:home_widget/home_widget.dart';
+
+const String appGroupId = 'group.com.example.app';
+const String iOSWidgetName = 'NewsWidgets';
+const String androidWidgetName = 'NewsWidget';
+
+Future<void> updateWidgetData(String title, String description) async {
+  await HomeWidget.setAppGroupId(appGroupId);
+  await HomeWidget.saveWidgetData<String>('headline_title', title);
+  await HomeWidget.saveWidgetData<String>('headline_description', description);
+  await HomeWidget.updateWidget(
+    iOSName: iOSWidgetName,
+    androidName: androidWidgetName,
+  );
+}
+```
+
+### Example: iOS SwiftUI Provider & View
+```swift
+import WidgetKit
+import SwiftUI
+
+struct NewsArticleEntry: TimelineEntry {
+    let date: Date
+    let title: String
+    let description: String
+}
+
+struct Provider: TimelineProvider {
+    func placeholder(in context: Context) -> NewsArticleEntry {
+        NewsArticleEntry(date: Date(), title: "Loading...", description: "Loading...")
+    }
+
+    func getSnapshot(in context: Context, completion: @escaping (NewsArticleEntry) -> ()) {
+        let userDefaults = UserDefaults(suiteName: "group.com.example.app")
+        let title = userDefaults?.string(forKey: "headline_title") ?? "No Title"
+        let description = userDefaults?.string(forKey: "headline_description") ?? "No Description"
+        
+        let entry = NewsArticleEntry(date: Date(), title: title, description: description)
+        completion(entry)
+    }
+
+    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
+        getSnapshot(in: context) { (entry) in
+            let timeline = Timeline(entries: [entry], policy: .atEnd)
+            completion(timeline)
+        }
+    }
+}
+
+struct NewsWidgetsEntryView : View {
+    var entry: Provider.Entry
+
+    var body: some View {
+        VStack(alignment: .leading) {
+            Text(entry.title).font(.headline)
+            Text(entry.description).font(.subheadline)
+        }
+    }
+}
+```
+
+### Example: Android Kotlin Provider
+```kotlin
+package com.example.app.widgets
+
+import android.appwidget.AppWidgetManager
+import android.appwidget.AppWidgetProvider
+import android.content.Context
+import android.widget.RemoteViews
+import es.antonborri.home_widget.HomeWidgetPlugin
+import com.example.app.R
+
+class NewsWidget : AppWidgetProvider() {
+    override fun onUpdate(
+        context: Context,
+        appWidgetManager: AppWidgetManager,
+        appWidgetIds: IntArray,
+    ) {
+        for (appWidgetId in appWidgetIds) {
+            val widgetData = HomeWidgetPlugin.getData(context)
+            val views = RemoteViews(context.packageName, R.layout.news_widget).apply {
+                val title = widgetData.getString("headline_title", "No Title")
+                setTextViewText(R.id.headline_title, title)
+
+                val description = widgetData.getString("headline_description", "No Description")
+                setTextViewText(R.id.headline_description, description)
+            }
+            appWidgetManager.updateAppWidget(appWidgetId, views)
+        }
+    }
+}
+```
+
+<details>
+<summary>Example: iOS Custom Font Registration Helper</summary>
+
+```swift
+// Add this to your SwiftUI View struct
+var bundle: URL {
+    let bundle = Bundle.main
+    if bundle.bundleURL.pathExtension == "appex" {
+        var url = bundle.bundleURL.deletingLastPathComponent().deletingLastPathComponent()
+        url.append(component: "Frameworks/App.framework/flutter_assets")
+        return url
+    }
+    return bundle.bundleURL
+}
+
+init(entry: Provider.Entry) {
+    self.entry = entry
+    CTFontManagerRegisterFontsForURL(
+        bundle.appending(path: "/fonts/YourCustomFont.ttf") as CFURL, 
+        CTFontManagerScope.process, 
+        nil
+    )
+}
+```
+</details>