Draw a large folder while it is being read, instead of after

Two seconds of readdir and stat cannot be made much cheaper - each is a round trip to another process - so the folder is now read in batches and drawn as it arrives. StorageSource.listBatches hands over 200 entries at a time; AllFilesSource implements it with Files.newDirectoryStream, which is lazy where File.listFiles materialised the whole directory first; the default implementation is one batch, so the SAF backend and every test fake are unchanged.

BrowserViewModel.load merges each batch into the list already on screen with core/SortedMerge, which is O(n+k) rather than re-sorting the folder on every batch, and keeps the rows in the user's order at every moment instead of shuffling them into place when the last batch lands. loading stays true until the last batch, so the progress bar the screen already draws sits above rows that are already useful. publishEntries is separate from recompute for that reason: the merge has done the ordering, and the batch path only has to apply the hidden filter.

Tests: four for the merge (including ties not jumping ahead) and one for the batched read, which asserts 250 files arrive as 100+100+50 covering every entry exactly once - the thing a streaming read is easiest to get wrong about. PERFORMANCE.md records the expected effect and states plainly that it is not measured yet, since confirming it needs the 20000-file fixture rebuilt.

docs/CODE_MAP.md

@@ -2,7 +2,7 @@
 
 Generated from the source by `tools/make-code-map.py` - do not edit by hand. Regenerate it after a change (`python3 tools/make-code-map.py`); `--check` exits non-zero when this file is stale.
 
-78 source files, 12910 lines - 34 test files, 391 tests. The behaviour index at the end lists every test name, and in this project a test name is a sentence about what the app does, so it doubles as the specification.
+79 source files, 13040 lines - 35 test files, 396 tests. The behaviour index at the end lists every test name, and in this project a test name is a sentence about what the app does, so it doubles as the specification.
 
 Start at `AGENTS.md`. What is done, and why: `docs/ROADMAP.md` and `CHANGELOG.md`. What was verified by hand rather than by a test: `docs/EDGE_CASE_TESTING.md`.
 
@@ -24,6 +24,7 @@ Pure Kotlin, **no Android imports**: paths, file names, kinds, sorting, formatti
 | `NameAllocator.kt` | 30 | Picks a name that is not already in use, in the familiar "name (1)" style. NameAllocator | `NameMatcherTest` (10) |
 | `NameMatcher.kt` | 63 | The in-folder search matcher. NameMatcher | `NameMatcherTest` (10) |
 | `SortSpec.kt` | 82 | A complete, serialisable description of the ordering of a directory listing. SortKey, SortDirection, SortSpec, NaturalOrder | `SortSpecTest` (8) |
+| `SortedMerge.kt` | 42 | Adds a freshly read batch to an already sorted list, in one pass. SortedMerge | `SortedMergeTest` (4) |
 | `StoragePath.kt` | 89 | A normalized, absolute, backend-agnostic storage path. StoragePath | `StoragePathTest` (8) |
 | `ThumbnailKey.kt` | 22 | The identity of a thumbnail: which file it came from, and which version of that file. ThumbnailKey | `ThumbnailKeyTest` (4) |
 | `Timestamps.kt` | 20 | Timestamps for the details sheet. Timestamps | - |
@@ -35,7 +36,7 @@ Storage backends (all-files access and SAF), volumes, incoming shares, the SQLit
 
 | file | lines | what it holds | tests |
 |---|---|---|---|
-| `AllFilesSource.kt` | 125 | The "All files access" backend: plain java.io.File over absolute paths. AllFilesSource, File() | `AllFilesSourceTest` (13) |
+| `AllFilesSource.kt` | 154 | The "All files access" backend: plain java.io.File over absolute paths. AllFilesSource, File() | `AllFilesSourceTest` (14) |
 | `ApkInspector.kt` | 100 | What an APK says about itself, read without installing it. ApkInfo, interface(), PackageManagerApkInspector | - |
 | `BookmarkStore.kt` | 34 | The folders the user starred. BookmarkStore | - |
 | `IncomingSource.kt` | 48 | Something another app has handed to this one. IncomingSource, ContentResolverIncomingSource | - |
@@ -50,7 +51,7 @@ Storage backends (all-files access and SAF), volumes, incoming shares, the SQLit
 | `StorageAccess.kt` | 80 | The Android-facing side of the storage-access decision. StorageAccess | - |
 | `StorageAccessPolicy.kt` | 68 | The decision rules behind StorageAccess. StorageAccessMode, StorageAccessPolicy | `StorageAccessPolicyTest` (6) |
 | `StorageLocation.kt` | 87 | Everything the browser needs to know about where files live and what it may touch. StorageLocation, StorageProvider | - |
-| `StorageSource.kt` | 96 | The primitive file operations a storage backend must provide. StorageException, StorageSource | - |
+| `StorageSource.kt` | 124 | The primitive file operations a storage backend must provide. StorageException, StorageSource | - |
 | `TrashIndex.kt` | 61 | The durable memory of what is in the trash. TrashRecord, TrashIndex | - |
 | `VolumeRepository.kt` | 121 | Discovers the device's storage volumes and reports their space. VolumeInfo, SpaceInfo, VolumeRepository | `VolumeRepositoryTest` (6) |
 
