feat: Enhance GameDataPickerManager and Wolf3dAppManager with improved directory and file picking capabilities

Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>

packages/wolf_3d_flutter/lib/managers/game_data_picker_manager.dart

@@ -5,18 +5,47 @@ import 'dart:collection';
 import 'package:file_selector/file_selector.dart';
 import 'package:wolf_3d_flutter/wolf_3d_flutter.dart';
 
+/// Callback used to open a directory picker.
+typedef PickDirectoryCallback =
+    Future<String?> Function({
+      String? confirmButtonText,
+    });
+
+/// Callback used to open a multi-file picker.
+typedef PickFilesCallback = Future<List<XFile>> Function();
+
 /// Coordinates game-data selection flows for the no-data setup screen.
 class GameDataPickerManager {
-  GameDataPickerManager({required this.engine});
+  /// Creates a picker workflow manager bound to [engine].
+  ///
+  /// [pickDirectory] and [pickFiles] are injectable test seams. Production
+  /// usage should rely on their defaults from `file_selector`.
+  GameDataPickerManager({
+    required this.engine,
+    PickDirectoryCallback? pickDirectory,
+    PickFilesCallback? pickFiles,
+  }) : _pickDirectory = pickDirectory ?? getDirectoryPath,
+       _pickFiles = pickFiles ?? openFiles;
 
+  /// Engine facade reloaded when users choose new data locations.
   final Wolf3dFlutterEngine engine;
 
+  final PickDirectoryCallback _pickDirectory;
+  final PickFilesCallback _pickFiles;
+
   bool _isLoadingGameData = false;
   String? _pickerError;
 
+  /// Whether a picker/reload operation is currently in progress.
   bool get isLoadingGameData => _isLoadingGameData;
+
+  /// Last picker/reload error, if any.
   String? get pickerError => _pickerError;
 
+  /// Prompts the user for a game-data directory and reloads discovery.
+  ///
+  /// Calls [notifyChanged] before and after the async workflow so UIs can
+  /// update loading/error state.
   Future<void> pickGameDataDirectory({
     required void Function() notifyChanged,
   }) async {
@@ -25,7 +54,7 @@ class GameDataPickerManager {
     notifyChanged();
 
     try {
-      final String? directoryPath = await getDirectoryPath(
+      final String? directoryPath = await _pickDirectory(
         confirmButtonText: 'Use this folder',
       );
 
@@ -42,6 +71,11 @@ class GameDataPickerManager {
     }
   }
 
+  /// Prompts the user for one or more game-data files and reloads discovery.
+  ///
+  /// Selected file paths are collapsed into unique parent directories, then
+  /// passed to [Wolf3dFlutterEngine.init] as one primary directory plus
+  /// [Wolf3dFlutterEngine.init] `additionalDirectories`.
   Future<void> pickGameDataFiles({
     required void Function() notifyChanged,
   }) async {
@@ -50,7 +84,7 @@ class GameDataPickerManager {
     notifyChanged();
 
     try {
-      final List<XFile> selectedFiles = await openFiles();
+      final List<XFile> selectedFiles = await _pickFiles();
 
       if (selectedFiles.isEmpty) {
         return;
@@ -84,6 +118,7 @@ class GameDataPickerManager {
     }
   }
 
+  /// Returns the parent directory component from [path].
   String _directoryFromFilePath(String path) {
     final String trimmedPath = path.trim();
     if (trimmedPath.isEmpty) {

packages/wolf_3d_flutter/lib/managers/wolf3d_app_manager.dart

@@ -6,17 +6,26 @@ import 'package:wolf_3d_flutter/wolf_3d_flutter.dart';
 
 /// Coordinates app-shell setup actions and shutdown behavior.
 class Wolf3dAppManager {
-  Wolf3dAppManager({required this.engine});
+  /// Creates an app-shell manager bound to [engine].
+  ///
+  /// [pickerManager] can be provided in tests to control picker behavior.
+  Wolf3dAppManager({
+    required this.engine,
+    GameDataPickerManager? pickerManager,
+  }) : _pickerManager = pickerManager ?? GameDataPickerManager(engine: engine);
 
+  /// Engine facade managed by the app shell.
   final Wolf3dFlutterEngine engine;
-  late final GameDataPickerManager _pickerManager = GameDataPickerManager(
-    engine: engine,
-  );
+  final GameDataPickerManager _pickerManager;
   Future<void>? _shutdownFuture;
 
+  /// Forwarded picker loading flag for UI binding.
   bool get isLoadingGameData => _pickerManager.isLoadingGameData;
+
+  /// Forwarded picker error text for UI binding.
   String? get pickerError => _pickerManager.pickerError;
 
+  /// Shuts down engine audio exactly once and reuses in-flight shutdown calls.
   Future<void> ensureAudioShutdown() {
     final existing = _shutdownFuture;
     if (existing != null) {
@@ -28,12 +37,14 @@ class Wolf3dAppManager {
     return shutdown;
   }
 
+  /// Delegates directory picker + reload behavior.
   Future<void> pickGameDataDirectory({
     required void Function() notifyChanged,
   }) async {
     await _pickerManager.pickGameDataDirectory(notifyChanged: notifyChanged);
   }
 
+  /// Delegates file picker + reload behavior.
   Future<void> pickGameDataFiles({
     required void Function() notifyChanged,
   }) async {