Add Injectable section and handler lifecycle warnings to docs

- Add "Want Less Boilerplate? Try Injectable!" section to get_it getting_started
- Move "Naming Your GetIt Instance" section earlier in the doc flow
- Add handler lifecycle warning to watch_it observing_commands, handlers, and debugging docs
- Create handler_lifecycle_example.dart code sample
- Apply all changes to both English and Spanish documentation

Author: escamoteur

code_samples/lib/watch_it/handler_lifecycle_example.dart

@@ -0,0 +1,108 @@
+// ignore_for_file: unused_local_variable
+import 'package:flutter/material.dart';
+import 'package:watch_it/watch_it.dart';
+import '_shared/stubs.dart';
+
+// #region bad
+// ❌ BAD: Handler inside widget that gets destroyed on parent rebuild
+class ParentWidget extends StatefulWidget {
+  const ParentWidget({super.key});
+
+  @override
+  State<ParentWidget> createState() => _ParentWidgetState();
+}
+
+class _ParentWidgetState extends State<ParentWidget> {
+  bool _isHovered = false;
+
+  @override
+  Widget build(BuildContext context) {
+    return MouseRegion(
+      onEnter: (_) => setState(() => _isHovered = true),
+      onExit: (_) => setState(() => _isHovered = false),
+      child: Container(
+        color: _isHovered ? Colors.blue.shade100 : Colors.white,
+        child: SaveButtonWithHandler(), // ❌ Destroyed on every hover!
+      ),
+    );
+  }
+}
+
+class SaveButtonWithHandler extends WatchingWidget {
+  @override
+  Widget build(BuildContext context) {
+    // ❌ Handler is registered here - if parent rebuilds,
+    // this widget is destroyed and handler is lost!
+    registerHandler(
+      select: (TodoManager m) => m.createTodoCommand.results,
+      handler: (context, result, cancel) {
+        if (result.hasData) {
+          Navigator.of(context).pop(); // May never execute!
+        }
+      },
+    );
+
+    return ElevatedButton(
+      onPressed: () => di<TodoManager>().createTodoCommand(
+        CreateTodoParams(title: 'New', description: 'Task'),
+      ),
+      child: const Text('Save'),
+    );
+  }
+}
+// #endregion bad
+
+// #region good
+// ✅ GOOD: Handler in stable parent widget
+class StableParentWidget extends WatchingStatefulWidget {
+  const StableParentWidget({super.key});
+
+  @override
+  State<StableParentWidget> createState() => _StableParentWidgetState();
+}
+
+class _StableParentWidgetState extends State<StableParentWidget> {
+  bool _isHovered = false;
+
+  @override
+  Widget build(BuildContext context) {
+    // ✅ Handler registered in parent - survives child rebuilds
+    registerHandler(
+      select: (TodoManager m) => m.createTodoCommand.results,
+      handler: (context, result, cancel) {
+        if (result.hasData) {
+          Navigator.of(context).pop(); // Always executes!
+        }
+      },
+    );
+
+    return MouseRegion(
+      onEnter: (_) => setState(() => _isHovered = true),
+      onExit: (_) => setState(() => _isHovered = false),
+      child: Container(
+        color: _isHovered ? Colors.blue.shade100 : Colors.white,
+        child: const SaveButtonOnly(), // Child can rebuild safely
+      ),
+    );
+  }
+}
+
+class SaveButtonOnly extends StatelessWidget {
+  const SaveButtonOnly({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    // Just the button - no handler here
+    return ElevatedButton(
+      onPressed: () => di<TodoManager>().createTodoCommand(
+        CreateTodoParams(title: 'New', description: 'Task'),
+      ),
+      child: const Text('Save'),
+    );
+  }
+}
+// #endregion good
+
+void main() {
+  setupDependencyInjection();
+}

docs/documentation/get_it/getting_started.md

@@ -65,6 +65,31 @@ dependencies:
 
 <strong>That's it!</strong> No Provider wrappers, no InheritedWidgets, no BuildContext needed.
 
+---
+
+## Naming Your GetIt Instance
+
+The standard pattern is to create a global variable:
+
+
+<<< @/../code_samples/lib/get_it/code_sample_866f5818.dart#example
+
+<strong>Alternative names you might see:</strong>
+- `final sl = GetIt.instance;` (service locator)
+- `final locator = GetIt.instance;`
+- `final di = GetIt.instance;` (dependency injection)
+- `GetIt.instance` or `GetIt.I` (use directly without variable)
+
+<strong>Recommendation:</strong> Use `getIt` or `di` - both are clear and widely recognized in the Flutter community.
+
+::: tip Using with `watch_it`
+If you're using the [`watch_it`](https://pub.dev/packages/watch_it) package, you already have a global `di` instance available - no need to create your own. Just import `watch_it` and use `di` directly.
+:::
+
+::: tip Cross-Package Usage
+`GetIt.instance` returns the same singleton across all packages in your project. Create your global variable once in your main app and import it elsewhere.
+:::
+
 ::: warning Isolate Safety
 GetIt instances are not thread-safe and cannot be shared across isolates. Each isolate will get its own GetIt instance. This means objects registered in one isolate can't be accessed from another isolate.
 :::
@@ -73,7 +98,7 @@ GetIt instances are not thread-safe and cannot be shared across isolates. Each i
 
 ## When to Use Which Registration Type
 
-get_it offers three main registration types:
+`get_it` offers three main registration types:
 
 | Registration Type | When Created | Lifetime | Use When |
 |-------------------|--------------|----------|----------|
@@ -161,6 +186,93 @@ See [Where should I put my get_it setup code?](/documentation/get_it/faq#where-s
 
 ---
 
+## Want Less Boilerplate? Try Injectable!
+
+**Injectable** is a code generation package that automates your `get_it` setup. If you find yourself writing lots of registration code, injectable might be for you.
+
+### How It Works
+
+Instead of manually registering each service:
+
+```dart
+void configureDependencies() {
+  getIt.registerLazySingleton<ApiClient>(() => ApiClient());
+  getIt.registerLazySingleton<Database>(() => Database());
+  getIt.registerLazySingleton<AuthService>(() => AuthService(getIt(), getIt()));
+}
+```
+
+Just annotate your classes:
+
+```dart
+@lazySingleton
+class ApiClient { }
+
+@lazySingleton
+class Database { }
+
+@lazySingleton
+class AuthService {
+  AuthService(ApiClient api, Database db); // Auto-injected!
+}
+```
+
+Run build_runner and injectable generates all the registration code for you.
+
+### Quick Setup
+
+1. Add dependencies:
+```yaml
+dependencies:
+  get_it: ^8.3.0
+  injectable: ^2.3.2
+
+dev_dependencies:
+  injectable_generator: ^2.6.1
+  build_runner: ^2.4.0
+```
+
+2. Annotate your main configuration:
+```dart
+@InjectableInit()
+void configureDependencies() => getIt.init();
+```
+
+3. Run code generation:
+```bash
+flutter pub run build_runner build
+```
+
+### When to Use Injectable
+
+**Use injectable if:**
+- You have many services to register
+- You want automatic dependency resolution
+- You prefer annotations over manual setup
+- You're comfortable with code generation
+
+**Stick with plain `get_it` if:**
+- You prefer explicit, visible registration
+- You want to avoid build_runner in your workflow
+- You have a small number of services
+- You want full control over registration order and logic
+
+Both approaches use the same `GetIt` instance and have identical runtime performance!
+
+### Learn More
+
+Check out [injectable on pub.dev](https://pub.dev/packages/injectable) for full documentation and advanced features like:
+- Environment-specific registrations (dev/prod)
+- Pre-resolved dependencies
+- Module registration
+- Custom annotations
+
+::: tip Injectable Support
+Injectable is a separate package maintained by a different author. If you encounter issues with injectable, please file them on the [injectable GitHub repository](https://github.com/Milad-Akarie/injectable/issues).
+:::
+
+---
+
 ## Next Steps
 
 Now that you understand the basics, explore these topics:
@@ -228,27 +340,3 @@ get_it implements the Service Locator pattern - it decouples interface (abstract
 For deeper understanding, read Martin Fowler's classic article: [Inversion of Control Containers and the Dependency Injection pattern](https://martinfowler.com/articles/injection.html)
 
 </details>
-
----
-
-## Naming Your GetIt Instance
-
-The standard pattern is to create a global variable:
-
-
-<<< @/../code_samples/lib/get_it/code_sample_866f5818.dart#example
-
-<strong>Alternative names you might see:</strong>
-- `final sl = GetIt.instance;` (service locator)
-- `final locator = GetIt.instance;`
-- `final di = GetIt.instance;` (dependency injection)
-- `GetIt.instance` or `GetIt.I` (use directly without variable)
-
-<strong>Recommendation:</strong> Use `getIt` or `di` - both are clear and widely recognized in the Flutter community.
-
-::: tip Using with `watch_it`
-If you're using the [`watch_it`](https://pub.dev/packages/watch_it) package, you already have a global `di` instance available - no need to create your own. Just import `watch_it` and use `di` directly.
-:::
-
-::: tip Cross-Package Usage
-`GetIt.instance` returns the same singleton across all packages in your project. Create your global variable once in your main app and import it elsewhere.

docs/documentation/watch_it/debugging_tracing.md

@@ -136,6 +136,18 @@ See [listen_it Collections](/documentation/listen_it/collections/introduction.md
 
 <<< @/../code_samples/lib/watch_it/debugging_registerhandler.dart#handler_registered_before_return_good
 
+#### 2. Widget destroyed during command execution
+
+If the widget containing the handler is destroyed and rebuilt while the command is running, the handler will be re-registered and may miss state changes.
+
+**Example:** A button inside a widget that rebuilds on hover:
+
+<<< @/../code_samples/lib/watch_it/handler_lifecycle_example.dart#bad
+
+**Solution:** Move the handler to a stable parent widget:
+
+<<< @/../code_samples/lib/watch_it/handler_lifecycle_example.dart#good
+
 ## Debugging Techniques
 
 ### Enable `watch_it` Tracing

docs/documentation/watch_it/handlers.md

@@ -202,6 +202,16 @@ When `true`, the handler is called on the first build with the current value of
 
 <<< @/../code_samples/lib/watch_it/handler_patterns.dart#mistake_good
 
+### ❌ Handler in widget that gets destroyed
+
+If the widget containing the handler is destroyed during command execution, the handler is lost and misses state changes:
+
+<<< @/../code_samples/lib/watch_it/handler_lifecycle_example.dart#bad
+
+### ✅ Move handler to stable parent widget
+
+<<< @/../code_samples/lib/watch_it/handler_lifecycle_example.dart#good
+
 ## What's Next?
 
 Now you know when to rebuild (watch) vs when to run side effects (handlers). Next:

docs/documentation/watch_it/observing_commands.md

@@ -67,6 +67,16 @@ While `watch` is for rebuilding UI, use `registerHandler` for side effects like
 - Log error to crash reporting
 - Retry logic
 
+::: warning Handler Lifecycle
+If you rely on your handler reacting to all state changes, ensure the widget where the handler is registered isn't destroyed and rebuilt during command execution.
+
+**Common pitfall:** A button that registers a handler and calls a command, but the parent widget rebuilds on an `onHover` event - this destroys and recreates the button (and its handler), causing missed state changes.
+
+**Solution:** Move the handler to a parent widget that will live for the entire duration of the command execution.
+
+**Note:** This doesn't apply to `watch` functions - their results are only used in the same build function, so widget rebuilds don't cause issues.
+:::
+
 ## Watching Command Results
 
 The `results` property provides a `CommandResult` object containing all command state in one place: