com.wallstop-studios.unity-helpers 2.0.0-rc81.6 → 2.0.0-rc81.9

package/Runtime/Visuals/UIToolkit/MultiFileSelectorElement.cs

@@ -1,322 +1,945 @@
-namespace WallstopStudios.UnityHelpers.Visuals.UIToolkit
-{
-    using System;
-    using System.Collections.Generic;
-    using System.IO;
-    using System.Linq;
-    using UnityEngine;
-    using UnityEngine.UIElements;
-    using WallstopStudios.UnityHelpers.Core.Extension;
-    using WallstopStudios.UnityHelpers.Core.Helper;
-
-    public sealed class MultiFileSelectorElement : VisualElement
-    {
-        private const string DefaultRootPath = "Assets";
-
-        public event Action<List<string>> OnFilesSelected;
-        public event Action OnCancelled;
-
-        private readonly TextField _pathField;
-        private readonly Button _upButton;
-        private readonly VisualElement _fileListContent;
-        private readonly HashSet<string> _fileExtensionsToDisplay;
-        private readonly List<string> _selectedFilePaths = new();
-
-        private string _currentDirectory;
-
-        public MultiFileSelectorElement(string initialPath, string[] filterExtensions)
-        {
-            _fileExtensionsToDisplay =
-                filterExtensions?.Select(ext => ext).ToHashSet(StringComparer.OrdinalIgnoreCase)
-                ?? new HashSet<string>(StringComparer.OrdinalIgnoreCase);
-
-            style.position = Position.Absolute;
-            style.left = style.top = style.right = style.bottom = 0;
-            style.backgroundColor = new StyleColor(new Color(0.1f, 0.1f, 0.1f, 0.9f));
-            style.paddingLeft = style.paddingRight = style.paddingTop = style.paddingBottom = 20;
-            style.alignItems = Align.Center;
-            style.justifyContent = Justify.Center;
-
-            VisualElement contentBox = new()
-            {
-                style =
-                {
-                    width = new Length(80, LengthUnit.Percent),
-                    height = new Length(80, LengthUnit.Percent),
-                    maxWidth = 700,
-                    maxHeight = 500,
-                    backgroundColor = new StyleColor(Color.gray),
-                    paddingLeft = 10,
-                    paddingRight = 10,
-                    paddingTop = 10,
-                    paddingBottom = 10,
-                    flexDirection = FlexDirection.Column,
-                    borderTopLeftRadius = 5,
-                    borderTopRightRadius = 5,
-                    borderBottomLeftRadius = 5,
-                    borderBottomRightRadius = 5,
-                },
-            };
-            Add(contentBox);
-
-            VisualElement headerControls = new()
-            {
-                style =
-                {
-                    flexDirection = FlexDirection.Row,
-                    marginBottom = 5,
-                    alignItems = Align.Center,
-                },
-            };
-            Button assetsFolderButton = new(() => NavigateTo(DefaultRootPath))
-            {
-                text = "Assets",
-                style = { width = 60, marginRight = 5 },
-            };
-            _upButton = new Button(NavigateUp)
-            {
-                text = "Up",
-                style = { width = 40, marginRight = 5 },
-            };
-            _pathField = new TextField(null)
-            {
-                isReadOnly = true,
-                style =
-                {
-                    flexGrow = 1,
-                    flexShrink = 1,
-                    marginRight = 5,
-                },
-            };
-
-            headerControls.Add(assetsFolderButton);
-            headerControls.Add(_upButton);
-            headerControls.Add(_pathField);
-            contentBox.Add(headerControls);
-
-            // TODO: Custom styling
-            ScrollView fileListView = new(ScrollViewMode.Vertical)
-            {
-                style =
-                {
-                    flexGrow = 1,
-                    borderTopWidth = 1,
-                    borderBottomWidth = 1,
-                    borderLeftWidth = 1,
-                    borderRightWidth = 1,
-                    borderBottomColor = Color.black,
-                    borderTopColor = Color.black,
-                    borderLeftColor = Color.black,
-                    borderRightColor = Color.black,
-                    marginBottom = 5,
-                    backgroundColor = Color.white * 0.15f,
-                },
-            };
-            _fileListContent = new VisualElement();
-            fileListView.Add(_fileListContent);
-            contentBox.Add(fileListView);
-
-            VisualElement footerControls = new()
-            {
-                style =
-                {
-                    flexDirection = FlexDirection.Row,
-                    justifyContent = Justify.FlexEnd,
-                    marginTop = 5,
-                },
-            };
-            Button cancelButton = new(() => OnCancelled?.Invoke())
-            {
-                text = "Cancel",
-                style = { marginRight = 10 },
-            };
-            Button confirmButton = new(ConfirmSelection) { text = "Add Selected" };
-            footerControls.Add(cancelButton);
-            footerControls.Add(confirmButton);
-            contentBox.Add(footerControls);
-
-            string validInitialPath = initialPath;
-            if (
-                string.IsNullOrEmpty(validInitialPath)
-                || !Directory.Exists(Path.Combine(Application.dataPath, "..", validInitialPath))
-            )
-            {
-                validInitialPath = DefaultRootPath;
-            }
-            NavigateTo(validInitialPath);
-        }
-
-        private void NavigateTo(string path)
-        {
-            string fullPath = Path.GetFullPath(Path.Combine(Application.dataPath, "..", path));
-            string projectRootPath = Path.GetFullPath(Path.Combine(Application.dataPath, ".."));
-
-            if (!fullPath.StartsWith(projectRootPath, StringComparison.OrdinalIgnoreCase))
-            {
-                fullPath = projectRootPath;
-            }
-
-            string assetsFullPath = Path.GetFullPath(Application.dataPath);
-            if (
-                DefaultRootPath == "Assets"
-                && !fullPath.StartsWith(assetsFullPath, StringComparison.OrdinalIgnoreCase)
-                && fullPath.StartsWith(projectRootPath)
-            )
-            {
-                fullPath = assetsFullPath;
-            }
-
-            if (!Directory.Exists(fullPath))
-            {
-                Debug.LogWarning($"Directory does not exist: {fullPath}. Resetting to Assets.");
-                _currentDirectory = assetsFullPath;
-            }
-            else
-            {
-                _currentDirectory = fullPath;
-            }
-
-            if (_currentDirectory.Equals(projectRootPath, StringComparison.OrdinalIgnoreCase))
-            {
-                _pathField.SetValueWithoutNotify("Project Root");
-            }
-            else if (
-                _currentDirectory.StartsWith(projectRootPath, StringComparison.OrdinalIgnoreCase)
-            )
-            {
-                _pathField.SetValueWithoutNotify(
-                    _currentDirectory.Substring(projectRootPath.Length + 1).SanitizePath()
-                );
-            }
-            else
-            {
-                _pathField.SetValueWithoutNotify(_currentDirectory.SanitizePath());
-            }
-
-            PopulateFileList();
-            DirectoryInfo parentDirectory = Directory.GetParent(_currentDirectory);
-            _upButton.SetEnabled(
-                !_currentDirectory.Equals(assetsFullPath, StringComparison.OrdinalIgnoreCase)
-                    && parentDirectory != null
-                    && parentDirectory.FullName.Length >= projectRootPath.Length
-            );
-        }
-
-        private void NavigateUp()
-        {
-            if (string.IsNullOrEmpty(_currentDirectory))
-            {
-                return;
-            }
-
-            DirectoryInfo directoryParent = Directory.GetParent(_currentDirectory);
-            if (directoryParent != null)
-            {
-                string projectRootPath = Path.GetFullPath(Path.Combine(Application.dataPath, ".."));
-
-                if (
-                    directoryParent.FullName.Length < projectRootPath.Length
-                    || _currentDirectory.Equals(
-                        Path.GetFullPath(Application.dataPath),
-                        StringComparison.OrdinalIgnoreCase
-                    )
-                )
-                {
-                    Debug.Log("Cannot navigate above Assets folder.");
-                    NavigateTo(DefaultRootPath);
-                    return;
-                }
-                NavigateTo(directoryParent.FullName.Substring(projectRootPath.Length + 1));
-            }
-        }
-
-        private void PopulateFileList()
-        {
-            _fileListContent.Clear();
-            try
-            {
-                foreach (string dirPath in Directory.GetDirectories(_currentDirectory).Ordered())
-                {
-                    string dirName = Path.GetFileName(dirPath);
-                    Button dirButton = new(() =>
-                        NavigateTo(
-                            dirPath.Substring(
-                                Path.GetFullPath(Path.Combine(Application.dataPath, "..")).Length
-                                    + 1
-                            )
-                        )
-                    )
-                    {
-                        text = $"📁 {dirName}",
-                        style = { unityTextAlign = TextAnchor.MiddleLeft, marginBottom = 1 },
-                    };
-                    _fileListContent.Add(dirButton);
-                }
-
-                foreach (string filePath in Directory.GetFiles(_currentDirectory).Ordered())
-                {
-                    if (_fileExtensionsToDisplay.Count > 0)
-                    {
-                        string extension = Path.GetExtension(filePath);
-                        if (!_fileExtensionsToDisplay.Contains(extension))
-                        {
-                            continue;
-                        }
-                    }
-
-                    VisualElement fileItem = new()
-                    {
-                        style =
-                        {
-                            flexDirection = FlexDirection.Row,
-                            alignItems = Align.Center,
-                            marginBottom = 1,
-                        },
-                    };
-                    Toggle toggle = new()
-                    {
-                        value = _selectedFilePaths.Contains(filePath),
-                        style = { marginRight = 5 },
-                    };
-                    toggle.RegisterValueChangedCallback(evt =>
-                    {
-                        if (evt.newValue)
-                        {
-                            _selectedFilePaths.Add(filePath);
-                        }
-                        else
-                        {
-                            _selectedFilePaths.Remove(filePath);
-                        }
-                    });
-
-                    Label label = new(Path.GetFileName(filePath));
-                    label.RegisterCallback<PointerDownEvent, Toggle>(
-                        (_, context) => context.value = !context.value,
-                        toggle
-                    );
-
-                    fileItem.Add(toggle);
-                    fileItem.Add(label);
-                    _fileListContent.Add(fileItem);
-                }
-            }
-            catch (Exception ex)
-            {
-                Debug.LogError($"Error accessing path {_currentDirectory}: {ex.Message}");
-                _fileListContent.Add(new Label($"Error reading directory: {ex.Message}"));
-            }
-        }
-
-        private void ConfirmSelection()
-        {
-            OnFilesSelected?.Invoke(_selectedFilePaths.ToList());
-        }
-
-        public void ResetAndShow(string newInitialPath)
-        {
-            _selectedFilePaths.Clear();
-            NavigateTo(newInitialPath);
-        }
-    }
-}
+namespace WallstopStudios.UnityHelpers.Visuals.UIToolkit
+{
+    using System;
+    using System.Collections.Generic;
+    using System.IO;
+    using UnityEngine;
+    using UnityEngine.UIElements;
+    using WallstopStudios.UnityHelpers.Core.Helper;
+
+    /// <summary>
+    /// Multi-file selector overlay built with UI Toolkit.
+    /// </summary>
+    /// <remarks>
+    /// Purpose
+    /// - Lets users quickly navigate folders (constrained to the Unity project root/Assets) and select multiple files.
+    /// - Optimized for large directories via virtualization and pooled buffers to keep the Editor responsive.
+    ///
+    /// Highlights
+    /// - Virtualized ListView with folder-first ordering and live search filter.
+    /// - Zero-allocation streaming directory enumeration with pooled lists (see Buffers&lt;T&gt;).
+    /// - HashSet-backed selection with Select All / Clear / Invert helpers.
+    /// - Clickable breadcrumbs and double-click directory navigation.
+    /// - Smart persistence of last directory and search per logical scope or provided key.
+    ///
+    /// When to use
+    /// - Any Editor tooling requiring an in-UI multi-file picker where the native file dialog is too limited or needs custom selection semantics.
+    /// - Scenarios where you need to keep selections across multiple navigations and filter by file extension.
+    ///
+    /// Usage
+    /// <code>
+    /// // Typical usage inside an EditorWindow
+    /// var selector = new MultiFileSelectorElement(
+    ///     initialPath: "Assets/Animations",
+    ///     filterExtensions: new[] { ".anim" },
+    ///     persistenceKey: "AnimationViewer"
+    /// );
+    /// selector.OnFilesSelected += files => Debug.Log($"Selected {files.Count} files");
+    /// selector.OnCancelled += () => Debug.Log("Selection cancelled");
+    /// rootVisualElement.Add(selector);
+    /// // To hide: selector.parent.Remove(selector);
+    /// </code>
+    public sealed class MultiFileSelectorElement : VisualElement
+    {
+        private const string DefaultRootPath = "Assets";
+        private const string PrefKey_LastDir = "WallstopStudios.MultiFileSelector.lastDirectory";
+        private const string PrefKey_LastSearch = "WallstopStudios.MultiFileSelector.lastSearch";
+        private const string PrefKey_LastUsed = "WallstopStudios.MultiFileSelector.lastUsed";
+        private const string PrefKey_ScopesIndex = "WallstopStudios.MultiFileSelector.scopes";
+
+        /// <summary>
+        /// Invoked when the user confirms selection. Provides absolute file system paths.
+        /// </summary>
+        public event Action<List<string>> OnFilesSelected;
+
+        /// <summary>
+        /// Invoked when the user cancels the dialog without confirming.
+        /// </summary>
+        public event Action OnCancelled;
+
+        private readonly TextField _pathField;
+        private readonly Button _upButton;
+        private readonly ListView _listView;
+        private readonly HashSet<string> _filterExtensions;
+        private readonly HashSet<string> _selectedSet = new(StringComparer.OrdinalIgnoreCase);
+        private readonly List<Item> _items = new();
+        private readonly string _projectRootPath;
+        private readonly string _assetsFullPath;
+        private readonly Button _confirmButton;
+        private readonly TextField _searchField;
+        private readonly VisualElement _breadcrumbBar;
+
+        private string _currentDirectory;
+        private string _searchText = string.Empty;
+        private readonly string _prefsScope;
+
+        private readonly struct Item
+        {
+            public readonly bool isDirectory;
+            public readonly string fullPath;
+            public readonly string name;
+
+            public Item(bool isDirectory, string fullPath, string name)
+            {
+                this.isDirectory = isDirectory;
+                this.fullPath = fullPath;
+                this.name = name;
+            }
+        }
+
+        /// <summary>
+        /// Creates a new multi-file selector.
+        /// </summary>
+        /// <param name="initialPath">Project-relative path (e.g., "Assets/..."). If null or invalid, defaults to Assets.</param>
+        /// <param name="filterExtensions">Allowed file extensions (with or without leading dot). Empty/null means all files.</param>
+        /// <param name="persistenceKey">Optional key to persist last directory and search across sessions for this selector. If null or empty, no persistence occurs.</param>
+        public MultiFileSelectorElement(
+            string initialPath,
+            string[] filterExtensions,
+            string persistenceKey = null
+        )
+        {
+            _projectRootPath = Path.GetFullPath(Path.Combine(Application.dataPath, ".."));
+            _assetsFullPath = Path.GetFullPath(Application.dataPath);
+
+            // Normalize filters: ensure leading '.' and OrdinalIgnoreCase
+            if (filterExtensions is { Length: > 0 })
+            {
+                _filterExtensions = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+                foreach (string ext in filterExtensions)
+                {
+                    if (string.IsNullOrWhiteSpace(ext))
+                    {
+                        continue;
+                    }
+
+                    string e = ext.StartsWith(".", StringComparison.Ordinal) ? ext : "." + ext;
+                    _filterExtensions.Add(e);
+                }
+            }
+            else
+            {
+                _filterExtensions = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            }
+
+            _prefsScope = BuildScope(initialPath, _filterExtensions, persistenceKey);
+            if (!string.IsNullOrEmpty(_prefsScope))
+            {
+                RegisterScope(_prefsScope);
+            }
+
+            style.position = Position.Absolute;
+            style.left = style.top = style.right = style.bottom = 0;
+            style.backgroundColor = new StyleColor(new Color(0.1f, 0.1f, 0.1f, 0.9f));
+            style.paddingLeft = style.paddingRight = style.paddingTop = style.paddingBottom = 20;
+            style.alignItems = Align.Center;
+            style.justifyContent = Justify.Center;
+
+            VisualElement contentBox = new()
+            {
+                style =
+                {
+                    width = new Length(80, LengthUnit.Percent),
+                    height = new Length(80, LengthUnit.Percent),
+                    maxWidth = 700,
+                    maxHeight = 500,
+                    backgroundColor = new StyleColor(Color.gray),
+                    paddingLeft = 10,
+                    paddingRight = 10,
+                    paddingTop = 10,
+                    paddingBottom = 10,
+                    flexDirection = FlexDirection.Column,
+                    borderTopLeftRadius = 5,
+                    borderTopRightRadius = 5,
+                    borderBottomLeftRadius = 5,
+                    borderBottomRightRadius = 5,
+                },
+            };
+            Add(contentBox);
+
+            VisualElement headerControls = new()
+            {
+                style =
+                {
+                    flexDirection = FlexDirection.Row,
+                    marginBottom = 5,
+                    alignItems = Align.Center,
+                },
+            };
+            Button assetsFolderButton = new(() => NavigateTo(DefaultRootPath))
+            {
+                text = "Assets",
+                style = { width = 60, marginRight = 5 },
+            };
+            _upButton = new Button(NavigateUp)
+            {
+                text = "Up",
+                style = { width = 40, marginRight = 5 },
+            };
+            _pathField = new TextField(null)
+            {
+                isReadOnly = true,
+                style =
+                {
+                    flexGrow = 1,
+                    flexShrink = 1,
+                    marginRight = 5,
+                },
+            };
+
+            _searchField = new TextField(null)
+            {
+                isReadOnly = false,
+                style = { width = 150, marginRight = 5 },
+                tooltip = "Filter by name",
+            };
+            _searchField.RegisterValueChangedCallback(evt =>
+            {
+                _searchText = evt.newValue ?? string.Empty;
+                PersistString(ScopedKey(PrefKey_LastSearch), _searchText);
+                UpdateLastUsedNow();
+                PopulateFileList();
+            });
+            // Initialize search from persisted value
+            string persistedSearch = LoadString(ScopedKey(PrefKey_LastSearch), string.Empty);
+            if (!string.IsNullOrEmpty(persistedSearch))
+            {
+                _searchText = persistedSearch;
+                _searchField.SetValueWithoutNotify(persistedSearch);
+            }
+
+            headerControls.Add(assetsFolderButton);
+            headerControls.Add(_upButton);
+            headerControls.Add(_pathField);
+            headerControls.Add(_searchField);
+#if UNITY_EDITOR
+            Button openInExplorer = new(OpenInExplorer) { text = "Open", style = { width = 60 } };
+            headerControls.Add(openInExplorer);
+#endif
+            contentBox.Add(headerControls);
+
+            _breadcrumbBar = new VisualElement
+            {
+                style =
+                {
+                    flexDirection = FlexDirection.Row,
+                    marginBottom = 5,
+                    flexWrap = Wrap.Wrap,
+                    alignItems = Align.Center,
+                },
+            };
+            contentBox.Add(_breadcrumbBar);
+
+            _listView = new ListView
+            {
+                selectionType = SelectionType.None,
+                virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight,
+                style =
+                {
+                    flexGrow = 1,
+                    borderTopWidth = 1,
+                    borderBottomWidth = 1,
+                    borderLeftWidth = 1,
+                    borderRightWidth = 1,
+                    borderBottomColor = Color.black,
+                    borderTopColor = Color.black,
+                    borderLeftColor = Color.black,
+                    borderRightColor = Color.black,
+                    marginBottom = 5,
+                    backgroundColor = Color.white * 0.15f,
+                },
+            };
+            _listView.makeItem = MakeRow;
+            _listView.bindItem = BindRow;
+            _listView.itemsSource = _items;
+            contentBox.Add(_listView);
+
+            VisualElement footerControls = new()
+            {
+                style =
+                {
+                    flexDirection = FlexDirection.Row,
+                    justifyContent = Justify.FlexEnd,
+                    marginTop = 5,
+                },
+            };
+            Button cancelButton = new(() => OnCancelled?.Invoke())
+            {
+                text = "Cancel",
+                style = { marginRight = 10 },
+            };
+            Button selectAllButton = new(SelectAllInView)
+            {
+                text = "Select All",
+                style = { marginRight = 5 },
+            };
+            Button clearButton = new(ClearSelectionInView)
+            {
+                text = "Clear",
+                style = { marginRight = 5 },
+            };
+            Button invertButton = new(InvertSelectionInView)
+            {
+                text = "Invert",
+                style = { marginRight = 10 },
+            };
+            _confirmButton = new Button(ConfirmSelection) { text = "Add Selected (0)" };
+            footerControls.Add(selectAllButton);
+            footerControls.Add(clearButton);
+            footerControls.Add(invertButton);
+            footerControls.Add(cancelButton);
+            footerControls.Add(_confirmButton);
+            contentBox.Add(footerControls);
+
+            string validInitialPath = initialPath;
+            // Prefer persisted directory when scope is present
+            string persistedStart = LoadString(ScopedKey(PrefKey_LastDir), null);
+            if (!string.IsNullOrEmpty(persistedStart))
+            {
+                validInitialPath = persistedStart;
+            }
+            else if (string.IsNullOrEmpty(validInitialPath))
+            {
+                validInitialPath = DefaultRootPath;
+            }
+            if (
+                string.IsNullOrEmpty(validInitialPath)
+                || !Directory.Exists(Path.Combine(Application.dataPath, "..", validInitialPath))
+            )
+            {
+                validInitialPath = DefaultRootPath;
+            }
+            NavigateTo(validInitialPath);
+        }
+
+        internal void NavigateTo(string path)
+        {
+            string fullPath = Path.GetFullPath(Path.Combine(Application.dataPath, "..", path));
+
+            if (!fullPath.StartsWith(_projectRootPath, StringComparison.OrdinalIgnoreCase))
+            {
+                fullPath = _projectRootPath;
+            }
+            if (
+                string.Equals(DefaultRootPath, "Assets", StringComparison.Ordinal)
+                && !fullPath.StartsWith(_assetsFullPath, StringComparison.OrdinalIgnoreCase)
+                && fullPath.StartsWith(_projectRootPath)
+            )
+            {
+                fullPath = _assetsFullPath;
+            }
+
+            if (!Directory.Exists(fullPath))
+            {
+                Debug.LogWarning($"Directory does not exist: {fullPath}. Resetting to Assets.");
+                _currentDirectory = _assetsFullPath;
+            }
+            else
+            {
+                _currentDirectory = fullPath;
+            }
+
+            if (_currentDirectory.Equals(_projectRootPath, StringComparison.OrdinalIgnoreCase))
+            {
+                _pathField.SetValueWithoutNotify("Project Root");
+            }
+            else if (
+                _currentDirectory.StartsWith(_projectRootPath, StringComparison.OrdinalIgnoreCase)
+            )
+            {
+                _pathField.SetValueWithoutNotify(
+                    _currentDirectory.Substring(_projectRootPath.Length + 1).SanitizePath()
+                );
+            }
+            else
+            {
+                _pathField.SetValueWithoutNotify(_currentDirectory.SanitizePath());
+            }
+
+            PopulateFileList();
+            DirectoryInfo parentDirectory = Directory.GetParent(_currentDirectory);
+            _upButton.SetEnabled(
+                !_currentDirectory.Equals(_assetsFullPath, StringComparison.OrdinalIgnoreCase)
+                    && parentDirectory != null
+                    && parentDirectory.FullName.Length >= _projectRootPath.Length
+            );
+            BuildBreadcrumbs();
+            // Persist relative path (scoped) if persistence is enabled
+            string rel = _currentDirectory.StartsWith(
+                _projectRootPath,
+                StringComparison.OrdinalIgnoreCase
+            )
+                ? _currentDirectory.Substring(_projectRootPath.Length + 1)
+                : _currentDirectory;
+            string dirKey = ScopedKey(PrefKey_LastDir);
+            if (!string.IsNullOrEmpty(rel) && !string.IsNullOrEmpty(dirKey))
+            {
+                PersistString(dirKey, rel.SanitizePath());
+                UpdateLastUsedNow();
+            }
+        }
+
+        private void NavigateUp()
+        {
+            if (string.IsNullOrEmpty(_currentDirectory))
+            {
+                return;
+            }
+
+            DirectoryInfo directoryParent = Directory.GetParent(_currentDirectory);
+            if (directoryParent != null)
+            {
+                if (
+                    directoryParent.FullName.Length < _projectRootPath.Length
+                    || _currentDirectory.Equals(_assetsFullPath, StringComparison.OrdinalIgnoreCase)
+                )
+                {
+                    Debug.Log("Cannot navigate above Assets folder.");
+                    NavigateTo(DefaultRootPath);
+                    return;
+                }
+                NavigateTo(directoryParent.FullName.Substring(_projectRootPath.Length + 1));
+            }
+        }
+
+        private void PopulateFileList()
+        {
+            _items.Clear();
+            try
+            {
+                // Collect and sort directories
+                using (
+                    Utils.PooledResource<List<string>> dirLease = Utils.Buffers<string>.List.Get(
+                        out List<string> dirs
+                    )
+                )
+                {
+                    try
+                    {
+                        foreach (string d in Directory.EnumerateDirectories(_currentDirectory))
+                        {
+                            string name = Path.GetFileName(d);
+                            if (
+                                !string.IsNullOrEmpty(_searchText)
+                                && name?.IndexOf(_searchText, StringComparison.OrdinalIgnoreCase)
+                                    < 0
+                            )
+                            {
+                                continue;
+                            }
+                            dirs.Add(d);
+                        }
+                    }
+                    catch (Exception)
+                    {
+                        // Ignore individual access issues during enumeration
+                    }
+                    dirs.Sort(StringComparer.OrdinalIgnoreCase);
+                    foreach (string d in dirs)
+                    {
+                        string name = Path.GetFileName(d);
+                        _items.Add(new Item(true, d, name));
+                    }
+                }
+
+                // Collect and sort files
+                using (
+                    Utils.PooledResource<List<string>> fileLease = Utils.Buffers<string>.List.Get(
+                        out List<string> files
+                    )
+                )
+                {
+                    try
+                    {
+                        foreach (string f in Directory.EnumerateFiles(_currentDirectory))
+                        {
+                            string ext = Path.GetExtension(f);
+                            if (_filterExtensions.Count > 0 && !_filterExtensions.Contains(ext))
+                            {
+                                continue;
+                            }
+                            string name = Path.GetFileName(f);
+                            if (
+                                !string.IsNullOrEmpty(_searchText)
+                                && name?.IndexOf(_searchText, StringComparison.OrdinalIgnoreCase)
+                                    < 0
+                            )
+                            {
+                                continue;
+                            }
+                            files.Add(f);
+                        }
+                    }
+                    catch (Exception)
+                    {
+                        // Ignore individual access issues during enumeration
+                    }
+                    files.Sort(StringComparer.OrdinalIgnoreCase);
+                    foreach (string f in files)
+                    {
+                        string name = Path.GetFileName(f);
+                        _items.Add(new Item(false, f, name));
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                Debug.LogError($"Error accessing path {_currentDirectory}: {ex.Message}");
+            }
+
+            _listView.RefreshItems();
+            UpdateConfirmButtonText();
+        }
+
+        private void ConfirmSelection()
+        {
+            OnFilesSelected?.Invoke(new List<string>(_selectedSet));
+        }
+
+        /// <summary>
+        /// Clears selection and navigates to a new starting directory.
+        /// </summary>
+        /// <param name="newInitialPath">Project-relative path (e.g., "Assets/...").</param>
+        public void ResetAndShow(string newInitialPath)
+        {
+            _selectedSet.Clear();
+            NavigateTo(newInitialPath);
+        }
+
+        private VisualElement MakeRow()
+        {
+            VisualElement row = new()
+            {
+                style =
+                {
+                    flexDirection = FlexDirection.Row,
+                    alignItems = Align.Center,
+                    marginBottom = 1,
+                },
+            };
+
+            Toggle toggle = new() { style = { marginRight = 5 } };
+            Label label = new()
+            {
+                style = { unityTextAlign = TextAnchor.MiddleLeft, flexGrow = 1 },
+            };
+
+            row.Add(toggle);
+            row.Add(label);
+            return row;
+        }
+
+        private void BindRow(VisualElement row, int index)
+        {
+            if (index < 0 || index >= _items.Count)
+            {
+                return;
+            }
+            Item item = _items[index];
+            Toggle toggle = row.ElementAt(0) as Toggle;
+            Label label = row.ElementAt(1) as Label;
+
+            if (item.isDirectory)
+            {
+                // Directory rows: no toggle, clickable to navigate
+                toggle.SetEnabled(false);
+                toggle.value = false;
+                label.text = $"📁 {item.name}";
+                label.style.opacity = 1f;
+                label.tooltip = item.fullPath.SanitizePath();
+                // Remove potential previous bindings
+                row.UnregisterCallback<ClickEvent>(OnDirectoryClick);
+                label.UnregisterCallback<PointerDownEvent>(OnLabelClick);
+                label.userData = null;
+                row.RegisterCallback<ClickEvent>(OnDirectoryClick, TrickleDown.NoTrickleDown);
+                row.userData = item.fullPath;
+            }
+            else
+            {
+                // File rows: toggleable selection
+                row.UnregisterCallback<ClickEvent>(OnDirectoryClick);
+                row.userData = null;
+                toggle.SetEnabled(true);
+                bool isSelected = _selectedSet.Contains(item.fullPath);
+                toggle.SetValueWithoutNotify(isSelected);
+                toggle.tooltip = item.fullPath.SanitizePath();
+                label.text = item.name;
+                label.style.opacity = 1f;
+
+                toggle.UnregisterValueChangedCallback(OnToggleChanged);
+                toggle.RegisterValueChangedCallback(OnToggleChanged);
+                toggle.userData = item.fullPath;
+                // Clicking the label toggles selection
+                label.UnregisterCallback<PointerDownEvent>(OnLabelClick);
+                label.userData = toggle;
+                label.RegisterCallback<PointerDownEvent>(OnLabelClick);
+            }
+        }
+
+        private void OnDirectoryClick(ClickEvent evt)
+        {
+            if (evt.button != 0 || evt.clickCount < 2)
+            {
+                return;
+            }
+            string path = evt.currentTarget is VisualElement ve ? ve.userData as string : null;
+            if (string.IsNullOrEmpty(path))
+            {
+                return;
+            }
+
+            // Navigate on single or double click
+            string relative = path;
+            if (relative.StartsWith(_projectRootPath, StringComparison.OrdinalIgnoreCase))
+            {
+                relative = relative.Substring(_projectRootPath.Length + 1);
+            }
+            NavigateTo(relative);
+        }
+
+        private void OnToggleChanged(ChangeEvent<bool> evt)
+        {
+            string filePath = (evt.target as Toggle)?.userData as string;
+            if (string.IsNullOrEmpty(filePath))
+            {
+                return;
+            }
+            if (evt.newValue)
+            {
+                _selectedSet.Add(filePath);
+            }
+            else
+            {
+                _selectedSet.Remove(filePath);
+            }
+            UpdateConfirmButtonText();
+        }
+
+        private void UpdateConfirmButtonText()
+        {
+            _confirmButton.text = $"Add Selected ({_selectedSet.Count})";
+        }
+
+        /// <summary>
+        /// Returns the current visible entry names (folders and files) for diagnostics and tests.
+        /// Folder names are returned without UI decorations.
+        /// </summary>
+        public IReadOnlyList<string> DebugGetVisibleEntryNames()
+        {
+            using Utils.PooledResource<List<string>> lease = Utils.Buffers<string>.List.Get(
+                out List<string> list
+            );
+            for (int i = 0; i < _items.Count; i++)
+            {
+                list.Add(_items[i].name);
+            }
+            return list.ToArray();
+        }
+
+        /// <summary>
+        /// Returns a copy of the selected file paths for diagnostics and tests.
+        /// </summary>
+        public IReadOnlyCollection<string> DebugGetSelectedFilePaths()
+        {
+            return new List<string>(_selectedSet);
+        }
+
+        private void BuildBreadcrumbs()
+        {
+            _breadcrumbBar.Clear();
+            string display;
+            string rel;
+            if (_currentDirectory.StartsWith(_projectRootPath, StringComparison.OrdinalIgnoreCase))
+            {
+                rel = _currentDirectory.Substring(_projectRootPath.Length).TrimStart('/', '\\');
+            }
+            else
+            {
+                rel = _currentDirectory;
+            }
+
+            AddCrumb("Assets", "Assets");
+
+            if (!string.IsNullOrEmpty(rel))
+            {
+                // If rel starts with Assets, strip it for subsequent segments
+                display = rel.Replace('\\', '/');
+                if (display.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase))
+                {
+                    display = display.Substring("Assets/".Length);
+                }
+
+                string cumulative = "Assets";
+                string[] parts = display.Split(
+                    new[] { '/' },
+                    StringSplitOptions.RemoveEmptyEntries
+                );
+                foreach (string part in parts)
+                {
+                    cumulative = cumulative + "/" + part;
+                    AddCrumb(part, cumulative);
+                }
+            }
+
+            // Remove trailing separator if exists
+            if (
+                _breadcrumbBar.childCount > 0
+                && _breadcrumbBar.ElementAt(_breadcrumbBar.childCount - 1) is Label
+            )
+            {
+                _breadcrumbBar.RemoveAt(_breadcrumbBar.childCount - 1);
+            }
+
+            return;
+
+            // Start with root segment
+            void AddCrumb(string title, string navigateTo)
+            {
+                Button b = new(() => NavigateTo(navigateTo))
+                {
+                    text = title,
+                    style = { marginRight = 4 },
+                };
+                _breadcrumbBar.Add(b);
+                Label sep = new("/") { style = { marginRight = 4 } };
+                _breadcrumbBar.Add(sep);
+            }
+        }
+
+        private void OnLabelClick(PointerDownEvent evt)
+        {
+            if (evt.button != 0)
+            {
+                return;
+            }
+            Toggle toggle = (evt.currentTarget as VisualElement)?.userData as Toggle;
+            if (toggle != null)
+            {
+                toggle.value = !toggle.value;
+            }
+        }
+
+        internal void SelectAllInView()
+        {
+            for (int i = 0; i < _items.Count; i++)
+            {
+                Item it = _items[i];
+                if (!it.isDirectory)
+                {
+                    _selectedSet.Add(it.fullPath);
+                }
+            }
+            _listView.RefreshItems();
+            UpdateConfirmButtonText();
+        }
+
+        internal void ClearSelectionInView()
+        {
+            for (int i = 0; i < _items.Count; i++)
+            {
+                Item it = _items[i];
+                if (!it.isDirectory)
+                {
+                    _selectedSet.Remove(it.fullPath);
+                }
+            }
+            _listView.RefreshItems();
+            UpdateConfirmButtonText();
+        }
+
+        internal void InvertSelectionInView()
+        {
+            for (int i = 0; i < _items.Count; i++)
+            {
+                Item it = _items[i];
+                if (!it.isDirectory)
+                {
+                    if (_selectedSet.Contains(it.fullPath))
+                    {
+                        _selectedSet.Remove(it.fullPath);
+                    }
+                    else
+                    {
+                        _selectedSet.Add(it.fullPath);
+                    }
+                }
+            }
+            _listView.RefreshItems();
+            UpdateConfirmButtonText();
+        }
+
+#if UNITY_EDITOR
+        private void OpenInExplorer()
+        {
+            try
+            {
+                UnityEditor.EditorUtility.RevealInFinder(_currentDirectory);
+            }
+            catch (Exception ex)
+            {
+                Debug.LogError($"Failed to open in Explorer/Finder: {ex.Message}");
+            }
+        }
+#endif
+
+        private static string LoadString(string key, string defaultValue)
+        {
+            if (string.IsNullOrEmpty(key))
+            {
+                return defaultValue;
+            }
+#if UNITY_EDITOR
+            return UnityEditor.EditorPrefs.GetString(key, defaultValue);
+#else
+            return PlayerPrefs.GetString(key, defaultValue);
+#endif
+        }
+
+        private static void PersistString(string key, string value)
+        {
+            if (string.IsNullOrEmpty(key))
+            {
+                return;
+            }
+#if UNITY_EDITOR
+            UnityEditor.EditorPrefs.SetString(key, value ?? string.Empty);
+#else
+            PlayerPrefs.SetString(key, value ?? string.Empty);
+            PlayerPrefs.Save();
+#endif
+        }
+
+        private static void RegisterScope(string scope)
+        {
+            if (string.IsNullOrEmpty(scope))
+            {
+                return;
+            }
+
+            string index = LoadString(PrefKey_ScopesIndex, string.Empty);
+            if (string.IsNullOrEmpty(index))
+            {
+                PersistString(PrefKey_ScopesIndex, scope);
+                return;
+            }
+
+            string[] parts = index.Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
+            for (int i = 0; i < parts.Length; i++)
+            {
+                if (string.Equals(parts[i], scope, StringComparison.Ordinal))
+                {
+                    return;
+                }
+            }
+            PersistString(PrefKey_ScopesIndex, index + ";" + scope);
+        }
+
+        private void UpdateLastUsedNow()
+        {
+            string key = ScopedKey(PrefKey_LastUsed);
+            if (!string.IsNullOrEmpty(key))
+            {
+                PersistString(key, DateTime.UtcNow.Ticks.ToString());
+                RegisterScope(_prefsScope);
+            }
+        }
+
+        /// <summary>
+        /// Removes persisted entries for scopes that have not been used within the provided time window.
+        /// Only affects entries written by this element and maintains a scope index for safe deletion.
+        /// </summary>
+        /// <param name="maxAge">Scopes with last-used older than now - maxAge are cleaned.</param>
+        public static void CleanupStalePersistenceEntries(TimeSpan maxAge)
+        {
+            string index = LoadString(PrefKey_ScopesIndex, string.Empty);
+            if (string.IsNullOrEmpty(index))
+            {
+                return;
+            }
+
+            string[] scopes = index.Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
+            DateTime cutoff = DateTime.UtcNow - maxAge;
+            bool changed = false;
+            using Utils.PooledResource<List<string>> lease = Utils.Buffers<string>.List.Get(
+                out List<string> survivors
+            );
+
+            for (int i = 0; i < scopes.Length; i++)
+            {
+                string scope = scopes[i];
+                string lastUsedStr = LoadString(PrefKey_LastUsed + "." + scope, string.Empty);
+                bool stale = true;
+                if (
+                    !string.IsNullOrEmpty(lastUsedStr) && long.TryParse(lastUsedStr, out long ticks)
+                )
+                {
+                    DateTime last = new(ticks, DateTimeKind.Utc);
+                    stale = last < cutoff;
+                }
+
+                if (stale)
+                {
+#if UNITY_EDITOR
+                    UnityEditor.EditorPrefs.DeleteKey(PrefKey_LastUsed + "." + scope);
+                    UnityEditor.EditorPrefs.DeleteKey(PrefKey_LastSearch + "." + scope);
+                    UnityEditor.EditorPrefs.DeleteKey(PrefKey_LastDir + "." + scope);
+#else
+                    PlayerPrefs.DeleteKey(PrefKey_LastUsed + "." + scope);
+                    PlayerPrefs.DeleteKey(PrefKey_LastSearch + "." + scope);
+                    PlayerPrefs.DeleteKey(PrefKey_LastDir + "." + scope);
+                    PlayerPrefs.Save();
+#endif
+                    changed = true;
+                }
+                else
+                {
+                    survivors.Add(scope);
+                }
+            }
+
+            if (changed)
+            {
+                string rebuilt = string.Join(";", survivors);
+                PersistString(PrefKey_ScopesIndex, rebuilt);
+            }
+        }
+
+        private string ScopedKey(string baseKey)
+        {
+            if (string.IsNullOrEmpty(baseKey) || string.IsNullOrEmpty(_prefsScope))
+            {
+                return null;
+            }
+            return baseKey + "." + _prefsScope;
+        }
+
+        private static string BuildScope(string initialPath, HashSet<string> extensions, string key)
+        {
+            // Only enable persistence when an explicit key is provided by the caller.
+            if (!string.IsNullOrWhiteSpace(key))
+            {
+                return SanitizeKey(key);
+            }
+            return null;
+        }
+
+        private static string SanitizeKey(string key)
+        {
+            char[] buffer = new char[key.Length];
+            int n = 0;
+            for (int i = 0; i < key.Length; i++)
+            {
+                char c = key[i];
+                if (char.IsLetterOrDigit(c) || c == '_' || c == '-' || c == '.')
+                {
+                    buffer[n++] = c;
+                }
+                else if (char.IsWhiteSpace(c) || c == '|' || c == '/' || c == '\\' || c == ',')
+                {
+                    buffer[n++] = '_';
+                }
+            }
+            return new string(buffer, 0, n).Trim('_');
+        }
+    }
+}