feat: complete hook-based debug system implementation

- Replace isInDebugMode parameter with extensible hook system
- Add WorkmanagerDebugHandler interface/protocol for Android/iOS
- Implement LoggingDebugHandler and NotificationDebugHandler
- Add WorkmanagerDebug global registry for handler management
- Remove old DebugNotificationHelper and UserDefaultsHelper debug code
- Update documentation with proper Tabs component syntax
- Clean up workmanager/README.md to avoid duplication with docs.page
- Fix all integration tests and update mocks

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ened

CLAUDE.md

@@ -32,4 +32,17 @@
 - **No AI agent progress**: Don't document debugging steps, build fixes, or internal development process
 - **What matters to users**: Breaking changes, new features, bug fixes that affect their code
 - **Example of bad changelog entry**: "Fixed Kotlin null safety issues with androidx.work 2.10.2 type system improvements"
-- **Example of good changelog entry**: "Fixed periodic tasks not respecting frequency changes"
+- **Example of good changelog entry**: "Fixed periodic tasks not respecting frequency changes"
+
+## Documentation Components (docs.page)
+- **Component reference**: https://use.docs.page/ contains the full reference for available components
+- **Tabs component syntax**:
+  ```jsx
+  <Tabs>
+    <TabItem label="Tab Name" value="unique-value">
+      Content here
+    </TabItem>
+  </Tabs>
+  ```
+- Use `<TabItem>` not `<Tab>` - this is a common mistake that causes JavaScript errors
+- Always include both `label` and `value` props on TabItem components

docs/debugging.mdx

@@ -89,7 +89,7 @@ WorkmanagerDebug.setDebugHandler(NotificationDebugHandler())
 Create your own debug handler for custom logging needs:
 
 <Tabs>
-<Tab title="Android">
+  <TabItem label="Android" value="android">
 
 ```kotlin
 class CustomDebugHandler : WorkmanagerDebugHandler {
@@ -105,8 +105,8 @@ class CustomDebugHandler : WorkmanagerDebugHandler {
 WorkmanagerDebug.setDebugHandler(CustomDebugHandler())
 ```
 
-</Tab>
-<Tab title="iOS">
+  </TabItem>
+  <TabItem label="iOS" value="ios">
 
 ```swift
 class CustomDebugHandler: WorkmanagerDebugHandler {
@@ -122,7 +122,7 @@ class CustomDebugHandler: WorkmanagerDebugHandler {
 WorkmanagerDebug.setDebugHandler(CustomDebugHandler())
 ```
 
-</Tab>
+  </TabItem>
 </Tabs>
 
 ## Android Debugging
