[green] integrate startup recovery and offline draft controls

Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>

Author: yyods

app/lib/app/app.dart

@@ -15,17 +15,22 @@ library;
 import 'package:flutter/material.dart';
 
 import 'package:pyble/localization/localization.dart';
+import 'package:pyble/editor/recovery_gate.dart';
 import 'package:pyble/theme/theme.dart';
 
 import 'shell.dart';
 
+/// Navigator used by explicit user confirmations, never by local recovery itself.
+final GlobalKey<NavigatorState> appNavigatorKey = GlobalKey<NavigatorState>();
+
 /// The PyBLE root widget: a `MaterialApp` hosting the responsive shell.
 class PybleApp extends StatelessWidget {
   const PybleApp({super.key});
 
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
+      navigatorKey: appNavigatorKey,
       // The app wordmark is a brand proper noun, sourced from the ARB (rendered
       // verbatim) so the OS task-switcher title follows the localization path.
       onGenerateTitle: (BuildContext context) =>
@@ -40,7 +45,7 @@ class PybleApp extends StatelessWidget {
       highContrastDarkTheme: PybleTheme.highContrastDark,
       themeMode: ThemeMode.system,
       debugShowCheckedModeBanner: false,
-      home: const PybleShell(),
+      home: const RecoveryGate(child: PybleShell()),
     );
   }
 }

app/lib/app/shell.dart

@@ -19,6 +19,9 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import 'package:pyble/console/console.dart';
 import 'package:pyble/editor/editor.dart';
+import 'package:pyble/editor/board_target_guard.dart';
+import 'package:pyble/editor/draft_recovery.dart';
+import 'package:pyble/editor/recovery_gate.dart';
 import 'package:pyble/localization/localization.dart';
 import 'package:pyble/pble/pble.dart';
 import 'package:pyble/theme/theme.dart';
