@uniqbit/mate-core 0.17.0-canary.9 → 0.17.1

package/src/cli/commands/studio/vault.ts

@@ -2,10 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import fs, { type Dirent, type FSWatcher, type Stats } from "node:fs";
 import * as fsp from "node:fs/promises";
 import path from "node:path";
-import { execFile as execFileCallback } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFile = promisify(execFileCallback);
+import { spawn } from "node:child_process";
 
 export interface VaultTreeNode {
   name: string;
@@ -68,9 +65,30 @@ export interface VaultWatcher {
   close(): void;
 }
 
-export interface VaultDeps {
+export interface VaultGitResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Rejects only when Git cannot be started; a non-zero exit resolves with its code. */
+export type VaultGitRunner = (args: string[], input?: string) => Promise<VaultGitResult>;
+
+export interface VaultListingFs {
+  realpath(target: string): Promise<string>;
+  stat(target: string): Promise<Stats>;
+  readdir(target: string): Promise<Dirent[]>;
+}
+
+export interface VaultListingDeps {
+  git?: VaultGitRunner;
+  fs?: Partial<VaultListingFs>;
+}
+
+export interface VaultDeps extends VaultListingDeps {
+  /** Called once per directory; the watch is not recursive. */
   watch?: (
-    root: string,
+    directory: string,
     listener: (event: string, filename: string | Buffer | null) => void,
   ) => VaultWatcher;
   beforeWrite?: (absolutePath: string) => Promise<void> | void;
@@ -147,16 +165,57 @@ export async function resolveVaultPath(
   return { root, absolute, relative: path.relative(root, absolute) || requestedPath };
 }
 
-async function ignored(root: string, relative: string): Promise<boolean> {
+function runGit(args: string[], input?: string): Promise<VaultGitResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, { stdio: ["pipe", "pipe", "pipe"] });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+    child.stdin.on("error", () => {});
+    child.on("error", reject);
+    child.on("close", (code) =>
+      resolve({
+        code: code ?? 1,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+      }),
+    );
+    child.stdin.end(input ?? "");
+  });
+}
+
+const defaultListingFs: VaultListingFs = {
+  realpath: (target) => fsp.realpath(target),
+  stat: (target) => fsp.stat(target),
+  readdir: (target) => fsp.readdir(target, { withFileTypes: true }),
+};
+
+async function ignored(git: VaultGitRunner, root: string, relative: string): Promise<boolean> {
+  try {
+    const result = await git(["-C", root, "check-ignore", "--no-index", "--quiet", "--", relative]);
+    return result.code === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function containedFile(
+  vaultFs: VaultListingFs,
+  root: string,
+  relative: string,
+): Promise<boolean> {
   try {
-    await execFile("git", ["-C", root, "check-ignore", "--no-index", "--quiet", "--", relative]);
-    return true;
+    const resolved = await vaultFs.realpath(path.join(root, relative));
+    return inside(root, resolved) && (await vaultFs.stat(resolved)).isFile();
   } catch {
     return false;
   }
 }
 
-async function collectFiles(
+/** Only used outside a Git checkout, where nothing counts as ignored. */
+async function walkFiles(
+  vaultFs: VaultListingFs,
   root: string,
   current: string,
   relativeDir: string,
@@ -164,34 +223,84 @@ async function collectFiles(
 ): Promise<void> {
   let entries: Dirent[];
   try {
-    entries = await fsp.readdir(current, { withFileTypes: true });
+    entries = await vaultFs.readdir(current);
   } catch {
     return;
   }
-  entries.sort((a, b) => a.name.localeCompare(b.name));
   for (const entry of entries) {
     if (entry.name === ".git") continue;
     const relative = path.join(relativeDir, entry.name);
-    if (await ignored(root, relative)) continue;
-    const absolute = path.join(current, entry.name);
     let resolved: string;
-    try {
-      resolved = await fsp.realpath(absolute);
-      if (!inside(root, resolved)) continue;
-    } catch {
-      continue;
-    }
     let stats: Stats;
     try {
-      stats = await fsp.stat(resolved);
+      resolved = await vaultFs.realpath(path.join(current, entry.name));
+      if (!inside(root, resolved)) continue;
+      stats = await vaultFs.stat(resolved);
     } catch {
       continue;
     }
-    if (stats.isDirectory()) await collectFiles(root, resolved, relative, output);
+    if (stats.isDirectory()) await walkFiles(vaultFs, root, resolved, relative, output);
     else if (stats.isFile() && isMarkdown(relative)) output.push(relative);
   }
 }
 
+function notACheckout(error: unknown, result?: VaultGitResult): boolean {
+  if (error) return (error as NodeJS.ErrnoException).code === "ENOENT";
+  return result !== undefined && /not a git repository/i.test(result.stderr);
+}
+
+/**
+ * Two Git processes per listing, whatever the repository size. `--no-index`
+ * keeps tracked files that match an ignore pattern hidden.
+ */
+async function listMarkdownFiles(root: string, deps: VaultListingDeps): Promise<string[]> {
+  const git = deps.git ?? runGit;
+  const vaultFs = { ...defaultListingFs, ...deps.fs };
+  let listed: VaultGitResult;
+  try {
+    listed = await git([
+      "-C",
+      root,
+      "ls-files",
+      "-z",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+    ]);
+  } catch (error) {
+    if (!notACheckout(error)) throw error;
+    const files: string[] = [];
+    await walkFiles(vaultFs, root, root, "", files);
+    return files;
+  }
+  if (listed.code !== 0) {
+    if (notACheckout(null, listed)) {
+      const files: string[] = [];
+      await walkFiles(vaultFs, root, root, "", files);
+      return files;
+    }
+    throw new Error(`git ls-files failed: ${listed.stderr.trim() || `exit ${listed.code}`}`);
+  }
+
+  const candidates = [...new Set(listed.stdout.split("\0").filter(Boolean))].filter(isMarkdown);
+  if (candidates.length === 0) return [];
+  const checked = await git(
+    ["-C", root, "check-ignore", "--no-index", "-z", "--stdin"],
+    `${candidates.join("\0")}\0`,
+  );
+  if (checked.code !== 0 && checked.code !== 1)
+    throw new Error(`git check-ignore failed: ${checked.stderr.trim() || `exit ${checked.code}`}`);
+  const ignoredPaths = new Set(checked.stdout.split("\0").filter(Boolean));
+
+  const relatives = candidates.flatMap((candidate) =>
+    ignoredPaths.has(candidate) ? [] : [path.join(...candidate.split("/"))],
+  );
+  const kept = await Promise.all(
+    relatives.map((relative) => containedFile(vaultFs, root, relative)),
+  );
+  return relatives.filter((_relative, index) => kept[index]);
+}
+
 function asTree(paths: string[]): VaultTreeNode[] {
   const roots: VaultTreeNode[] = [];
   for (const filePath of paths.sort((a, b) => a.localeCompare(b))) {
@@ -217,11 +326,12 @@ function asTree(paths: string[]): VaultTreeNode[] {
 }
 
 /** Collects every non-ignored markdown file under a companion root. */
-export async function collectMarkdownTree(companionRoot: string): Promise<VaultTreeNode[]> {
+export async function collectMarkdownTree(
+  companionRoot: string,
+  deps: VaultListingDeps = {},
+): Promise<VaultTreeNode[]> {
   const root = await fsp.realpath(companionRoot);
-  const files: string[] = [];
-  await collectFiles(root, root, "", files);
-  return asTree(files);
+  return asTree(await listMarkdownFiles(root, deps));
 }
 
 /** The token is opaque to callers and changes whenever the bytes change. */
@@ -229,25 +339,35 @@ export function versionToken(content: string): string {
   return createHash("sha256").update(content).digest("hex");
 }
 
-export const createVersionToken = versionToken;
-
-export async function readVaultFile(
-  companionRoot: string,
-  requestedPath: string,
-): Promise<VaultFile> {
+async function readVaultFile(companionRoot: string, requestedPath: string): Promise<VaultFile> {
   const resolved = await resolveVaultPath(companionRoot, requestedPath);
   const content = await fsp.readFile(resolved.absolute, "utf8");
   return { path: resolved.relative, content, token: versionToken(content) };
 }
 
 function defaultWatcher(
-  root: string,
+  directory: string,
   listener: (event: string, filename: string | Buffer | null) => void,
 ): VaultWatcher {
-  const watcher: FSWatcher = fs.watch(root, { recursive: true }, listener);
+  const watcher: FSWatcher = fs.watch(directory, listener);
+  /** A removed directory errors its watcher; the next listing drops it. */
+  watcher.on("error", () => watcher.close());
   return { close: () => watcher.close() };
 }
 
+/** The root, every directory holding a listed file, and their ancestors. */
+function watchedDirectories(root: string, files: string[]): Set<string> {
+  const directories = new Set([root]);
+  for (const file of files) {
+    let current = path.dirname(path.join(root, file));
+    while (current !== root && !directories.has(current)) {
+      directories.add(current);
+      current = path.dirname(current);
+    }
+  }
+  return directories;
+}
+
 interface SaveRecord {
   path: string;
   content: string;
@@ -264,6 +384,8 @@ interface Subscriber {
 
 export interface VaultManager {
   tree(companionRoot: string, refresh?: boolean): Promise<VaultTreeResult>;
+  /** The cached tree, or `null` after starting (or joining) a listing in the background. */
+  prefetch(companionRoot: string, refresh?: boolean): Promise<VaultTreeResult | null>;
   open(companionRoot: string, requestedPath: string): Promise<VaultFile>;
   save(
     companionRoot: string,
@@ -282,12 +404,19 @@ export interface VaultManager {
   getRecovery(companionRoot: string, requestedPath: string): VaultWatchEvent | null;
 }
 
-/** Owns one tree cache and one recursive watcher per selected companion process. */
+/** Owns one tree cache and one set of per-directory watchers per selected companion process. */
 export function createVaultManager(deps: VaultDeps = {}): VaultManager {
   const watch = deps.watch ?? defaultWatcher;
+  const git = deps.git ?? runGit;
   const trees = new Map<string, VaultTreeNode[]>();
+  const generations = new Map<string, number>();
+  const listings = new Map<string, Promise<VaultTreeNode[]>>();
+  const listed = new Map<string, string[]>();
   const warnings = new Map<string, string | null>();
-  const watchers = new Map<string, VaultWatcher>();
+  const watchers = new Map<string, Map<string, VaultWatcher>>();
+  const reconciles = new Map<string, Set<string>>();
+  /** Directories created since the last listing; they hold no listed file yet. */
+  const adopted = new Map<string, Set<string>>();
   let activeRoot: string | null = null;
   const subscribers = new Map<string, Set<Subscriber>>();
   const pendingEvents = new Map<string, ReturnType<typeof setTimeout>>();
@@ -299,6 +428,7 @@ export function createVaultManager(deps: VaultDeps = {}): VaultManager {
 
   const invalidate = (root: string) => {
     trees.delete(root);
+    generations.set(root, (generations.get(root) ?? 0) + 1);
   };
 
   const notify = async (
@@ -368,47 +498,149 @@ export function createVaultManager(deps: VaultDeps = {}): VaultManager {
     }
   };
 
+  const closeWatchers = (root: string) => {
+    for (const watcher of watchers.get(root)?.values() ?? []) watcher.close();
+    watchers.delete(root);
+    reconciles.delete(root);
+    adopted.delete(root);
+  };
+
+  const unavailable = (root: string, error: unknown) => {
+    closeWatchers(root);
+    warnings.set(
+      root,
+      `Live updates are unavailable: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  };
+
+  const onDirectoryEvent = (root: string, directory: string, filename: string | Buffer | null) => {
+    if (!filename) {
+      invalidate(root);
+      return;
+    }
+    const absolute = path.resolve(directory, String(filename));
+    const relative = path.relative(root, absolute);
+    if (!relative || relative.startsWith("..") || relative.split(path.sep).includes(".git")) return;
+    if (!isMarkdown(relative)) {
+      if (watchers.get(root)?.has(absolute)) {
+        invalidate(root);
+        return;
+      }
+      void adoptDirectory(root, absolute).catch(() => {});
+      return;
+    }
+    const observed = observeNow(root, relative);
+    const saveWasActive = recentSaves.get(`${root}\0${relative}`)?.windowOpen === true;
+    void ignored(git, root, relative).then((isIgnored) => {
+      if (isIgnored) return;
+      invalidate(root);
+      void notify(root, relative, observed, saveWasActive);
+    });
+  };
+
+  const watchDirectory = (root: string, directory: string) =>
+    watch(directory, (_event, filename) => onDirectoryEvent(root, directory, filename));
+
+  /** Watches a new directory and its subdirectories at once, so files written into them are seen. */
+  const adoptDirectory = async (root: string, absolute: string): Promise<void> => {
+    if (!(await fsp.stat(absolute)).isDirectory()) return;
+    const relative = path.relative(root, absolute);
+    if (await ignored(git, root, `${relative}${path.sep}`)) return;
+    invalidate(root);
+    const current = watchers.get(root);
+    if (!current || activeRoot !== root || current.has(absolute)) return;
+    try {
+      current.set(absolute, watchDirectory(root, absolute));
+    } catch (error) {
+      unavailable(root, error);
+      return;
+    }
+    const set = adopted.get(root) ?? new Set<string>();
+    set.add(absolute);
+    adopted.set(root, set);
+    const entries = await fsp.readdir(absolute, { withFileTypes: true });
+    await Promise.all(
+      entries.flatMap((entry) =>
+        entry.isDirectory() && entry.name !== ".git"
+          ? [adoptDirectory(root, path.join(absolute, entry.name))]
+          : [],
+      ),
+    );
+  };
+
+  /** Synchronous for the root only, so a request learns at once whether it is watched. */
   const startWatching = (root: string) => {
     if (activeRoot && activeRoot !== root) {
-      watchers.get(activeRoot)?.close();
-      watchers.delete(activeRoot);
+      closeWatchers(activeRoot);
       warnings.delete(root);
     }
     activeRoot = root;
     if (watchers.has(root) || warnings.has(root)) return;
     try {
-      watchers.set(
-        root,
-        watch(root, (_event, filename) => {
-          if (!filename) return;
-          const value = String(filename);
-          const relative = path.relative(
-            root,
-            path.isAbsolute(value) ? value : path.resolve(root, value),
-          );
-          if (
-            !relative ||
-            relative.startsWith("..") ||
-            !isMarkdown(relative) ||
-            relative.split(path.sep).includes(".git")
-          )
-            return;
-          const observed = observeNow(root, relative);
-          const saveWasActive = recentSaves.get(`${root}\0${relative}`)?.windowOpen === true;
-          void ignored(root, relative).then((isIgnored) => {
-            if (isIgnored) return;
-            invalidate(root);
-            void notify(root, relative, observed, saveWasActive);
-          });
-        }),
-      );
+      watchers.set(root, new Map([[root, watchDirectory(root, root)]]));
       warnings.set(root, null);
     } catch (error) {
-      warnings.set(
-        root,
-        `Live updates are unavailable: ${error instanceof Error ? error.message : String(error)}`,
-      );
+      unavailable(root, error);
+      return;
+    }
+    const files = listed.get(root);
+    if (files) scheduleReconcile(root, files);
+  };
+
+  const reconcile = (root: string) => {
+    const desired = reconciles.get(root);
+    reconciles.delete(root);
+    const current = watchers.get(root);
+    if (!desired || !current || activeRoot !== root) return;
+    const kept = adopted.get(root);
+    for (const [directory, watcher] of current) {
+      if (desired.has(directory)) {
+        kept?.delete(directory);
+        continue;
+      }
+      if (kept?.has(directory) && fs.existsSync(directory)) continue;
+      kept?.delete(directory);
+      watcher.close();
+      current.delete(directory);
     }
+    for (const directory of desired) {
+      if (current.has(directory)) continue;
+      try {
+        current.set(directory, watchDirectory(root, directory));
+      } catch (error) {
+        unavailable(root, error);
+        return;
+      }
+    }
+  };
+
+  const scheduleReconcile = (root: string, files: string[]) => {
+    if (!watchers.has(root)) return;
+    const pending = reconciles.has(root);
+    reconciles.set(root, watchedDirectories(root, files));
+    if (!pending) setImmediate(() => reconcile(root));
+  };
+
+  /** A change seen while listing leaves the cache empty, so the next request lists again. */
+  const listTree = (root: string): Promise<VaultTreeNode[]> => {
+    const inFlight = listings.get(root);
+    if (inFlight) return inFlight;
+    const generation = generations.get(root) ?? 0;
+    const listing = (async () => {
+      try {
+        const files = await listMarkdownFiles(root, deps);
+        listed.set(root, files);
+        startWatching(root);
+        scheduleReconcile(root, files);
+        const tree = asTree(files);
+        if ((generations.get(root) ?? 0) === generation) trees.set(root, tree);
+        return tree;
+      } finally {
+        listings.delete(root);
+      }
+    })();
+    listings.set(root, listing);
+    return listing;
   };
 
   const readConflict = async (resolved: VaultPath, reason: string): Promise<VaultConflict> => {
@@ -527,14 +759,24 @@ export function createVaultManager(deps: VaultDeps = {}): VaultManager {
   return {
     async tree(companionRoot, refresh = false) {
       const root = await rootKey(companionRoot);
+      const tree = !refresh && trees.get(root);
+      const result = tree || (await listTree(root));
       startWatching(root);
-      if (refresh || !trees.has(root)) trees.set(root, await collectMarkdownTree(root));
       return {
-        tree: trees.get(root) ?? [],
+        tree: result,
         watching: watchers.has(root),
         warning: warnings.get(root) ?? null,
       };
     },
+    async prefetch(companionRoot, refresh = false) {
+      const root = await rootKey(companionRoot);
+      if (refresh) invalidate(root);
+      startWatching(root);
+      const tree = trees.get(root);
+      if (tree) return { tree, watching: watchers.has(root), warning: warnings.get(root) ?? null };
+      void listTree(root).catch(() => {});
+      return null;
+    },
     async open(companionRoot, requestedPath) {
       const root = await rootKey(companionRoot);
       startWatching(root);
@@ -548,9 +790,13 @@ export function createVaultManager(deps: VaultDeps = {}): VaultManager {
       const set = subscribers.get(key) ?? new Set<Subscriber>();
       set.add(subscriber);
       subscribers.set(key, set);
+      const watchListed = (root: string) => {
+        startWatching(root);
+        if (!trees.has(root)) void listTree(root).catch(() => {});
+      };
       void rootKey(companionRoot).then((root) => {
         if (!active || root === path.resolve(companionRoot)) {
-          if (active) startWatching(root);
+          if (active) watchListed(root);
           return;
         }
         const oldSet = subscribers.get(key);
@@ -560,7 +806,7 @@ export function createVaultManager(deps: VaultDeps = {}): VaultManager {
         const newSet = subscribers.get(key) ?? new Set<Subscriber>();
         newSet.add(subscriber);
         subscribers.set(key, newSet);
-        startWatching(root);
+        watchListed(root);
       });
       return () => {
         active = false;
@@ -575,16 +821,15 @@ export function createVaultManager(deps: VaultDeps = {}): VaultManager {
     },
     deactivate() {
       if (activeRoot) {
-        watchers.get(activeRoot)?.close();
-        watchers.delete(activeRoot);
+        closeWatchers(activeRoot);
         warnings.delete(activeRoot);
       }
       activeRoot = null;
       subscribers.clear();
     },
     stop() {
-      for (const watcher of watchers.values()) watcher.close();
-      watchers.clear();
+      for (const root of watchers.keys()) closeWatchers(root);
+      reconciles.clear();
       activeRoot = null;
       for (const timer of pendingEvents.values()) clearTimeout(timer);
       for (const record of recentSaves.values()) clearTimeout(record.expires);

package/src/cli/commands/studio/views/client.ts

@@ -2,6 +2,7 @@ import { COMPANION_DIGEST_PATTERN, COMPANION_PARAM } from "../selection";
 
 export const THEME_STORAGE_KEY = "mate-studio-theme";
 export const COMPANION_STORAGE_KEY = "mate-studio-companion";
+export const VAULT_TREE_STORAGE_KEY = "mate-studio-vault-tree";
 
 /**
  * Runs in `<head>` before first paint. A server-rendered document arrives with
@@ -20,6 +21,9 @@ export const STUDIO_PREPAINT_SCRIPT = `(function () {
     if (chosen === "dark" || chosen === "light") {
       document.documentElement.setAttribute("data-theme", chosen);
     }
+    if (localStorage.getItem(${JSON.stringify(VAULT_TREE_STORAGE_KEY)}) === "hidden") {
+      document.documentElement.setAttribute("data-vault-tree", "hidden");
+    }
   } catch (error) {
     /* a blocked web store only costs the preference, never the page */
   }
@@ -38,9 +42,9 @@ export const STUDIO_PREPAINT_SCRIPT = `(function () {
 
 /**
  * The only browser code Studio ships: cycling the appearance, remembering the
- * companion on screen, switching workflow schema tabs, and copying a prompt.
- * Each needs an API the server does not have, and nothing else here renders,
- * fetches, or holds state.
+ * companion on screen, switching workflow schema tabs, copying a prompt, the
+ * vault's editor, filter and tree toggle, and swapping in a deferred vault tree.
+ * Each needs an API the server does not have; all markup comes from the server.
  */
 export const STUDIO_CLIENT_SCRIPT = `(function () {
   var THEME_KEY = ${JSON.stringify(THEME_STORAGE_KEY)};
@@ -248,8 +252,8 @@ export const STUDIO_CLIENT_SCRIPT = `(function () {
     if (submitter && submitter.name && submitter.value) target.searchParams.set(submitter.name, submitter.value);
     return target.toString();
   }
-  function wireNavigation() {
-    document.querySelectorAll('form[method="get"]').forEach(function (form) {
+  function wireNavigation(scope) {
+    (scope || document).querySelectorAll('form[method="get"]').forEach(function (form) {
       form.addEventListener("submit", function (event) {
         event.preventDefault();
         navigate(navigationUrl(form, event.submitter));
@@ -299,10 +303,9 @@ export const STUDIO_CLIENT_SCRIPT = `(function () {
     if (recover) recover.addEventListener("click", function () {
       acceptIncoming({ content: recover.getAttribute("data-vault-content") || "", token: recover.getAttribute("data-vault-token") || "" });
     });
-    var companion = document.querySelector("[data-companion]");
-    var path = node.getAttribute("data-vault-path");
-    if (companion && path && typeof EventSource !== "undefined") {
-      var events = new EventSource("/api/vault/events?companion=" + encodeURIComponent(companion.getAttribute("data-companion") || "") + "&path=" + encodeURIComponent(path));
+    var eventsUrl = node.getAttribute("data-vault-events");
+    if (eventsUrl && typeof EventSource !== "undefined") {
+      var events = new EventSource(eventsUrl);
       events.onmessage = function (message) {
         var event;
         try { event = JSON.parse(message.data); } catch (error) { return; }
@@ -332,6 +335,84 @@ export const STUDIO_CLIENT_SCRIPT = `(function () {
       event.preventDefault();
       event.returnValue = "";
     });
+  function filterTree(query) {
+    var needle = query.trim().toLowerCase();
+    document.querySelectorAll("[data-vault-entry]").forEach(function (entry) {
+      entry.hidden = !!needle && (entry.getAttribute("data-vault-entry") || "").toLowerCase().indexOf(needle) === -1;
+    });
+    document.querySelectorAll("[data-vault-dir]").forEach(function (folder) {
+      if (!needle) {
+        folder.hidden = false;
+        folder.open = folder.hasAttribute("data-vault-expanded");
+        return;
+      }
+      var match = folder.querySelector("[data-vault-entry]:not([hidden])");
+      folder.hidden = !match;
+      if (match) folder.open = true;
+    });
+  }
+  function showTree(shown) {
+    var root = document.documentElement;
+    if (shown) root.removeAttribute("data-vault-tree");
+    else root.setAttribute("data-vault-tree", "hidden");
+    var toggle = document.getElementById("vault-tree-toggle");
+    if (toggle) {
+      toggle.textContent = shown ? "Hide files" : "Show files";
+      toggle.setAttribute("aria-expanded", shown ? "true" : "false");
+    }
+    try {
+      localStorage.setItem(${JSON.stringify(VAULT_TREE_STORAGE_KEY)}, shown ? "shown" : "hidden");
+    } catch (error) {
+      /* a blocked web store only costs the preference, never the page */
+    }
+  }
+  /** Moves server-rendered parts into place; builds no markup of its own. */
+  function swapVaultSlots(markup) {
+    var parsed = new DOMParser().parseFromString(markup, "text/html");
+    parsed.querySelectorAll("[data-vault-slot]").forEach(function (slot) {
+      var target = document.querySelector('[data-vault-slot="' + slot.getAttribute("data-vault-slot") + '"]');
+      if (!target) return;
+      var node = document.importNode(slot, true);
+      target.replaceWith(node);
+      wireNavigation(node);
+    });
+    var filter = document.getElementById("vault-filter");
+    if (filter && filter.value) filterTree(filter.value);
+  }
+  function failVaultSlots(message) {
+    document.querySelectorAll("[data-vault-slot][aria-busy]").forEach(function (slot) {
+      slot.removeAttribute("aria-busy");
+      slot.textContent = message;
+    });
+  }
+  function wireVaultBrowser() {
+    var layout = document.querySelector("[data-vault-layout]");
+    if (!layout) return;
+    var filter = document.getElementById("vault-filter");
+    if (filter) {
+      filter.hidden = false;
+      filter.addEventListener("input", function () { filterTree(filter.value); });
+    }
+    var toggle = document.getElementById("vault-tree-toggle");
+    if (toggle) {
+      toggle.hidden = false;
+      var hidden = document.documentElement.getAttribute("data-vault-tree") === "hidden";
+      toggle.textContent = hidden ? "Show files" : "Hide files";
+      toggle.setAttribute("aria-expanded", hidden ? "false" : "true");
+      toggle.addEventListener("click", function () {
+        showTree(document.documentElement.getAttribute("data-vault-tree") === "hidden");
+      });
+    }
+    var deferred = layout.getAttribute("data-vault-view");
+    if (!deferred) return;
+    fetch(deferred, { headers: { accept: "text/html" } }).then(function (response) {
+      if (!response.ok) throw new Error("status " + response.status);
+      return response.text();
+    }).then(swapVaultSlots).catch(function (error) {
+      failVaultSlots("The files could not be listed: " + (error && error.message ? error.message : String(error)));
+    });
+  }
   wireNavigation();
   wireVault();
+  wireVaultBrowser();
 })();`;