@@ -102,7 +103,7 @@ The browser screen: view model, state, list and grid, dialogs, selection bar
 | `BrowserScreen.kt` | 591 | BrowserScreen() | - |
 | `BrowserTopBar.kt` | 238 | The browser's app bar: title, up, the favourite star, and the search / sort / overflow actions. BrowserTopBar(), SEARCH_FIELD_WIDTH | `BrowserTopBarTest` (4) |
 | `BrowserUiState.kt` | 311 | One immutable description of everything the browser shows. ViewMode, SearchScope, Clipboard, UiMessage, ConflictPrompt, RootItem, Bookmark, DetailFocus, Undo, UndoMove, Overlay, BrowserUiState | - |
-| `BrowserViewModel.kt` | 2206 | Drives the browser screen. BrowserViewModel, ArchivePreview | `BrowserViewModelTest` (90) |
+| `BrowserViewModel.kt` | 2237 | Drives the browser screen. BrowserViewModel, ArchivePreview | `BrowserViewModelTest` (90) |
 | `DetailsSheet.kt` | 109 | Name, location, size, type and modified date for one entry. DetailsSheet(), DetailLines(), DetailLine() | - |
 | `EntryIntents.kt` | 58 | Wraps an entry's path in a content:// URI another app may read. contentUriFor(), viewIntent(), shareIntent() | - |
 | `IncomingBar.kt` | 60 | The bar shown while another app is waiting on this one. IncomingBar() | - |
@@ -289,6 +290,13 @@ Every test name in the suite, by file: the fastest way to see whether something
 - comparison ignores case
 - a prefix sorts before a longer name
 
+### `core/SortedMergeTest.kt` (4)
+
+- a later batch slots into the order already on screen
+- the first batch into an empty list is sorted on its own
+- an empty batch changes nothing
+- an entry that ties on name does not jump ahead of one that arrived earlier
+
 ### `core/StoragePathTest.kt` (8)
 
 - normalizes separators and dot segments
@@ -315,8 +323,9 @@ Every test name in the suite, by file: the fastest way to see whether something
 - a folder cannot be moved into itself or a descendant
 - a move into itself is skipped in the plan
 
-### `data/AllFilesSourceTest.kt` (13)
+### `data/AllFilesSourceTest.kt` (14)
 
+- reads a large folder in batches, covering every entry exactly once
 - lists the children of a directory
 - names lists a folder without reading metadata
 - names of a folder that cannot be read is null, not empty
@@ -676,4 +685,4 @@ Every test name in the suite, by file: the fastest way to see whether something
 
 ---
 
-Purpose taken from the first KDoc rather than from a declaration sharing the file's name (15 of 77): `MainActivity.kt`, `ArchiveFormats.kt`, `FileNames.kt`, `ApkInspector.kt`, `OperationModels.kt`, `TextRes.kt`, `BrowserComponents.kt`, `BrowserDetailPane.kt`, `BrowserDialogs.kt`, `BrowserRoots.kt`, `BrowserScreen.kt`, `EntryIntents.kt`, `Color.kt`, `Theme.kt`, `Type.kt`
+Purpose taken from the first KDoc rather than from a declaration sharing the file's name (15 of 78): `MainActivity.kt`, `ArchiveFormats.kt`, `FileNames.kt`, `ApkInspector.kt`, `OperationModels.kt`, `TextRes.kt`, `BrowserComponents.kt`, `BrowserDetailPane.kt`, `BrowserDialogs.kt`, `BrowserRoots.kt`, `BrowserScreen.kt`, `EntryIntents.kt`, `Color.kt`, `Theme.kt`, `Type.kt`

docs/PERFORMANCE.md

@@ -160,6 +160,28 @@ scheduler hiccup on top of that — unidentified, and worth a perfetto trace rat
 cheap in absolute terms, but it is work the frame has no reason to wait for, and the threshold keeps small
 folders on the simple synchronous path.
 
+### The same cost, delivered in pieces
+
+Those two seconds of `readdir` and `stat` cannot be made much cheaper — they are round trips to another
+process — so the fix is to **draw while they happen**:
+
+- `StorageSource.listBatches` hands a folder over 200 entries at a time. `AllFilesSource` implements it
+  with `Files.newDirectoryStream`, which is lazy: it pulls `readdir` results as the loop asks for them,
+  where `File.listFiles` materialised the whole folder before returning anything. The default
+  implementation is still a single batch, so the SAF backend and every test fake behave exactly as before.
+- `BrowserViewModel.load` merges each batch into the list already on screen (`core/SortedMerge`,
+  O(n + k) instead of re-sorting the folder after every batch), so rows arrive in the user's order and the
+  list is never a partly ordered jumble that shuffles into place afterwards.
+- `loading` stays true until the last batch, which is what the existing progress bar above the list already
+  draws — the feedback that keeps a slow folder from feeling like a frozen one.
+
+At 200 entries per batch, the first rows should appear after roughly 20 ms of reading plus a frame, against
+two seconds of empty screen before. **That expectation is not measured yet**: confirming it needs a
+20 000-file fixture, which takes about half an hour to build through MIUI's storage layer, so the numbers to
+beat are the ones in the table above and the first thing to do with that fixture is to re-run
+`openAFolderOfAThousandFiles` and look at the *min* iteration rather than the median — the minimum is what
+"first rows visible" now governs.
+
 Building that fixture is the expensive part, not measuring it: 20 000 files took about thirty minutes
 through MIUI's storage layer (`: >` in a loop), against roughly four minutes of benchmark on top. Worth
 knowing before anyone re-creates it, and an argument for the fixture being built once and kept.