sliftutils 1.4.9 → 1.4.11

package/index.d.ts

@@ -1315,6 +1315,7 @@ declare module "sliftutils/storage/FileFolderAPI" {
     /// <reference types="node" />
     /// <reference types="node" />
     import { IStorageRaw } from "./IStorage";
+    import { RemoteOptions } from "./remoteFileStorage";
     declare global {
         interface Window {
             showSaveFilePicker(config?: {
@@ -1341,7 +1342,7 @@ declare module "sliftutils/storage/FileFolderAPI" {
             }): Promise<PermissionState>;
         }
     }
-    type FileWrapper = {
+    export type FileWrapper = {
         getFile(): Promise<{
             size: number;
             lastModified: number;
@@ -1358,7 +1359,7 @@ declare module "sliftutils/storage/FileFolderAPI" {
             close(): Promise<void>;
         }>;
     };
-    type DirectoryWrapper = {
+    export type DirectoryWrapper = {
         removeEntry(key: string, options?: {
             recursive?: boolean;
         }): Promise<void>;
@@ -1467,8 +1468,8 @@ declare module "sliftutils/storage/FileFolderAPI" {
         folder: NestedFileStorage;
     };
     export declare function wrapHandle(handle: DirectoryWrapper): FileStorage;
+    export declare function getRemoteFileStorageFactory(url: string, password: string, options?: RemoteOptions): (pathStr: string) => Promise<FileStorage>;
     export declare function tryToLoadPointer(pointer: string): Promise<DirectoryWrapper | undefined>;
-    export {};
 
 }
 
@@ -1861,44 +1862,18 @@ declare module "sliftutils/storage/remoteFileServer" {
 }
 
 declare module "sliftutils/storage/remoteFileStorage" {
-    /// <reference types="node" />
-    /// <reference types="node" />
-    /// <reference types="node" />
-    import https from "https";
-    import type { FileStorage } from "./FileFolderAPI";
-    export type RemoteFileStorageOptions = {
+    import type { DirectoryWrapper } from "./FileFolderAPI";
+    export type RemoteOptions = {
         chunkBytes?: number;
         cacheBytes?: number;
         latencyMs?: number;
-    };
-    type Connection = {
-        url: string;
-        password: string;
-        latencyMs: number;
-        agent: https.Agent | undefined;
-        cache: RangeCache;
-        stats: {
+        stats?: {
             requestCount: number;
             bytesFetched: number;
         };
     };
-    declare class RangeCache {
-        private chunkBytes;
-        private budget;
-        private chunks;
-        private bytes;
-        constructor(chunkBytes: number, budget: number);
-        private key;
-        private peek;
-        private store;
-        invalidate(path: string): void;
-        getRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined>;
-    }
-    export type RemoteStorageFactory = ((path: string) => Promise<FileStorage>) & {
-        stats: Connection["stats"];
-    };
-    export declare function getRemoteFileStorage(url: string, password: string, options?: RemoteFileStorageOptions): RemoteStorageFactory;
-    export type RemoteProbeResult = {
+    export declare function getRemoteDirectoryHandle(url: string, password: string, options?: RemoteOptions): DirectoryWrapper;
+    export type RemoteConnectResult = {
         status: "ok";
     } | {
         status: "unauthorized";
@@ -1906,8 +1881,7 @@ declare module "sliftutils/storage/remoteFileStorage" {
         status: "unreachable";
         error: string;
     };
-    export declare function probeRemoteConnection(url: string, password: string): Promise<RemoteProbeResult>;
-    export {};
+    export declare function testRemoteConnection(url: string, password: string, options?: RemoteOptions): Promise<RemoteConnectResult>;
 
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sliftutils",
-    "version": "1.4.9",
+    "version": "1.4.11",
     "main": "index.js",
     "license": "MIT",
     "files": [

package/storage/FileFolderAPI.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { IStorageRaw } from "./IStorage";
+import { RemoteOptions } from "./remoteFileStorage";
 declare global {
     interface Window {
         showSaveFilePicker(config?: {
@@ -27,7 +28,7 @@ declare global {
         }): Promise<PermissionState>;
     }
 }
-type FileWrapper = {
+export type FileWrapper = {
     getFile(): Promise<{
         size: number;
         lastModified: number;
@@ -44,7 +45,7 @@ type FileWrapper = {
         close(): Promise<void>;
     }>;
 };
-type DirectoryWrapper = {
+export type DirectoryWrapper = {
     removeEntry(key: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
@@ -153,5 +154,5 @@ export type FileStorage = IStorageRaw & {
     folder: NestedFileStorage;
 };
 export declare function wrapHandle(handle: DirectoryWrapper): FileStorage;
+export declare function getRemoteFileStorageFactory(url: string, password: string, options?: RemoteOptions): (pathStr: string) => Promise<FileStorage>;
 export declare function tryToLoadPointer(pointer: string): Promise<DirectoryWrapper | undefined>;
-export {};

package/storage/FileFolderAPI.tsx

@@ -7,7 +7,7 @@ import { css, isNode } from "typesafecss";
 import { IStorageRaw } from "./IStorage";
 import { runInSerial } from "socket-function/src/batching";
 import { getFileStorageIndexDB } from "./IndexedDBFileFolderAPI";
-import { getRemoteFileStorage, probeRemoteConnection } from "./remoteFileStorage";
+import { getRemoteDirectoryHandle, testRemoteConnection, RemoteOptions } from "./remoteFileStorage";
 import fs from "fs";
 import path from "path";
 
@@ -36,7 +36,7 @@ declare global {
 // DO NOT enable this is isNode
 const USE_INDEXED_DB = false;
 
-type FileWrapper = {
+export type FileWrapper = {
     getFile(): Promise<{
         size: number;
         lastModified: number;
@@ -51,7 +51,7 @@ type FileWrapper = {
         close(): Promise<void>;
     }>;
 };
-type DirectoryWrapper = {
+export type DirectoryWrapper = {
     removeEntry(key: string, options?: { recursive?: boolean }): Promise<void>;
     getFileHandle(key: string, options?: { create?: boolean }): Promise<FileWrapper>;
     getDirectoryHandle(key: string, options?: { create?: boolean }): Promise<DirectoryWrapper>;
@@ -86,20 +86,14 @@ type RemoteConfig = { url: string; password: string };
 function remoteConfigKey() { return getFileAPIKey() + ":remote"; }
 function loadRemoteConfig(): RemoteConfig | undefined {
     try {
-        const key = remoteConfigKey();
-        const s = localStorage.getItem(key);
-        console.log("[remotecfg] load", JSON.stringify(key), "->", s);
+        const s = localStorage.getItem(remoteConfigKey());
         if (!s) return undefined;
         const c = JSON.parse(s);
         if (c && typeof c.url === "string" && typeof c.password === "string") return c;
-    } catch (e) { console.warn("[remotecfg] load error", e); }
+    } catch { /* ignore */ }
     return undefined;
 }
-function saveRemoteConfig(c: RemoteConfig) {
-    const key = remoteConfigKey();
-    localStorage.setItem(key, JSON.stringify(c));
-    console.log("[remotecfg] saved", JSON.stringify(key), "readback ->", localStorage.getItem(key));
-}
+function saveRemoteConfig(c: RemoteConfig) { localStorage.setItem(remoteConfigKey(), JSON.stringify(c)); }
 
 // The server is always HTTPS on the filehoster's default port, so the user only needs to type the host
 // (e.g. "65.109.93.113"). We strip any scheme/path they include and default the port if omitted.
@@ -111,14 +105,14 @@ function normalizeServerUrl(raw: string): string {
     return "https://" + s;
 }
 
-// One shared factory (and therefore one shared range cache) per remote config.
-let remoteFactory: { key: string; factory: ReturnType<typeof getRemoteFileStorage> } | undefined;
-function getRemoteFactory(remote: RemoteConfig) {
+// One shared remote DirectoryWrapper (and therefore one shared range cache) per remote config.
+let remoteHandle: { key: string; handle: DirectoryWrapper } | undefined;
+function getRemoteHandle(remote: RemoteConfig): DirectoryWrapper {
     const key = remote.url + "\0" + remote.password;
-    if (!remoteFactory || remoteFactory.key !== key) {
-        remoteFactory = { key, factory: getRemoteFileStorage(remote.url, remote.password) };
+    if (!remoteHandle || remoteHandle.key !== key) {
+        remoteHandle = { key, handle: getRemoteDirectoryHandle(remote.url, remote.password) };
     }
-    return remoteFactory.factory;
+    return remoteHandle.handle;
 }
 
 @observer
@@ -139,12 +133,19 @@ class DirectoryPrompter extends preact.Component {
     }
 }
 
-// "Connect to a server" option for the directory prompt: collapses to a button, expands to URL +
-// password fields. On connect it validates the credentials against the server, persists the config, and
-// reloads so getFileStorageNested2 picks up the remote storage.
+// "Connect to a server" option for the directory prompt: collapses to a button, expands to address +
+// password fields. On connect it ACTUALLY connects (testRemoteConnection); only on success does it
+// persist the config and call onConnected, so the caller (getDirectoryHandle) resolves with a working
+// remote handle. Failures are shown to the user (and logged, without the password), never swallowed.
+// `initial` pre-fills + expands the form (used to retry a remembered server that stopped working).
 @observer
-class ServerConnectForm extends preact.Component {
-    private obs = observable({ expanded: false, url: "", password: "", error: "", connecting: false, needsCert: false, showPassword: false });
+class ServerConnectForm extends preact.Component<{ onConnected: (config: RemoteConfig) => void; initial?: RemoteConfig }> {
+    private obs = observable({
+        expanded: !!this.props.initial,
+        url: this.props.initial?.url || "",
+        password: this.props.initial?.password || "",
+        error: "", connecting: false, needsCert: false, showPassword: false,
+    });
     private cleanUrl() { return normalizeServerUrl(this.obs.url); }
     private connect = async () => {
         const s = this.obs;
@@ -153,22 +154,27 @@ class ServerConnectForm extends preact.Component {
         s.connecting = true;
         try {
             const url = this.cleanUrl();
-            if (!url) { s.error = "Enter a server URL"; return; }
-            const result = await probeRemoteConnection(url, s.password.trim());
+            if (!url) { s.error = "Enter a server address."; return; }
+            const result = await testRemoteConnection(url, s.password.trim());
             if (result.status === "ok") {
-                saveRemoteConfig({ url, password: s.password.trim() });
-                window.location.reload();
+                const config: RemoteConfig = { url, password: s.password.trim() };
+                saveRemoteConfig(config);             // remember for next session
+                this.props.onConnected(config);       // hand the verified server back to getDirectoryHandle
                 return;
             }
             if (result.status === "unauthorized") {
                 s.error = "The server rejected that password.";
+                console.error("Remote connect: unauthorized for", url);
             } else {
-                // Reached nothing back — almost always the self-signed certificate isn't trusted yet.
+                // Got nothing back — usually the self-signed certificate isn't trusted yet, but show the
+                // actual error too so a wrong address / down server / CORS issue is diagnosable.
                 s.needsCert = true;
-                s.error = "Couldn't reach the server.";
+                s.error = "Couldn't reach the server: " + result.error;
+                console.error("Remote connect: unreachable", url, "-", result.error);
             }
         } catch (e) {
-            s.error = "Could not connect: " + ((e as Error).message || String(e));
+            s.error = "Connection error: " + ((e as Error).message || String(e));
+            console.error("Remote connect threw:", e);
         } finally {
             s.connecting = false;
         }
@@ -362,132 +368,87 @@ export class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
 }
 
 
-// NOTE: Blocks until the user provides a directory
-// NOTE: If you want to override the location, you can explicitly call getDirectoryHandle.set with your own directory wrapper. Which if your server side can be the Node.js directory handle wrapper, or if your client side it can just be a pointer from tryToLoadPointer/fileSystemPointer.ts.
+// Returns the directory handle to use — local (Node / picked folder) OR a remote server, both as the
+// same DirectoryWrapper, so callers don't know or care which it is. A remembered server is VERIFIED
+// (we actually connect) before use; if it no longer works we re-prompt, just like a local folder whose
+// permission was lost. Blocks until ready (or the user dismisses, which rejects).
 export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Promise<DirectoryWrapper> {
     if (isNode()) {
         return new NodeJSDirectoryHandleWrapper(path.resolve("./data/"));
     }
+
+    // A server connected in a previous session: only reuse it if it still actually works.
+    const savedRemote = loadRemoteConfig();
+    if (savedRemote) {
+        const result = await testRemoteConnection(savedRemote.url, savedRemote.password);
+        if (result.status === "ok") return getRemoteHandle(savedRemote);
+        console.warn(`Saved remote server didn't connect (${result.status})${result.status === "unreachable" ? ": " + result.error : ""} — re-prompting.`);
+    }
+
     let root = document.createElement("div");
     document.body.appendChild(root);
     preact.render(<DirectoryPrompter />, root);
     try {
+        let resolveHandle!: (h: DirectoryWrapper) => void;
+        let rejectHandle!: (e: Error) => void;
+        const promise = new Promise<DirectoryWrapper>((res, rej) => { resolveHandle = res; rejectHandle = rej; });
 
-        let handle: DirectoryWrapper | undefined;
+        const pickLocal = async () => {
+            try {
+                const handle = await window.showDirectoryPicker();
+                await handle.requestPermission({ mode: "readwrite" });
+                const storedId = await storeFileSystemPointer({ mode: "readwrite", handle });
+                localStorage.setItem(getFileAPIKey(), storedId);
+                resolveHandle(handle as any);
+            } catch (e) {
+                console.error("Directory pick failed/cancelled:", e); // stay on the prompt
+            }
+        };
+        const onConnected = (config: RemoteConfig) => { saveRemoteConfig(config); resolveHandle(getRemoteHandle(config)); };
+        // The three options, rendered fresh each time. If a saved server just failed, pre-fill + expand
+        // the connect form so the user can retry or fix it.
+        const renderOptions = () => (
+            <>
+                <button className={css.fontSize(40).pad2(80, 40)} onClick={pickLocal}>Pick Data Directory</button>
+                <ServerConnectForm onConnected={onConnected} initial={savedRemote} />
+                <button className={css.fontSize(40).pad2(80, 40)}
+                    onClick={() => rejectHandle(new Error("User dismissed file system access prompt"))}>Dismiss</button>
+            </>
+        );
 
-        const storedId = localStorage.getItem(getFileAPIKey());
+        // A previously-picked local folder: try to restore it (may need a click). Skipped when a saved
+        // server failed — that user wants the server, so go straight to the (pre-filled) prompt.
+        const storedId = !savedRemote && localStorage.getItem(getFileAPIKey());
         if (storedId) {
             let doneLoad = false;
-            setTimeout(() => {
-                if (doneLoad) return;
-                console.log("Waiting for user to click");
-                displayData.ui = "Click anywhere to allow file system access";
-            }, 500);
+            setTimeout(() => { if (!doneLoad) displayData.ui = "Click anywhere to allow file system access"; }, 500);
             try {
-                handle = await tryToLoadPointer(storedId);
+                const handle = await tryToLoadPointer(storedId);
+                doneLoad = true;
+                if (handle) return handle;
             } catch (e) {
+                doneLoad = true;
                 console.error(e);
-                // Check if the error is due to user activation being required
-                const errorMessage = e instanceof Error ? e.message : String(e);
-                if (errorMessage.includes("user activation") || errorMessage.includes("User activation")) {
-                    doneLoad = true;
-                    // Show UI to get user to click and retry
-                    let retryCallback: (success: boolean) => void;
-                    let retryReject: (err: Error) => void;
-                    let retryPromise = new Promise<boolean>((resolve, reject) => {
-                        retryCallback = resolve;
-                        retryReject = reject;
-                    });
+                const msg = e instanceof Error ? e.message : String(e);
+                if (msg.includes("user activation") || msg.includes("User activation")) {
                     displayData.ui = (
                         <div className={css.vbox(20).center}>
-                            <button
-                                className={css.fontSize(40).pad2(80, 40)}
-                                onClick={async () => {
-                                    displayData.ui = "Loading...";
-                                    try {
-                                        const retryHandle = await tryToLoadPointer(storedId);
-                                        if (retryHandle) {
-                                            handle = retryHandle;
-                                            retryCallback(true);
-                                        } else {
-                                            retryCallback(false);
-                                        }
-                                    } catch (retryError) {
-                                        console.error("Retry failed:", retryError);
-                                        retryCallback(false);
-                                    }
-                                }}
-                            >
-                                Click to restore file system access
-                            </button>
-                            <button
-                                className={css.fontSize(40).pad2(80, 40)}
-                                onClick={async () => {
-                                    console.log("Waiting for user to give permission");
-                                    const pickedHandle = await window.showDirectoryPicker();
-                                    await pickedHandle.requestPermission({ mode: "readwrite" });
-                                    let newStoredId = await storeFileSystemPointer({ mode: "readwrite", handle: pickedHandle });
-                                    localStorage.setItem(getFileAPIKey(), newStoredId);
-                                    handle = pickedHandle as any;
-                                    retryCallback(true);
-                                }}
-                            >
-                                Pick Data Directory
-                            </button>
-                            <ServerConnectForm />
-                            <button
-                                className={css.fontSize(40).pad2(80, 40)}
-                                onClick={() => {
-                                    retryReject(new Error("User dismissed file system access prompt"));
-                                }}
-                            >
-                                Dismiss
-                            </button>
+                            <button className={css.fontSize(40).pad2(80, 40)} onClick={async () => {
+                                displayData.ui = "Loading...";
+                                try {
+                                    const h = await tryToLoadPointer(storedId);
+                                    if (h) { resolveHandle(h); return; }
+                                } catch (retryError) { console.error("Retry failed:", retryError); }
+                                displayData.ui = <div className={css.vbox(20).center}>{renderOptions()}</div>;
+                            }}>Click to restore file system access</button>
+                            {renderOptions()}
                         </div>
                     );
-                    const success = await retryPromise;
-                    if (handle) {
-                        return handle;
-                    }
+                    return await promise;
                 }
             }
-            doneLoad = true;
-            if (handle) {
-                return handle;
-            }
         }
-        let fileCallback: (handle: DirectoryWrapper) => void;
-        let fileReject: (err: Error) => void;
-        let promise = new Promise<DirectoryWrapper>((resolve, reject) => {
-            fileCallback = resolve;
-            fileReject = reject;
-        });
-        displayData.ui = (
-            <div className={css.vbox(20).center}>
-                <button
-                    className={css.fontSize(40).pad2(80, 40)}
-                    onClick={async () => {
-                        console.log("Waiting for user to give permission");
-                        const handle = await window.showDirectoryPicker();
-                        await handle.requestPermission({ mode: "readwrite" });
-                        let storedId = await storeFileSystemPointer({ mode: "readwrite", handle });
-                        localStorage.setItem(getFileAPIKey(), storedId);
-                        fileCallback(handle as any);
-                    }}
-                >
-                    Pick Data Directory
-                </button>
-                <ServerConnectForm />
-                <button
-                    className={css.fontSize(40).pad2(80, 40)}
-                    onClick={() => {
-                        fileReject(new Error("User dismissed file system access prompt"));
-                    }}
-                >
-                    Dismiss
-                </button>
-            </div>
-        );
+        displayData.ui = <div className={css.vbox(20).center}>{renderOptions()}</div>;
         return await promise;
     } finally {
         preact.render(null, root);
@@ -507,10 +468,6 @@ export const getFileStorageNested = cache(async function getFileStorage(path: st
 export const getFileStorageNested2 = cache(async function getFileStorage(pathStr: string): Promise<FileStorage> {
     let base: DirectoryWrapper;
     pathStr = pathStr.replaceAll("\\", "/");
-    if (!isNode()) {
-        const remote = loadRemoteConfig();
-        if (remote) return getRemoteFactory(remote)(pathStr);
-    }
     if (isNode()) {
         if (path.isAbsolute(pathStr)) {
             return wrapHandle(new NodeJSDirectoryHandleWrapper(pathStr));
@@ -541,7 +498,6 @@ export const getFileStorage = lazy(async function getFileStorage(): Promise<File
     if (USE_INDEXED_DB) {
         return await getFileStorageIndexDB();
     }
-
     let handle = await getDirectoryHandle();
     return wrapHandle(handle);
 });
@@ -757,6 +713,20 @@ export function wrapHandle(handle: DirectoryWrapper): FileStorage {
     };
 }
 
+// A StorageFactory backed by a remote server (path -> FileStorage), for code that injects its own
+// storage into BulkDatabase2 rather than going through the directory prompt.
+export function getRemoteFileStorageFactory(url: string, password: string, options?: RemoteOptions): (pathStr: string) => Promise<FileStorage> {
+    const root = getRemoteDirectoryHandle(url, password, options);
+    return async (pathStr: string) => {
+        let base: DirectoryWrapper = root;
+        for (const part of pathStr.replaceAll("\\", "/").split("/")) {
+            if (!part) continue;
+            base = await base.getDirectoryHandle(part, { create: true });
+        }
+        return wrapHandle(base);
+    };
+}
+
 export async function tryToLoadPointer(pointer: string) {
     let result = await getFileSystemPointer({ pointer });
     if (!result) return;

package/storage/remoteFileServer.ts

@@ -203,6 +203,22 @@ function normalizePassword(p: string): string {
     return String(p || "").toLowerCase().replace(/[^a-z]/g, "");
 }
 
+// The password is generated once and saved (next to the cert, outside the served folder), then reused
+// across restarts — so connected clients keep working after the server bounces, instead of getting a
+// new password every time. Override with the PASSWORD env var.
+function getOrCreatePassword(): string {
+    const dir = path.join(os.homedir(), ".sliftutils-remote");
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, "password.txt");
+    try {
+        const existing = fs.readFileSync(file, "utf8").trim();
+        if (existing) return existing;
+    } catch { /* not created yet */ }
+    const pw = generatePassword(6);
+    fs.writeFileSync(file, pw + "\n", { mode: 0o600 });
+    return pw;
+}
+
 // Generate (once) and cache a self-signed key + cert via openssl, outside the served folder so its
 // private key is never reachable through the API.
 function getCert(): { key: Buffer; cert: Buffer } {
@@ -278,7 +294,7 @@ export function startRemoteFileServer(options: RemoteFileServerOptions): Promise
     if (!fs.existsSync(root)) fs.mkdirSync(root, { recursive: true });
     const port = options.port ?? 8787;
     const host = options.host || "0.0.0.0";
-    const password = options.password || generatePassword(6);
+    const password = options.password || getOrCreatePassword();
     const normPassword = normalizePassword(password);
     const { key, cert } = getCert();
 
@@ -340,21 +356,17 @@ export function startRemoteFileServer(options: RemoteFileServerOptions): Promise
             const full = safeResolve(root, relPath);
             if (full === undefined) return sendJson(403, { error: "path escapes root" });
 
+            // One listing returns every entry with its type, so a directory read is a single round trip.
             if (req.method === "GET" && op === "/list") {
-                const wantFolders = url.searchParams.get("folders") === "1";
                 let entries: fs.Dirent[];
                 try { entries = fs.readdirSync(full, { withFileTypes: true }); }
                 catch (e) { return (e as NodeJS.ErrnoException).code === "ENOENT" ? sendJson(200, []) : sendJson(500, { error: (e as Error).message }); }
-                return sendJson(200, entries.filter(d => wantFolders ? d.isDirectory() : d.isFile()).map(d => d.name));
+                return sendJson(200, entries.filter(d => d.isFile() || d.isDirectory()).map(d => ({ name: d.name, dir: d.isDirectory() })));
             }
             if (req.method === "GET" && op === "/info") {
                 let st: fs.Stats;
                 try { st = fs.statSync(full); } catch { return sendJson(404, { error: "not found" }); }
-                return sendJson(200, { size: st.size, lastModified: st.mtimeMs });
-            }
-            if (req.method === "GET" && op === "/hasDir") {
-                let st: fs.Stats; try { st = fs.statSync(full); } catch { return sendJson(200, { exists: false }); }
-                return sendJson(200, { exists: st.isDirectory() });
+                return sendJson(200, { size: st.size, lastModified: st.mtimeMs, dir: st.isDirectory() });
             }
             if (req.method === "GET" && op === "/read") {
                 let st: fs.Stats;
@@ -377,19 +389,11 @@ export function startRemoteFileServer(options: RemoteFileServerOptions): Promise
                 recordAccess(clientIp(req), "write", relPath, body.length);
                 return sendJson(200, { ok: true });
             }
+            // Removes a file or a directory (recursively); missing is fine.
             if (req.method === "DELETE" && op === "/remove") {
-                try { fs.unlinkSync(full); } catch (e) { if ((e as NodeJS.ErrnoException).code !== "ENOENT") return sendJson(500, { error: (e as Error).message }); }
-                return sendJson(200, { ok: true });
-            }
-            if (req.method === "DELETE" && op === "/removeDir") {
                 try { fs.rmSync(full, { recursive: true, force: true }); } catch (e) { return sendJson(500, { error: (e as Error).message }); }
                 return sendJson(200, { ok: true });
             }
-            if (req.method === "POST" && op === "/reset") {
-                try { for (const name of fs.readdirSync(full)) fs.rmSync(path.join(full, name), { recursive: true, force: true }); }
-                catch (e) { if ((e as NodeJS.ErrnoException).code !== "ENOENT") return sendJson(500, { error: (e as Error).message }); }
-                return sendJson(200, { ok: true });
-            }
             return sendJson(404, { error: "unknown endpoint" });
         } catch (e) {
             try { sendJson(500, { error: String((e as Error)?.message || e) }); } catch { /* response already sent */ }

package/storage/remoteFileStorage.d.ts

@@ -1,41 +1,15 @@
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-import https from "https";
-import type { FileStorage } from "./FileFolderAPI";
-export type RemoteFileStorageOptions = {
+import type { DirectoryWrapper } from "./FileFolderAPI";
+export type RemoteOptions = {
     chunkBytes?: number;
     cacheBytes?: number;
     latencyMs?: number;
-};
-type Connection = {
-    url: string;
-    password: string;
-    latencyMs: number;
-    agent: https.Agent | undefined;
-    cache: RangeCache;
-    stats: {
+    stats?: {
         requestCount: number;
         bytesFetched: number;
     };
 };
-declare class RangeCache {
-    private chunkBytes;
-    private budget;
-    private chunks;
-    private bytes;
-    constructor(chunkBytes: number, budget: number);
-    private key;
-    private peek;
-    private store;
-    invalidate(path: string): void;
-    getRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined>;
-}
-export type RemoteStorageFactory = ((path: string) => Promise<FileStorage>) & {
-    stats: Connection["stats"];
-};
-export declare function getRemoteFileStorage(url: string, password: string, options?: RemoteFileStorageOptions): RemoteStorageFactory;
-export type RemoteProbeResult = {
+export declare function getRemoteDirectoryHandle(url: string, password: string, options?: RemoteOptions): DirectoryWrapper;
+export type RemoteConnectResult = {
     status: "ok";
 } | {
     status: "unauthorized";
@@ -43,5 +17,4 @@ export type RemoteProbeResult = {
     status: "unreachable";
     error: string;
 };
-export declare function probeRemoteConnection(url: string, password: string): Promise<RemoteProbeResult>;
-export {};
+export declare function testRemoteConnection(url: string, password: string, options?: RemoteOptions): Promise<RemoteConnectResult>;

package/storage/remoteFileStorage.ts

@@ -1,99 +1,140 @@
 import { isNode } from "typesafecss";
 import https from "https";
-import type { FileStorage, NestedFileStorage } from "./FileFolderAPI";
+import type { DirectoryWrapper, FileWrapper } from "./FileFolderAPI";
 
-// Client for remoteFileServer.js: exposes a remote folder as a FileStorage (so BulkDatabase2 runs over
-// the network unchanged). One HTTP round trip per operation. A pure data-level range cache (below)
-// fetches in large aligned chunks and reuses them, because over the network latency dominates — reading
-// 1MB costs about the same as 64KB, so fewer round trips wins.
+// A remote server (remoteFileServer.js) exposed as a DirectoryWrapper — the SAME interface as the
+// Node.js and File-System-Access handles. So getDirectoryHandle can return one of these and everything
+// downstream (wrapHandle, navigation, BulkDatabase2) works unchanged; nothing else knows it's remote.
+//
+// Files here are immutable (written once) or append-only, so the range cache (raw compressed bytes, in
+// ~1MB aligned chunks) is always valid — over the network latency dominates, so reading 1MB costs about
+// the same as 64KB and far fewer round trips wins.
 
 const EMPTY = Buffer.alloc(0);
-
-// Over the network, fetch reads in chunks this big and cache them. Big because each request pays a
-// full round trip; over-reading a bit is far cheaper than another round trip.
 const DEFAULT_CHUNK_BYTES = 1024 * 1024;
 const DEFAULT_CACHE_BYTES = 128 * 1024 * 1024;
 
-export type RemoteFileStorageOptions = {
-    // Bytes per cached chunk (aligned). Reads coalesce/serve from these.
+export type RemoteOptions = {
     chunkBytes?: number;
-    // Max total bytes held in the range cache (LRU eviction).
     cacheBytes?: number;
-    // Artificial per-request delay, for simulating network latency in tests.
-    latencyMs?: number;
-};
-
-type Connection = {
-    url: string;
-    password: string;
-    latencyMs: number;
-    agent: https.Agent | undefined;
-    cache: RangeCache;
-    // Observable stats (handy for tests / diagnostics).
-    stats: { requestCount: number; bytesFetched: number };
+    latencyMs?: number;          // artificial per-request delay, for simulating network latency in tests
+    stats?: { requestCount: number; bytesFetched: number };
 };
 
+function enoent(p: string): Error {
+    return Object.assign(new Error(`File not found: ${p}`), { code: "ENOENT", name: "NotFoundError" });
+}
+function toArrayBuffer(b: Buffer): ArrayBuffer {
+    return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength) as ArrayBuffer;
+}
 const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
 
-// One HTTP request. Node uses the https module (self-signed cert → verification disabled); the browser
-// uses fetch (the user accepts the self-signed cert once). Returns the raw status + body bytes.
-async function httpRequest(conn: Connection, method: string, op: string, params: Record<string, string>, body?: Buffer): Promise<{ status: number; body: Buffer }> {
-    if (conn.latencyMs > 0) await sleep(conn.latencyMs);
-    conn.stats.requestCount++;
-    const qs = new URLSearchParams(params).toString();
-    const fullUrl = conn.url.replace(/\/+$/, "") + op + (qs ? "?" + qs : "");
-    const headers: Record<string, string> = { authorization: "Bearer " + conn.password };
-    if (body) headers["content-type"] = "application/octet-stream";
+type Stat = { size: number; lastModified: number; dir: boolean };
 
-    if (isNode()) {
-        return await new Promise((resolve, reject) => {
-            const u = new URL(fullUrl);
-            const req = https.request({
-                hostname: u.hostname, port: u.port, path: u.pathname + u.search, method, headers, agent: conn.agent,
-            }, res => {
-                const chunks: Buffer[] = [];
-                res.on("data", d => chunks.push(d as Buffer));
-                res.on("end", () => resolve({ status: res.statusCode || 0, body: Buffer.concat(chunks) }));
+// A stat is cached this long, so the burst of size lookups during a single read pass is one request per
+// file, not one per block. Short enough that an append by another writer shows up promptly; our own
+// writes invalidate it immediately.
+const INFO_TTL_MS = 2000;
+
+class Connection {
+    private agent = isNode() ? new https.Agent({ rejectUnauthorized: false }) : undefined;
+    private cache: RangeCache;
+    private infoCache = new Map<string, { stat: Stat | undefined; at: number }>();
+    constructor(public url: string, public password: string, private opts: RemoteOptions) {
+        this.cache = new RangeCache(opts.chunkBytes || DEFAULT_CHUNK_BYTES, opts.cacheBytes || DEFAULT_CACHE_BYTES);
+        this.url = url.replace(/\/+$/, "");
+    }
+
+    // One HTTP request. Node uses the https module (self-signed cert → verification disabled); the
+    // browser uses fetch (the user has accepted the cert). Returns the raw status + body bytes.
+    async request(method: string, op: string, params: Record<string, string>, body?: Buffer): Promise<{ status: number; body: Buffer }> {
+        if (this.opts.latencyMs) await sleep(this.opts.latencyMs);
+        if (this.opts.stats) this.opts.stats.requestCount++;
+        const qs = new URLSearchParams(params).toString();
+        const fullUrl = this.url + op + (qs ? "?" + qs : "");
+        const headers: Record<string, string> = { authorization: "Bearer " + this.password };
+        if (body) headers["content-type"] = "application/octet-stream";
+        if (isNode()) {
+            return await new Promise((resolve, reject) => {
+                const u = new URL(fullUrl);
+                const req = https.request({ hostname: u.hostname, port: u.port, path: u.pathname + u.search, method, headers, agent: this.agent }, res => {
+                    const chunks: Buffer[] = [];
+                    res.on("data", d => chunks.push(d as Buffer));
+                    res.on("end", () => resolve({ status: res.statusCode || 0, body: Buffer.concat(chunks) }));
+                });
+                req.on("error", reject);
+                if (body) req.write(body);
+                req.end();
             });
-            req.on("error", reject);
-            if (body) req.write(body);
-            req.end();
-        });
+        }
+        const res = await fetch(fullUrl, { method, headers, body: body ? new Uint8Array(body) : undefined });
+        return { status: res.status, body: Buffer.from(await res.arrayBuffer()) };
     }
-    const res = await fetch(fullUrl, { method, headers, body: body ? new Uint8Array(body) : undefined });
-    const buf = Buffer.from(await res.arrayBuffer());
-    return { status: res.status, body: buf };
-}
 
-async function readRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined> {
-    const r = await httpRequest(conn, "GET", "/read", { path, start: String(start), end: String(end) });
-    if (r.status === 404) return undefined;
-    if (r.status !== 200) throw new Error(`remote read failed (${r.status}): ${r.body.toString("utf8").slice(0, 200)}`);
-    conn.stats.bytesFetched += r.body.length;
-    return r.body;
+    async stat(path: string): Promise<Stat | undefined> {
+        const cached = this.infoCache.get(path);
+        if (cached && Date.now() - cached.at < INFO_TTL_MS) return cached.stat;
+        const r = await this.request("GET", "/info", { path });
+        let stat: Stat | undefined;
+        if (r.status === 404) stat = undefined;
+        else if (r.status !== 200) throw new Error(`remote info failed (${r.status})`);
+        else stat = JSON.parse(r.body.toString("utf8")) as Stat;
+        this.infoCache.set(path, { stat, at: Date.now() });
+        return stat;
+    }
+    async list(path: string): Promise<{ name: string; dir: boolean }[]> {
+        const r = await this.request("GET", "/list", { path });
+        if (r.status !== 200) throw new Error(`remote list failed (${r.status})`);
+        return JSON.parse(r.body.toString("utf8"));
+    }
+    async read(path: string, start: number, end: number): Promise<Buffer> {
+        return (await this.cache.read(this, path, start, end)) ?? EMPTY;
+    }
+    async readServer(path: string, start: number, end: number): Promise<Buffer | undefined> {
+        const r = await this.request("GET", "/read", { path, start: String(start), end: String(end) });
+        if (r.status === 404) return undefined;
+        if (r.status !== 200) throw new Error(`remote read failed (${r.status})`);
+        if (this.opts.stats) this.opts.stats.bytesFetched += r.body.length;
+        return r.body;
+    }
+    async append(path: string, body: Buffer): Promise<void> {
+        const r = await this.request("PUT", "/append", { path }, body);
+        if (r.status !== 200) throw new Error(`remote append failed (${r.status})`);
+        // Append-only keeps existing bytes, so cached chunks stay valid; just the size changed.
+        this.infoCache.delete(path);
+    }
+    async set(path: string, body: Buffer): Promise<void> {
+        const r = await this.request("PUT", "/set", { path }, body);
+        if (r.status !== 200) throw new Error(`remote set failed (${r.status})`);
+        this.cache.invalidate(path);
+        this.infoCache.delete(path);
+    }
+    async remove(path: string): Promise<void> {
+        const r = await this.request("DELETE", "/remove", { path });
+        if (r.status !== 200) throw new Error(`remote remove failed (${r.status})`);
+        this.cache.invalidate(path);
+        this.infoCache.delete(path);
+    }
 }
 
-// Caches the longest-known prefix of each aligned chunk per path. Safe because every file here is either
-// immutable (bulk files, written once under a unique name) or append-only (stream files): the bytes at a
-// given offset never change, only more are added. So a cached [0, n) of a chunk is always valid; a read
-// that needs MORE than we have refetches (and picks up appended bytes). It never distinguishes file
-// types — it only does range reads.
+// Caches the longest-known prefix of each aligned chunk per path. Valid because files are immutable or
+// append-only (the bytes at an offset never change). It only does range reads — it doesn't care what
+// the files are.
 class RangeCache {
-    private chunks = new Map<string, Buffer>(); // key: path + "
" + chunkIndex (insertion-ordered → LRU)
+    private chunks = new Map<string, Buffer>(); // path + "
" + chunkIndex, insertion-ordered (LRU)
     private bytes = 0;
     constructor(private chunkBytes: number, private budget: number) { }
-
     private key(path: string, c: number) { return path + "
" + c; }
     private peek(path: string, c: number): Buffer | undefined {
         const k = this.key(path, c);
         const v = this.chunks.get(k);
-        if (v) { this.chunks.delete(k); this.chunks.set(k, v); } // bump to most-recent
+        if (v) { this.chunks.delete(k); this.chunks.set(k, v); }
         return v;
     }
     private store(path: string, c: number, buf: Buffer) {
         const k = this.key(path, c);
         const ex = this.chunks.get(k);
-        if (ex && ex.length >= buf.length) { this.chunks.delete(k); this.chunks.set(k, ex); return; } // keep longer prefix
+        if (ex && ex.length >= buf.length) { this.chunks.delete(k); this.chunks.set(k, ex); return; }
         if (ex) this.bytes -= ex.length;
         this.chunks.delete(k);
         this.chunks.set(k, buf);
@@ -106,17 +147,13 @@ class RangeCache {
     }
     invalidate(path: string) {
         const prefix = path + "
";
-        for (const k of [...this.chunks.keys()]) {
-            if (k.startsWith(prefix)) { this.bytes -= (this.chunks.get(k) as Buffer).length; this.chunks.delete(k); }
-        }
+        for (const k of [...this.chunks.keys()]) if (k.startsWith(prefix)) { this.bytes -= (this.chunks.get(k) as Buffer).length; this.chunks.delete(k); }
     }
-
-    async getRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined> {
+    async read(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined> {
         if (end <= start) return EMPTY;
         const CHUNK = this.chunkBytes;
         const firstChunk = Math.floor(start / CHUNK);
         const lastChunk = Math.floor((end - 1) / CHUNK);
-        // Find the contiguous span of chunks we don't have enough of, and fetch it in one request.
         let fetchFrom = -1, fetchTo = -1;
         for (let c = firstChunk; c <= lastChunk; c++) {
             const cStart = c * CHUNK;
@@ -125,11 +162,11 @@ class RangeCache {
             if (!have || have.length < needEnd) { if (fetchFrom < 0) fetchFrom = c; fetchTo = c; }
         }
         if (fetchFrom >= 0) {
-            const bytes = await readRange(conn, path, fetchFrom * CHUNK, (fetchTo + 1) * CHUNK);
-            if (bytes === undefined) return undefined; // file missing
+            const bytes = await conn.readServer(path, fetchFrom * CHUNK, (fetchTo + 1) * CHUNK);
+            if (bytes === undefined) return undefined;
             for (let c = fetchFrom; c <= fetchTo; c++) {
                 const off = (c - fetchFrom) * CHUNK;
-                if (off >= bytes.length) break; // hit EOF — no bytes for this chunk
+                if (off >= bytes.length) break;
                 this.store(path, c, bytes.subarray(off, Math.min(off + CHUNK, bytes.length)));
             }
         }
@@ -139,122 +176,99 @@ class RangeCache {
             const from = Math.max(start, cStart) - cStart;
             const to = Math.min(end, cStart + CHUNK) - cStart;
             const chunk = this.peek(path, c);
-            if (!chunk || chunk.length < to) {
-                // File ended before the requested end — return what's available (callers read within EOF).
-                if (chunk && chunk.length > from) parts.push(chunk.subarray(from, chunk.length));
-                break;
-            }
+            if (!chunk || chunk.length < to) { if (chunk && chunk.length > from) parts.push(chunk.subarray(from, chunk.length)); break; }
             parts.push(chunk.subarray(from, to));
         }
         return parts.length === 1 ? parts[0] : Buffer.concat(parts);
     }
 }
 
-function makeStorage(conn: Connection, basePath: string): FileStorage {
-    const rel = (key: string) => basePath ? basePath + "/" + key : key;
+const joinPath = (base: string, key: string) => (base ? base + "/" + key : key);
 
-    const folder: NestedFileStorage = {
-        async hasKey(key: string): Promise<boolean> {
-            const r = await httpRequest(conn, "GET", "/hasDir", { path: rel(key) });
-            if (r.status !== 200) return false;
-            return !!JSON.parse(r.body.toString("utf8")).exists;
-        },
-        async getStorage(key: string): Promise<FileStorage> {
-            return makeStorage(conn, rel(key));
-        },
-        async removeStorage(key: string): Promise<void> {
-            await httpRequest(conn, "DELETE", "/removeDir", { path: rel(key) });
-            conn.cache.invalidate(rel(key));
-        },
-        async getKeys(): Promise<string[]> {
-            const r = await httpRequest(conn, "GET", "/list", { path: basePath, folders: "1" });
-            if (r.status !== 200) throw new Error(`remote list failed (${r.status})`);
-            return JSON.parse(r.body.toString("utf8"));
-        },
-    };
-
-    return {
-        async getInfo(key: string) {
-            const r = await httpRequest(conn, "GET", "/info", { path: rel(key) });
-            if (r.status === 404) return undefined;
-            if (r.status !== 200) throw new Error(`remote info failed (${r.status})`);
-            return JSON.parse(r.body.toString("utf8")) as { size: number; lastModified: number };
-        },
-        async get(key: string) {
-            const info = await this.getInfo(key);
-            if (!info) return undefined;
-            return this.getRange(key, { start: 0, end: info.size });
-        },
-        async getRange(key: string, config: { start: number; end: number }) {
-            return conn.cache.getRange(conn, rel(key), config.start, config.end);
-        },
-        async append(key: string, value: Buffer) {
-            const r = await httpRequest(conn, "PUT", "/append", { path: rel(key) }, value);
-            if (r.status !== 200) throw new Error(`remote append failed (${r.status})`);
-            // No invalidation needed: append-only files keep their prefix; a read past it refetches.
-        },
-        async set(key: string, value: Buffer) {
-            const r = await httpRequest(conn, "PUT", "/set", { path: rel(key) }, value);
-            if (r.status !== 200) throw new Error(`remote set failed (${r.status})`);
-            conn.cache.invalidate(rel(key));
-        },
-        async remove(key: string) {
-            await httpRequest(conn, "DELETE", "/remove", { path: rel(key) });
-            conn.cache.invalidate(rel(key));
-        },
-        async getKeys(includeFolders: boolean = false) {
-            const r = await httpRequest(conn, "GET", "/list", { path: basePath, folders: includeFolders ? "1" : "0" });
-            if (r.status !== 200) throw new Error(`remote list failed (${r.status})`);
-            return JSON.parse(r.body.toString("utf8"));
-        },
-        async reset() {
-            await httpRequest(conn, "POST", "/reset", { path: basePath });
-            conn.cache.invalidate(basePath);
-        },
-        folder,
-    };
+class RemoteFileWrapper implements FileWrapper {
+    // `stat` is supplied when the parent already statted us (avoids a second /info). `createIntent` means
+    // this was opened with create:true, so a missing file reads as empty (it'll be created on write).
+    constructor(private conn: Connection, private filePath: string, private stat?: Stat, private createIntent = false) { }
+    async getFile() {
+        let stat = this.stat ?? await this.conn.stat(this.filePath);
+        if (!stat) {
+            if (!this.createIntent) throw enoent(this.filePath);
+            stat = { size: 0, lastModified: Date.now(), dir: false };
+        }
+        const conn = this.conn, filePath = this.filePath, size = stat.size;
+        return {
+            size, lastModified: stat.lastModified,
+            async arrayBuffer() { return toArrayBuffer(await conn.read(filePath, 0, size)); },
+            slice(start: number, end: number) {
+                return { async arrayBuffer() { return toArrayBuffer(await conn.read(filePath, start, end)); } };
+            },
+        };
+    }
+    async createWritable(config?: { keepExistingData?: boolean }) {
+        const conn = this.conn, filePath = this.filePath, append = !!config?.keepExistingData;
+        const chunks: Buffer[] = [];
+        return {
+            async seek() { /* the server appends to the end / overwrites the whole file; offset unused */ },
+            async write(value: Buffer) { chunks.push(value); },
+            async close() {
+                const body = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
+                if (append) await conn.append(filePath, body); else await conn.set(filePath, body);
+            },
+        };
+    }
 }
 
-export type RemoteStorageFactory = ((path: string) => Promise<FileStorage>) & { stats: Connection["stats"] };
+class RemoteDirectoryWrapper implements DirectoryWrapper {
+    constructor(private conn: Connection, private dirPath: string) { }
+    async removeEntry(key: string): Promise<void> {
+        await this.conn.remove(joinPath(this.dirPath, key));
+    }
+    async getFileHandle(key: string, options?: { create?: boolean }): Promise<FileWrapper> {
+        const p = joinPath(this.dirPath, key);
+        if (options?.create) return new RemoteFileWrapper(this.conn, p, undefined, true);
+        const stat = await this.conn.stat(p);                 // matches the File API: throw if missing
+        if (!stat || stat.dir) throw enoent(p);
+        return new RemoteFileWrapper(this.conn, p, stat, false);
+    }
+    async getDirectoryHandle(key: string, options?: { create?: boolean }): Promise<DirectoryWrapper> {
+        const p = joinPath(this.dirPath, key);
+        if (!options?.create) {
+            const stat = await this.conn.stat(p);
+            if (!stat || !stat.dir) throw enoent(p);
+        }
+        return new RemoteDirectoryWrapper(this.conn, p);       // dirs are created lazily on first write
+    }
+    async *[Symbol.asyncIterator](): AsyncIterableIterator<[string, { kind: "file"; name: string; getFile(): Promise<FileWrapper> } | { kind: "directory"; name: string; getDirectoryHandle(key: string, options?: { create?: boolean }): Promise<DirectoryWrapper> }]> {
+        const entries = await this.conn.list(this.dirPath);
+        for (const e of entries) {
+            const childPath = joinPath(this.dirPath, e.name);
+            if (e.dir) {
+                yield [e.name, { kind: "directory", name: e.name, getDirectoryHandle: (k, o) => new RemoteDirectoryWrapper(this.conn, childPath).getDirectoryHandle(k, o) }];
+            } else {
+                yield [e.name, { kind: "file", name: e.name, getFile: async () => new RemoteFileWrapper(this.conn, childPath) }];
+            }
+        }
+    }
+}
 
-// Returns a StorageFactory (path -> FileStorage) backed by a remoteFileServer.js instance. Drop-in for
-// getFileStorageNested2 in BulkDatabase2. `password` is the 6-word password the server printed.
-export function getRemoteFileStorage(url: string, password: string, options: RemoteFileStorageOptions = {}): RemoteStorageFactory {
-    const conn: Connection = {
-        url,
-        password,
-        latencyMs: options.latencyMs || 0,
-        // Self-signed cert: skip verification in Node. (The browser path uses fetch, where the user has
-        // already accepted the cert.) The password is what authorizes access.
-        agent: isNode() ? new https.Agent({ rejectUnauthorized: false }) : undefined,
-        cache: new RangeCache(options.chunkBytes || DEFAULT_CHUNK_BYTES, options.cacheBytes || DEFAULT_CACHE_BYTES),
-        stats: { requestCount: 0, bytesFetched: 0 },
-    };
-    const factory = ((path: string) => Promise.resolve(makeStorage(conn, path.replace(/^\/+|\/+$/g, "")))) as RemoteStorageFactory;
-    factory.stats = conn.stats;
-    return factory;
+// A DirectoryWrapper rooted at a remote server. Drop-in for the Node / File-API handles.
+export function getRemoteDirectoryHandle(url: string, password: string, options: RemoteOptions = {}): DirectoryWrapper {
+    return new RemoteDirectoryWrapper(new Connection(url, password, options), "");
 }
 
-export type RemoteProbeResult =
-    | { status: "ok" }
-    | { status: "unauthorized" }
-    // Couldn't reach the server at all — in the browser this is usually the self-signed certificate not
-    // being trusted yet (fetch throws with no detail), but also covers a wrong URL / server down / CORS.
-    | { status: "unreachable"; error: string };
+export type RemoteConnectResult = { status: "ok" } | { status: "unauthorized" } | { status: "unreachable"; error: string };
 
-// Probes a remote server: distinguishes "connected" from "wrong password" from "couldn't reach it". The
-// browser can't tell a cert-distrust from other network failures (fetch just throws), so the UI treats
-// `unreachable` as "you probably need to accept the self-signed certificate first".
-export async function probeRemoteConnection(url: string, password: string): Promise<RemoteProbeResult> {
+// Verifies a server is reachable and the password works — by actually listing the root. Distinguishes
+// "connected" / "wrong password" / "couldn't reach it" (the last usually meaning the self-signed cert
+// isn't trusted yet in the browser, since fetch failures carry no detail).
+export async function testRemoteConnection(url: string, password: string, options: RemoteOptions = {}): Promise<RemoteConnectResult> {
+    const conn = new Connection(url, password, options);
     try {
-        await (await getRemoteFileStorage(url, password)("")).getKeys();
-        return { status: "ok" };
+        const r = await conn.request("GET", "/list", { path: "" });
+        if (r.status === 200) return { status: "ok" };
+        if (r.status === 401) return { status: "unauthorized" };
+        return { status: "unreachable", error: `server returned ${r.status}` };
     } catch (e) {
-        const msg = (e as Error)?.message || String(e);
-        // Our client throws "remote ... failed (NNN)" when it actually got an HTTP response (so the cert
-        // is trusted); a thrown fetch with no status means we never connected.
-        const m = msg.match(/\((\d{3})\)/);
-        if (m) return m[1] === "401" ? { status: "unauthorized" } : { status: "unreachable", error: msg };
-        return { status: "unreachable", error: msg };
+        return { status: "unreachable", error: (e as Error)?.message || String(e) };
     }
 }