only-bible-app v3.7.2+24

# Backup Export/Import Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Let users export their entire `AppState` (highlights, highlight history, reading position, display settings) to a JSON file via a native save dialog, and import a previously-exported file back (replacing current state), both from the settings bottom sheet.

**Architecture:** Add `file_picker` as the only new dependency. Extract the JSON-shape logic (filename, encode, decode+validate) into pure, unit-testable functions in a new `lib/store/actions_backup.dart`, then wrap them in two thin `ReduxAction<AppState>` classes (`ExportAppStateAction`, `ImportAppStateAction`) that call `file_picker` and the existing `lib/dialog.dart` helpers for user feedback. Wire two new rows into `lib/widgets/settings_sheet.dart`.

**Tech Stack:** Flutter/Dart, `async_redux` (`ReduxAction<AppState>`), `file_picker` (new), `dart:convert`, `dart:io`.

## Global Constraints

- Export/import operates on the **entire** `AppState` — highlights, `highlightHistory`, `savedBook`/`savedChapter`, `darkMode`, `fontSize`, `fontWeight`, `engTitles` — never a subset.
- Import **replaces** state wholesale after an explicit user confirmation; it never merges with existing state.
- The only new dependency is `file_picker`, added via `flutter pub add file_picker` (do not hand-write a version number into `pubspec.yaml`; let pub resolve one compatible with `sdk: '>=3.0.6 <4.0.0'`, `pubspec.yaml:7`).
- New actions follow the existing convention in `lib/store/actions_navigation.dart`/`lib/store/actions_state.dart`: `ReduxAction<AppState>` with a `BuildContext buildContext` constructor field when the action shows dialogs, `Future<AppState?> reduce() async`, and `showError`/`showAlert` from `lib/dialog.dart` for feedback. Always guard post-`await` `BuildContext` use with `buildContext.mounted`, matching `TogglePlayAction` (`lib/store/actions_state.dart:101`).
- Match the single existing project convention of *not* unit-testing actions that call into native plugin channels (see the comment at `test/app_logic_test.dart:262-270` explaining why `NextChapterAction`/`PreviousChapterAction`/`GoToChapterAction` aren't dispatched directly in tests) — apply the same reasoning to `file_picker` calls: test the pure logic they wrap, verify the actions themselves by running the app.
- Adding new UI to `SettingsSheet` will change its golden screenshot (`test/screenshot_test.dart:199-211`); the golden must be regenerated as part of this work, not left failing.

---

### Task 1: Add the `file_picker` dependency

**Files:**
- Modify: `pubspec.yaml`

**Interfaces:**
- Produces: `file_picker` package available for import as `package:file_picker/file_picker.dart` in later tasks.

- [ ] **Step 1: Add the dependency**

Run:
```bash
flutter pub add file_picker
```

- [ ] **Step 2: Verify it resolved and the project still analyzes cleanly**

Run: `flutter pub get && flutter analyze`
Expected: both commands exit 0; `pubspec.yaml` now has a `file_picker: ^<version>` line under `dependencies`.

- [ ] **Step 3: Commit**

```bash
git add pubspec.yaml pubspec.lock
git commit -m "Add file_picker dependency for backup export/import"
```

---

### Task 2: Backup JSON helpers (pure logic)

**Files:**
- Create: `lib/store/actions_backup.dart`
- Test: `test/actions_backup_test.dart`

**Interfaces:**
- Consumes: `AppState` (`lib/store/app_state.dart:40`, with `toJson()`/`fromJson()`), `Bible` (`lib/gen/bible.gen.dart`), `loadBible(String name) => Future<Bible>` (`lib/utils.dart:175`).
- Produces (used by Task 4/5):
  - `String buildBackupFileName([DateTime? now])`
  - `String buildBackupJson(AppState state)`
  - `class BackupParseException implements Exception { final String message; }`
  - `Future<AppState> parseBackupState(String contents, {Future<Bible> Function(String) loadBibleFn = loadBible})`

- [ ] **Step 1: Write the failing tests**

Create `test/actions_backup_test.dart`:

```dart
import "dart:convert";

import "package:flutter_test/flutter_test.dart";
import "package:only_bible_app/store/actions_backup.dart";
import "package:only_bible_app/store/app_state.dart";

import "app_logic_test.dart" show buildTestBible;

void main() {
  group("buildBackupFileName", () {
    test("formats a zero-padded date", () {
      expect(
        buildBackupFileName(DateTime.utc(2026, 3, 5)),
        "only_bible_app_backup_2026-03-05.json",
      );
    });
  });

  group("buildBackupJson / parseBackupState", () {
    test("round-trips highlights and settings through export and import", () async {
      final bible = buildTestBible();
      final state = AppState(
        bible: bible,
        darkMode: true,
        fontSize: 22,
        highlights: {"0:0:0": 2},
        highlightHistory: [
          HighlightHistoryEntry(book: 0, chapter: 0, verseIndex: 0, colorIndex: 2, timestamp: DateTime.utc(2026, 1, 1)),
        ],
      );

      final jsonString = buildBackupJson(state);
      final restored = await parseBackupState(jsonString, loadBibleFn: (_) async => bible);

      expect(restored.darkMode, true);
      expect(restored.fontSize, 22);
      expect(restored.highlights["0:0:0"], 2);
      expect(restored.highlightHistory.single.colorIndex, 2);
    });

    test("rejects malformed JSON", () async {
      expect(
        () => parseBackupState("not json", loadBibleFn: (_) async => buildTestBible()),
        throwsA(isA<BackupParseException>()),
      );
    });

    test("rejects valid JSON that isn't an object", () async {
      expect(
        () => parseBackupState(jsonEncode([1, 2, 3]), loadBibleFn: (_) async => buildTestBible()),
        throwsA(isA<BackupParseException>()),
      );
    });

    test("rejects a bibleName the app can't load", () async {
      expect(
        () => parseBackupState(
          jsonEncode({"bibleName": "does_not_exist"}),
          loadBibleFn: (_) async => throw Exception("no such asset"),
        ),
        throwsA(isA<BackupParseException>()),
      );
    });
  });
}
```

- [ ] **Step 2: Run the tests to verify they fail**

Run: `flutter test test/actions_backup_test.dart`
Expected: FAIL — `lib/store/actions_backup.dart` doesn't exist yet (import error).

- [ ] **Step 3: Implement the helpers**

Create `lib/store/actions_backup.dart`:

```dart
import "dart:convert";

import "package:only_bible_app/gen/bible.gen.dart";
import "package:only_bible_app/store/app_state.dart";
import "package:only_bible_app/utils.dart";

String buildBackupFileName([DateTime? now]) {
  final n = now ?? DateTime.now();
  final y = n.year.toString().padLeft(4, "0");
  final m = n.month.toString().padLeft(2, "0");
  final d = n.day.toString().padLeft(2, "0");
  return "only_bible_app_backup_$y-$m-$d.json";
}

String buildBackupJson(AppState state) {
  return const JsonEncoder.withIndent("  ").convert(state.toJson());
}

class BackupParseException implements Exception {
  final String message;

  const BackupParseException(this.message);

  @override
  String toString() => message;
}

Future<AppState> parseBackupState(
  String contents, {
  Future<Bible> Function(String) loadBibleFn = loadBible,
}) async {
  final Map<String, dynamic> json;
  try {
    final decoded = jsonDecode(contents);
    if (decoded is! Map<String, dynamic>) {
      throw const FormatException("backup is not a JSON object");
    }
    json = decoded;
  } catch (_) {
    throw const BackupParseException("That file isn't a valid backup");
  }

  final bibleName = json["bibleName"] as String? ?? "en_kjv";
  final Bible bible;
  try {
    bible = await loadBibleFn(bibleName);
  } catch (_) {
    throw const BackupParseException("That file isn't a valid backup");
  }

  try {
    return AppState.fromJson(json, bible);
  } catch (_) {
    throw const BackupParseException("That file isn't a valid backup");
  }
}
```

- [ ] **Step 4: Run the tests to verify they pass**

Run: `flutter test test/actions_backup_test.dart`
Expected: PASS (all 5 tests)

- [ ] **Step 5: Commit**

```bash
git add lib/store/actions_backup.dart test/actions_backup_test.dart
git commit -m "Add pure backup JSON build/parse helpers with tests"
```

---

### Task 3: Add a reusable Yes/No confirmation dialog

**Files:**
- Modify: `lib/dialog.dart`

**Interfaces:**
- Produces: `Future<bool> showConfirm(BuildContext context, String title, String message)` — resolves `true` only if the user taps "Continue"; `false` on "Cancel", back button, or barrier dismiss.

- [ ] **Step 1: Add `showConfirm` to `lib/dialog.dart`**

Add this function after `showError` (around line 34), following the same style as `showAlert`/`showReportError` already in the file:

```dart
Future<bool> showConfirm(BuildContext context, String title, String message) async {
  final result = await showDialog<bool>(
    context: context,
    barrierColor: Colors.black54,
    builder: (dialogContext) {
      return AlertDialog(
        title: Text(title),
        content: Text(message),
        actionsAlignment: MainAxisAlignment.end,
        actionsOverflowButtonSpacing: 8.0,
        actions: [
          TextButton(
            onPressed: () => Navigator.of(dialogContext).pop(false),
            child: const Text("Cancel"),
          ),
          TextButton(
            onPressed: () => Navigator.of(dialogContext).pop(true),
            child: const Text("Continue"),
          ),
        ],
      );
    },
  );
  return result ?? false;
}
```

There is no existing widget-test harness for dialogs in this codebase (only golden screenshot tests, which don't drive dialog interaction) — verified manually in Task 7.

- [ ] **Step 2: Verify it compiles**

Run: `flutter analyze`
Expected: no new errors.

- [ ] **Step 3: Commit**

```bash
git add lib/dialog.dart
git commit -m "Add showConfirm Yes/No dialog helper"
```

---

### Task 4: `ExportAppStateAction`

**Files:**
- Modify: `lib/store/actions_backup.dart`

**Interfaces:**
- Consumes: `buildBackupFileName()`, `buildBackupJson(AppState)` (Task 2); `showError`/`showAlert` (`lib/dialog.dart`); `FilePicker.saveFile` (`file_picker`, Task 1).
- Produces: `class ExportAppStateAction extends ReduxAction<AppState>` — constructor `ExportAppStateAction(BuildContext buildContext)`.

No automated test for this task: it calls `file_picker`'s platform channel, which (per the project's existing convention noted in Global Constraints) isn't exercised in headless `flutter test`. Correctness of the logic it depends on is covered by Task 2; the action's actual file-writing behavior is verified manually in Task 7.

- [ ] **Step 1: Implement the action**

Add to the top of `lib/store/actions_backup.dart`:

```dart
import "dart:io";

import "package:async_redux/async_redux.dart";
import "package:file_picker/file_picker.dart";
import "package:flutter/foundation.dart";
import "package:flutter/material.dart";
import "package:only_bible_app/dialog.dart";
```

(these go alongside the existing `dart:convert`/`gen/bible.gen.dart`/`app_state.dart`/`utils.dart` imports already there from Task 2)

Then append the action at the bottom of the file:

```dart
class ExportAppStateAction extends ReduxAction<AppState> {
  final BuildContext buildContext;

  ExportAppStateAction(this.buildContext);

  @override
  Future<AppState?> reduce() async {
    final jsonString = buildBackupJson(state);
    final fileName = buildBackupFileName();
    String? path;
    try {
      path = await FilePicker.saveFile(
        fileName: fileName,
        bytes: kIsWeb ? utf8.encode(jsonString) : null,
      );
      if (path == null) return null; // user cancelled the dialog
      if (!kIsWeb) {
        await File(path).writeAsString(jsonString);
      }
    } catch (_) {
      if (buildContext.mounted) {
        showError(buildContext, "Failed to export backup");
      }
      return null;
    }
    if (buildContext.mounted) {
      showAlert(buildContext, "Backup Exported", "Your backup was saved successfully.");
    }
    return null;
  }
}
```

- [ ] **Step 2: Verify it compiles**

Run: `flutter analyze`
Expected: no new errors (in particular, no unused-import warnings — `dart:io`, `file_picker`, `flutter/foundation.dart`, `flutter/material.dart`, `only_bible_app/dialog.dart` are all now used).

- [ ] **Step 3: Commit**

```bash
git add lib/store/actions_backup.dart
git commit -m "Add ExportAppStateAction"
```

---

### Task 5: `ImportAppStateAction`

**Files:**
- Modify: `lib/store/actions_backup.dart`

**Interfaces:**
- Consumes: `parseBackupState`, `BackupParseException` (Task 2); `showConfirm`, `showError`, `showAlert` (`lib/dialog.dart`); `FilePicker.pickFiles` (`file_picker`).
- Produces: `class ImportAppStateAction extends ReduxAction<AppState>` — constructor `ImportAppStateAction(BuildContext buildContext)`.

Same testing note as Task 4: no automated test for the plugin-touching action itself; `parseBackupState`'s behavior is already covered by Task 2's tests; end-to-end behavior is verified manually in Task 7.

- [ ] **Step 1: Implement the action**

Append to `lib/store/actions_backup.dart`:

```dart
class ImportAppStateAction extends ReduxAction<AppState> {
  final BuildContext buildContext;

  ImportAppStateAction(this.buildContext);

  @override
  Future<AppState?> reduce() async {
    final confirmed = await showConfirm(
      buildContext,
      "Import Backup",
      "This will replace all your current highlights and settings. Continue?",
    );
    if (!confirmed) return null;
    if (!buildContext.mounted) return null;

    final result = await FilePicker.pickFiles(
      type: FileType.custom,
      allowedExtensions: ["json"],
      withData: true,
    );
    if (result == null || result.files.isEmpty) return null; // user cancelled

    final bytes = result.files.single.bytes;
    if (bytes == null) {
      if (buildContext.mounted) {
        showError(buildContext, "That file isn't a valid backup");
      }
      return null;
    }

    try {
      final newState = await parseBackupState(utf8.decode(bytes));
      if (buildContext.mounted) {
        showAlert(buildContext, "Backup Imported", "Your backup was restored successfully.");
      }
      return newState;
    } on BackupParseException catch (err) {
      if (buildContext.mounted) {
        showError(buildContext, err.message);
      }
      return null;
    }
  }
}
```

- [ ] **Step 2: Verify it compiles**

Run: `flutter analyze`
Expected: no new errors.

- [ ] **Step 3: Commit**

```bash
git add lib/store/actions_backup.dart
git commit -m "Add ImportAppStateAction"
```

---

### Task 6: Wire the Backup section into `SettingsSheet`

**Files:**
- Modify: `lib/widgets/settings_sheet.dart`
- Modify (regenerate): `test/screenshot_test.dart` goldens for the `settings` screenshot

**Interfaces:**
- Consumes: `ExportAppStateAction`, `ImportAppStateAction` (Task 4/5).

- [ ] **Step 1: Add the import**

In `lib/widgets/settings_sheet.dart`, add alongside the existing imports (after line 4, `import "package:only_bible_app/store/actions_state.dart";` — check the actual current import list first since Task 4/5 changes don't touch this file):

```dart
import "package:only_bible_app/store/actions_backup.dart";
```

- [ ] **Step 2: Add the Backup section**

In `lib/widgets/settings_sheet.dart`, insert this block right after the "English titles toggle" `Material` card (i.e. after its closing `),` and before the final `const SizedBox(height: 16), Spacer(),`):

```dart
          const SizedBox(height: 16),
          Text(
            "Backup",
            style: Theme.of(context).textTheme.titleMedium,
          ),
          const SizedBox(height: 8),
          Material(
            elevation: isDark ? 2 : 1,
            borderRadius: BorderRadius.circular(12),
            color: cardColor,
            shadowColor: colorScheme.shadow,
            child: InkWell(
              borderRadius: BorderRadius.circular(12),
              onTap: () => context.dispatch(ExportAppStateAction(context)),
              child: Container(
                padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 12),
                decoration: BoxDecoration(
                  borderRadius: BorderRadius.circular(12),
                  border: Border.all(color: cardBorderColor),
                ),
                child: Row(
                  children: [
                    Icon(Icons.download_outlined, color: colorScheme.onSurface),
                    const SizedBox(width: 12),
                    const Expanded(child: Text("Export Backup")),
                  ],
                ),
              ),
            ),
          ),
          const SizedBox(height: 8),
          Material(
            elevation: isDark ? 2 : 1,
            borderRadius: BorderRadius.circular(12),
            color: cardColor,
            shadowColor: colorScheme.shadow,
            child: InkWell(
              borderRadius: BorderRadius.circular(12),
              onTap: () => context.dispatch(ImportAppStateAction(context)),
              child: Container(
                padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 12),
                decoration: BoxDecoration(
                  borderRadius: BorderRadius.circular(12),
                  border: Border.all(color: cardBorderColor),
                ),
                child: Row(
                  children: [
                    Icon(Icons.upload_outlined, color: colorScheme.onSurface),
                    const SizedBox(width: 12),
                    const Expanded(child: Text("Import Backup")),
                  ],
                ),
              ),
            ),
          ),
```

- [ ] **Step 3: Verify it compiles and analyzes cleanly**

Run: `flutter analyze`
Expected: no new errors.

- [ ] **Step 4: Regenerate the settings golden screenshots**

The new rows change the rendered height/content of `SettingsSheet`, so the existing `settings` golden (`test/screenshot_test.dart:211`, device loop covering `GoldenScreenshotDevices.iphone`/`ipad`/`androidPhone` at `test/screenshot_test.dart:103-105`) will now mismatch. Regenerate it:

Run: `flutter test test/screenshot_test.dart --update-goldens`
Expected: exits 0; this overwrites the committed master images:
- `ios/fastlane/screenshots/en-US/settings.png`
- `ios/fastlane/screenshots/en-US/ipad_settings.png`
- `android/fastlane/metadata/android/en-GB/images/phoneScreenshots/settings.png`

- [ ] **Step 5: Confirm the screenshot test now passes without `--update-goldens`**

Run: `flutter test test/screenshot_test.dart`
Expected: PASS

- [ ] **Step 6: Review the updated screenshots, then commit**

Open the three PNGs listed in Step 4 and confirm the new "Backup" section renders as expected (no clipping/overflow) on all three form factors before committing:

```bash
git add lib/widgets/settings_sheet.dart \
  ios/fastlane/screenshots/en-US/settings.png \
  ios/fastlane/screenshots/en-US/ipad_settings.png \
  android/fastlane/metadata/android/en-GB/images/phoneScreenshots/settings.png
git commit -m "Add Export/Import Backup rows to settings sheet"
```

---

### Task 7: Manual end-to-end verification

**Files:** none (no code changes)

- [ ] **Step 1: Run the full test suite**

Run: `flutter test`
Expected: all tests pass, including the new `test/actions_backup_test.dart` and the regenerated `test/screenshot_test.dart`.

- [ ] **Step 2: Launch the app on macOS**

Run: `flutter run -d macos`
Expected: app launches to the last-read chapter.

- [ ] **Step 3: Highlight a verse, then export**

In the running app: highlight at least one verse, open Settings (gear icon), tap "Export Backup", choose a destination in the save dialog (e.g. Desktop).
Expected: a success dialog appears ("Backup Exported"); the chosen destination now contains a `only_bible_app_backup_<date>.json` file; open it in a text editor and confirm it contains a `"highlights"` object with your highlighted verse's key.

- [ ] **Step 4: Change state, then import the backup back**

In the running app: remove the highlight from Step 3 (so current state now differs from the backup), open Settings, tap "Import Backup", confirm the replace-warning dialog, and pick the file exported in Step 3.
Expected: a success dialog appears ("Backup Imported"); the highlight from Step 3 reappears in the reading view, confirming the state was replaced from the file.

- [ ] **Step 5: Verify cancel paths don't error**

Tap "Export Backup" and immediately cancel the save dialog; tap "Import Backup", confirm the warning, then cancel the file-open dialog.
Expected: no error dialog appears in either case, and app state is unchanged.

- [ ] **Step 6: Verify a malformed file is rejected on import**

Create a text file containing `not valid json` and try importing it via "Import Backup".
Expected: an error dialog appears with "That file isn't a valid backup"; app state is unchanged.