web: walk a roll layer by layer, and let the strip drop the branch

docker/frontend/src/engine/rollWalk.ts

@@ -0,0 +1,68 @@
+// Walking a picked folder is the one part of the catalogue that can run for
+// minutes: a roll is dated folders inside dated folders, and a library can hold
+// thousands. The walk goes from the parent down, one layer at a time, so the
+// frames nearest the top are indexed first — and a folder the reader clicks is
+// put in front of the queue, so the branch in front of them is read before the
+// layer it sits in would have come round. A pass covers `DIRS_PER_PASS`
+// directories and then hands the thread back, which is what keeps the page
+// answering while a scan runs.
+//
+// Pure on purpose: it only reads `values()` off a directory handle, so a check
+// can walk a stand-in tree without a browser (scripts/roll-walk-check.mjs).
+
+export interface WalkFile {
+  handle: FileSystemFileHandle;
+  rel: string;
+}
+
+interface Pending {
+  dir: FileSystemDirectoryHandle;
+  rel: string;
+}
+
+// Directories one pass walks before it yields: small enough that a click is
+// answered within a second, large enough that a folder of a few hundred is one
+// pass rather than a hundred.
+export const DIRS_PER_PASS = 200;
+
+// The folder the reader clicked goes first. `rel` is how the queue spells a
+// folder — '' for the picked one, `2026/04/` under it — and a folder already
+// walked is simply not in the queue, which is the no-op case.
+//
+// ponytail: only a folder the queue already holds can jump, which is every
+// folder the tree can draw, because a row exists per indexed frame. A tree that
+// listed folders before their first frame would need `getDirectoryHandle` to
+// descend to the clicked path here.
+export function jumpQueue(pending: Pending[], rel: string | null): void {
+  if (rel === null) return;
+  const at = pending.findIndex((p) => p.rel === rel);
+  if (at > 0) pending.unshift(pending.splice(at, 1)[0]);
+}
+
+// One pass over the queue. The queue is the walk's own state: what is behind has
+// been walked, what is ahead is in the order it was found — parents before
+// children, shallower layers before deeper ones. Returns true when nothing is
+// left to walk.
+export async function walkPass(
+  pending: Pending[],
+  out: WalkFile[],
+  keep: (name: string) => boolean,
+  jump: () => string | null
+): Promise<boolean> {
+  for (let i = 0; i < DIRS_PER_PASS && pending.length; i++) {
+    jumpQueue(pending, jump());
+    const here = pending.shift()!;
+    try {
+      for await (const entry of here.dir.values()) {
+        // Names beginning with `.` or `@` are skipped — that is `.thumbnails`,
+        // `.git`, and the `@eaDir` a Synology writes beside every frame.
+        if (/^[.@]/.test(entry.name)) continue;
+        if (entry.kind === 'directory') pending.push({ dir: entry as FileSystemDirectoryHandle, rel: `${here.rel}${entry.name}/` });
+        else if (keep(entry.name)) out.push({ handle: entry as FileSystemFileHandle, rel: `${here.rel}${entry.name}` });
+      }
+    } catch {
+      // A subfolder that will not open is skipped; the rest of the roll stands.
+    }
+  }
+  return pending.length === 0;
+}