@@ -149,18 +152,49 @@ class PybleShell extends ConsumerWidget {
 /// Pin-reference pane, or console strip, none of which means anything without a
 /// board. The toolbar's connection action is an inert Connect slot here (the
 /// live scan/connect flow is the surface below); Run/Stop are disabled.
-class _DisconnectedShell extends StatelessWidget {
+class _DisconnectedShell extends ConsumerStatefulWidget {
   const _DisconnectedShell();
 
+  @override
+  ConsumerState<_DisconnectedShell> createState() => _DisconnectedShellState();
+}
+
+class _DisconnectedShellState extends ConsumerState<_DisconnectedShell> {
+  bool _showRecovery = true;
+
   @override
   Widget build(BuildContext context) {
-    return const Scaffold(
+    final DraftRecoveryState recovery = ref.watch(draftRecoveryProvider);
+    final bool recovered = ref.watch(editorRecoveredDraftProvider);
+    final EditorDocument document = ref.watch(editorDocumentProvider);
+    final bool previewAvailable =
+        recovery.enabled && (recovered || document.content.isNotEmpty);
+    final AppLocalizations l10n = AppLocalizations.of(context);
+    return Scaffold(
       body: SafeArea(
         child: Column(
           children: <Widget>[
-            _Toolbar(),
-            Divider(height: 1),
-            Expanded(child: ConnectPage()),
+            const _Toolbar(),
+            const Divider(height: 1),
+            if (previewAvailable) ...<Widget>[
+              TextButton.icon(
+                onPressed: () => setState(() => _showRecovery = !_showRecovery),
+                icon: Icon(
+                  _showRecovery ? Icons.bluetooth : Icons.description_outlined,
+                ),
+                label: Text(
+                  _showRecovery ? l10n.recoveryConnect : l10n.recoveryOpen,
+                ),
+              ),
+              const RecoveryStatusBar(),
+            ],
+            Expanded(
+              child: previewAvailable && _showRecovery
+                  ? CurrentDraftPreview(
+                      onContinue: () => setState(() => _showRecovery = false),
+                    )
+                  : const ConnectPage(),
+            ),
           ],
         ),
       ),
@@ -509,13 +543,15 @@ class _Toolbar extends ConsumerWidget {
     } on EBusy {
       // EBusy is never swallowed: tell the user a program is already running.
       messenger.showSnackBar(SnackBar(content: Text(l10n.runBusyMessage)));
+    } on BoardActionCancelled {
+      return;
     } catch (e) {
       // NOTHING else was surfaced before: every other failure (a typed ERange
       // for an over-long buffer, a link timeout, a torn-down connection)
       // became an unhandled async error, so pressing Run did LITERALLY nothing
       // visible. FR-RUN-3 requires the failure to be honest.
       messenger.showSnackBar(
-        SnackBar(content: Text(l10n.runFailed(_reasonOf(e)))),
+        SnackBar(content: Text(l10n.runFailed(_reasonOf(e, l10n)))),
       );
     }
   }
@@ -531,15 +567,19 @@ class _Toolbar extends ConsumerWidget {
       await action();
     } catch (e) {
       messenger.showSnackBar(
-        SnackBar(content: Text(l10n.runFailed(_reasonOf(e)))),
+        SnackBar(content: Text(l10n.runFailed(_reasonOf(e, l10n)))),
       );
     }
   }
 
   /// The technical reason token for [e]. A typed PBLE/1 §8 status name is a
   /// technical identifier rendered verbatim (FR-I18N-4).
-  static String _reasonOf(Object e) =>
-      e is PbleException ? e.runtimeType.toString() : e.toString();
+  static String _reasonOf(Object e, AppLocalizations l10n) => switch (e) {
+    ProgramSourceSessionChanged(:final sourcePath) =>
+      l10n.runSourceSessionChanged(sourcePath),
+    PbleException() => e.runtimeType.toString(),
+    _ => e.toString(),
+  };
 
   static void _openAbout(BuildContext context) {
     Navigator.of(context).push<void>(

app/lib/editor/editor_view.dart

@@ -22,6 +22,10 @@ import 'package:pyble/pble/pble.dart';
 import 'package:pyble/theme/theme.dart';
 
 import 'editor_document.dart';
+import 'board_target_guard.dart';
+import 'draft_recovery.dart';
+import 'recovery_gate.dart';
+import 'recovery_panel.dart';
 import 'editor_display_settings.dart';
 import 'editor_surface.dart';
 import 'editor_surface_factory.dart';
@@ -103,6 +107,7 @@ class _EditorViewState extends ConsumerState<EditorView> {
         // present, and it fixes on tap — the buffer is never rewritten behind
         // the user's back.
         const _SmartPunctuationBanner(),
+        const RecoveryStatusBar(),
         // The editable code well — a recessed monospace surface (§1.4).
         Expanded(
           child: surfaceBuilder(
@@ -267,6 +272,8 @@ class _EditorHeader extends ConsumerWidget {
     try {
       final String path = await ref.read(saveControllerProvider).save();
       messenger.showSnackBar(SnackBar(content: Text(l10n.editorSaved(path))));
+    } on BoardActionCancelled {
+      return;
     } on PbleException catch (e) {
       // The typed §8 status name (EBusy / ENoSpc / ECrc …) is a PBLE/1
       // technical identifier: rendered verbatim, never localized (FR-I18N-4).
@@ -291,27 +298,77 @@ class _EditorHeader extends ConsumerWidget {
   /// no way to get it back (the document is volatile by design).
   Future<void> _newDocument(BuildContext context, WidgetRef ref) async {
     final AppLocalizations l10n = AppLocalizations.of(context);
-    if (ref.read(editorDocumentProvider).dirty) {
-      final bool? discard = await showDialog<bool>(
-        context: context,
-        builder: (BuildContext ctx) => AlertDialog(
-          title: Text(l10n.editorDiscardTitle),
-          content: Text(l10n.editorDiscardDetail),
-          actions: <Widget>[
-            TextButton(
-              onPressed: () => Navigator.of(ctx).pop(false),
-              child: Text(l10n.commonCancel),
-            ),
-            TextButton(
-              onPressed: () => Navigator.of(ctx).pop(true),
-              child: Text(l10n.editorDiscardConfirm),
-            ),
-          ],
-        ),
-      );
-      if (discard != true) return;
+    final int epoch = ref.read(editorDocumentEpochProvider);
+    final EditorDocument document = ref.read(editorDocumentProvider);
+    final DraftRecoveryState recovery = ref.read(draftRecoveryProvider);
+    final bool meaningful =
+        document.content.isNotEmpty ||
+        document.name != kDefaultDocumentName ||
+        document.boardPath != null;
+    final bool needsChoice =
+        document.dirty ||
+        (recovery.enabled &&
+            meaningful &&
+            recovery.status != DraftRecoveryStatus.saved);
+    if (needsChoice) {
+      if (recovery.enabled) {
+        if (!await confirmRecoveryReplacement(context)) return;
+      } else {
+        final bool? discard = await showDialog<bool>(
+          context: context,
+          builder: (BuildContext ctx) => AlertDialog(
+            scrollable: true,
+            title: Text(l10n.editorDiscardTitle),
+            content: Text(l10n.editorDiscardDetail),
+            actions: <Widget>[
+              TextButton(
+                onPressed: () => Navigator.of(ctx).pop(false),
+                child: Text(l10n.commonCancel),
+              ),
+              TextButton(
+                onPressed: () => Navigator.of(ctx).pop(true),
+                child: Text(l10n.editorDiscardConfirm),
+              ),
+            ],
+          ),
+        );
+        if (discard != true) return;
+      }
+    }
+    if (!context.mounted) return;
+    if (ref.read(editorDocumentEpochProvider) != epoch) {
+      ScaffoldMessenger.of(
+        context,
+      ).showSnackBar(SnackBar(content: Text(l10n.recoveryChanged)));
+      return;
+    }
+    if (!recovery.enabled) {
+      ref.read(editorDocumentProvider.notifier).newDocument();
+      return;
+    }
+    final bool replaced = await ref
+        .read(draftRecoveryProvider.notifier)
+        .replaceDocument(const EditorDocument.untitled(), expectedEpoch: epoch);
+    if (!replaced && context.mounted) {
+      if (ref.read(editorDocumentEpochProvider) != epoch) {
+        ScaffoldMessenger.of(
+          context,
+        ).showSnackBar(SnackBar(content: Text(l10n.recoveryChanged)));
+        return;
+      }
+      if (!await confirmVolatileReplacement(context)) return;
+      if (!context.mounted || ref.read(editorDocumentEpochProvider) != epoch) {
+        return;
+      }
+      ref.read(draftRecoveryProvider.notifier).continueWithoutRecovery();
+      await ref
+          .read(draftRecoveryProvider.notifier)
+          .replaceDocument(
+            const EditorDocument.untitled(),
+            expectedEpoch: epoch,
+            allowVolatile: true,
+          );
     }
-    ref.read(editorDocumentProvider.notifier).newDocument();
   }
 }