@@ -350,7 +350,7 @@ Future<bool> isTaskHealthy(String taskName, Duration maxAge) async {
 - [ ] Workmanager initialized in main()
 - [ ] Task names are unique
 - [ ] Platform setup completed ([iOS setup guide](quickstart#ios))
-- [ ] Debug notifications enabled (`isInDebugMode: kDebugMode`)
+- [ ] Debug handler configured (see [Debug Handlers](#debug-handlers))
 
 **Performance & Reliability:**
 - [ ] Task logic optimized for background execution

docs/quickstart.mdx

@@ -145,10 +145,7 @@ void callbackDispatcher() {
 import 'package:flutter/foundation.dart';
 
 void main() {
-  Workmanager().initialize(
-    callbackDispatcher,
-    isInDebugMode: kDebugMode,
-  );
+  Workmanager().initialize(callbackDispatcher);
   
   runApp(MyApp());
 }

example/integration_test/workmanager_integration_test.dart

@@ -76,7 +76,7 @@ void main() {
 
     testWidgets('initialize should succeed on all platforms',
         (WidgetTester tester) async {
-      await workmanager.initialize(callbackDispatcher, isInDebugMode: true);
+      await workmanager.initialize(callbackDispatcher);
       // No exception means success
     });
 

workmanager/README.md

@@ -35,14 +35,12 @@ class MockWorkmanager extends _i1.Mock implements _i2.Workmanager {
 
   @override
   _i3.Future<void> initialize(
-    Function? callbackDispatcher, {
-    bool? isInDebugMode = false,
-  }) =>
+    Function? callbackDispatcher,
+  ) =>
       (super.noSuchMethod(
         Invocation.method(
           #initialize,
           [callbackDispatcher],
-          {#isInDebugMode: isInDebugMode},
         ),
         returnValue: _i3.Future<void>.value(),
         returnValueForMissingStub: _i3.Future<void>.value(),

workmanager/test/workmanager_test.mocks.dart

@@ -50,7 +50,6 @@ class BackgroundWorker(
     private val dartTask
         get() = workerParams.inputData.getString(DART_TASK_KEY)!!
 
-
     private val randomThreadIdentifier = Random().nextInt()
     private var engine: FlutterEngine? = null
 
@@ -96,8 +95,8 @@ class BackgroundWorker(
                     inputData = payload,
                     startTime = startTime,
                     callbackHandle = callbackHandle,
-                    callbackInfo = callbackInfo?.callbackName
-                )
+                    callbackInfo = callbackInfo?.callbackName,
+                ),
             )
 
             engine?.let { engine ->
@@ -134,13 +133,13 @@ class BackgroundWorker(
             TaskDebugInfo(
                 taskName = dartTask,
                 inputData = payload,
-                startTime = startTime
+                startTime = startTime,
             ),
             TaskResult(
                 success = result is Result.Success,
                 duration = fetchDuration,
-                error = if (result is Result.Failure) "Task failed" else null
-            )
+                error = if (result is Result.Failure) "Task failed" else null,
+            ),
         )
 
         // No result indicates we were signalled to stop by WorkManager.  The result is already

workmanager_android/android/src/main/kotlin/dev/fluttercommunity/workmanager/BackgroundWorker.kt

@@ -12,15 +12,22 @@ class LoggingDebugHandler : WorkmanagerDebugHandler {
         private const val TAG = "WorkmanagerDebug"
     }
 
-    override fun onTaskStarting(context: Context, taskInfo: TaskDebugInfo) {
+    override fun onTaskStarting(
+        context: Context,
+        taskInfo: TaskDebugInfo,
+    ) {
         Log.d(TAG, "Task starting: ${taskInfo.taskName}, callbackHandle: ${taskInfo.callbackHandle}")
     }
 
-    override fun onTaskCompleted(context: Context, taskInfo: TaskDebugInfo, result: TaskResult) {
+    override fun onTaskCompleted(
+        context: Context,
+        taskInfo: TaskDebugInfo,
+        result: TaskResult,
+    ) {
         val status = if (result.success) "SUCCESS" else "FAILURE"
         Log.d(TAG, "Task completed: ${taskInfo.taskName}, result: $status, duration: ${result.duration}ms")
         if (result.error != null) {
             Log.e(TAG, "Task error: ${result.error}")
         }
     }
-}
+}

workmanager_android/android/src/main/kotlin/dev/fluttercommunity/workmanager/LoggingDebugHandler.kt

@@ -5,7 +5,6 @@ import android.app.NotificationManager
 import android.content.Context
 import android.os.Build
 import androidx.core.app.NotificationCompat
-import androidx.work.ListenableWorker
 import java.text.DateFormat
 import java.util.Date
 import java.util.concurrent.TimeUnit.MILLISECONDS
@@ -14,7 +13,7 @@ import kotlin.random.Random
 /**
  * A debug handler that shows notifications for task events.
  * Use this to see task execution as notifications on the device.
- * 
+ *
  * Note: You need to ensure your app has notification permissions.
  */
 class NotificationDebugHandler : WorkmanagerDebugHandler {
@@ -30,7 +29,10 @@ class NotificationDebugHandler : WorkmanagerDebugHandler {
     private val failureEmoji = "🔥"
     private val currentTime get() = debugDateFormatter.format(Date())
 
-    override fun onTaskStarting(context: Context, taskInfo: TaskDebugInfo) {
+    override fun onTaskStarting(
+        context: Context,
+        taskInfo: TaskDebugInfo,
+    ) {
         val notificationId = Random.nextInt()
         postNotification(
             context,
@@ -40,16 +42,20 @@ class NotificationDebugHandler : WorkmanagerDebugHandler {
             • Task Starting: ${taskInfo.taskName}
             • Input Data: ${taskInfo.inputData ?: "none"}
             • Callback Handle: ${taskInfo.callbackHandle}
-            """.trimIndent()
+            """.trimIndent(),
         )
     }
 
-    override fun onTaskCompleted(context: Context, taskInfo: TaskDebugInfo, result: TaskResult) {
+    override fun onTaskCompleted(
+        context: Context,
+        taskInfo: TaskDebugInfo,
+        result: TaskResult,
+    ) {
         val notificationId = Random.nextInt()
         val emoji = if (result.success) successEmoji else failureEmoji
         val status = if (result.success) "SUCCESS" else "FAILURE"
         val duration = MILLISECONDS.toSeconds(result.duration)
-        
+
         postNotification(
             context,
             notificationId,
@@ -60,7 +66,7 @@ class NotificationDebugHandler : WorkmanagerDebugHandler {
             • Input Data: ${taskInfo.inputData ?: "none"}
             • Duration: ${duration}s
             ${if (result.error != null) "• Error: ${result.error}" else ""}
-            """.trimIndent()
+            """.trimIndent(),
         )
     }
 
@@ -71,33 +77,34 @@ class NotificationDebugHandler : WorkmanagerDebugHandler {
         contentText: String,
     ) {
         val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
-        
+
         createNotificationChannel(notificationManager)
-        
-        val notification = NotificationCompat
-            .Builder(context, DEBUG_CHANNEL_ID)
-            .setContentTitle(title)
-            .setContentText(contentText)
-            .setStyle(
-                NotificationCompat
-                    .BigTextStyle()
-                    .bigText(contentText)
-            )
-            .setSmallIcon(android.R.drawable.stat_notify_sync)
-            .setPriority(NotificationCompat.PRIORITY_LOW)
-            .build()
-            
+
+        val notification =
+            NotificationCompat
+                .Builder(context, DEBUG_CHANNEL_ID)
+                .setContentTitle(title)
+                .setContentText(contentText)
+                .setStyle(
+                    NotificationCompat
+                        .BigTextStyle()
+                        .bigText(contentText),
+                ).setSmallIcon(android.R.drawable.stat_notify_sync)
+                .setPriority(NotificationCompat.PRIORITY_LOW)
+                .build()
+
         notificationManager.notify(notificationId, notification)
     }
 
     private fun createNotificationChannel(notificationManager: NotificationManager) {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            val channel = NotificationChannel(
-                DEBUG_CHANNEL_ID,
-                DEBUG_CHANNEL_NAME,
-                NotificationManager.IMPORTANCE_LOW
-            )
+            val channel =
+                NotificationChannel(
+                    DEBUG_CHANNEL_ID,
+                    DEBUG_CHANNEL_NAME,
+                    NotificationManager.IMPORTANCE_LOW,
+                )
             notificationManager.createNotificationChannel(channel)
         }
     }
-}
+}

workmanager_android/android/src/main/kotlin/dev/fluttercommunity/workmanager/NotificationDebugHandler.kt

@@ -99,9 +99,7 @@ class WorkManagerWrapper(
 ) {
     private val workManager = WorkManager.getInstance(context)
 
-    fun enqueueOneOffTask(
-        request: dev.fluttercommunity.workmanager.pigeon.OneOffTaskRequest,
-    ) {
+    fun enqueueOneOffTask(request: dev.fluttercommunity.workmanager.pigeon.OneOffTaskRequest) {
         try {
             val oneOffTaskRequest =
                 OneTimeWorkRequest
@@ -141,9 +139,7 @@ class WorkManagerWrapper(
         }
     }
 
-    fun enqueuePeriodicTask(
-        request: dev.fluttercommunity.workmanager.pigeon.PeriodicTaskRequest,
-    ) {
+    fun enqueuePeriodicTask(request: dev.fluttercommunity.workmanager.pigeon.PeriodicTaskRequest) {
         val periodicTaskRequest =
             PeriodicWorkRequest
                 .Builder(