sliftutils 1.4.10 → 1.4.12

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,9 @@ declare module "sliftutils/storage/FileFolderAPI" {
             }): Promise<PermissionState>;
         }
     }
-    type FileWrapper = {
+    export type FileWrapper = {
+        readonly kind: "file";
+        readonly name: string;
         getFile(): Promise<{
             size: number;
             lastModified: number;
@@ -1358,7 +1361,9 @@ declare module "sliftutils/storage/FileFolderAPI" {
             close(): Promise<void>;
         }>;
     };
-    type DirectoryWrapper = {
+    export type DirectoryWrapper = {
+        readonly kind: "directory";
+        readonly name: string;
         removeEntry(key: string, options?: {
             recursive?: boolean;
         }): Promise<void>;
@@ -1368,29 +1373,15 @@ declare module "sliftutils/storage/FileFolderAPI" {
         getDirectoryHandle(key: string, options?: {
             create?: boolean;
         }): Promise<DirectoryWrapper>;
-        [Symbol.asyncIterator](): AsyncIterableIterator<[
-            string,
-            {
-                kind: "file";
-                name: string;
-                getFile(): Promise<FileWrapper>;
-            } | {
-                kind: "directory";
-                name: string;
-                getDirectoryHandle(key: string, options?: {
-                    create?: boolean;
-                }): Promise<DirectoryWrapper>;
-            }
-        ]>;
+        entries(): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
+        [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
     };
     export declare function setFileAPIKey(key: string): void;
-    type RemoteConfig = {
-        url: string;
-        password: string;
-    };
     export declare class NodeJSFileHandleWrapper implements FileWrapper {
         private filePath;
         constructor(filePath: string);
+        readonly kind: "file";
+        get name(): string;
         getFile(): Promise<{
             size: number;
             lastModified: number;
@@ -1410,6 +1401,9 @@ declare module "sliftutils/storage/FileFolderAPI" {
     export declare class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
         private rootPath;
         constructor(rootPath: string);
+        readonly kind: "directory";
+        get name(): string;
+        entries(): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
         removeEntry(key: string, options?: {
             recursive?: boolean;
         }): Promise<void>;
@@ -1419,33 +1413,8 @@ declare module "sliftutils/storage/FileFolderAPI" {
         getDirectoryHandle(key: string, options?: {
             create?: boolean;
         }): Promise<DirectoryWrapper>;
-        [Symbol.asyncIterator](): AsyncIterableIterator<[
-            string,
-            {
-                kind: "file";
-                name: string;
-                getFile(): Promise<FileWrapper>;
-            } | {
-                kind: "directory";
-                name: string;
-                getDirectoryHandle(key: string, options?: {
-                    create?: boolean;
-                }): Promise<DirectoryWrapper>;
-            }
-        ]>;
+        [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
     }
-    type StorageChoice = {
-        type: "local";
-        handle: DirectoryWrapper;
-    } | {
-        type: "remote";
-        config: RemoteConfig;
-    };
-    export declare const getStorageChoice: {
-        (): Promise<StorageChoice>;
-        reset(): void;
-        set(newValue: Promise<StorageChoice>): void;
-    };
     export declare const getDirectoryHandle: {
         (): Promise<DirectoryWrapper>;
         reset(): void;
@@ -1483,8 +1452,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 {};
 
 }
 
@@ -1877,44 +1846,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";
@@ -1922,8 +1865,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.10",
+    "version": "1.4.12",
     "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,9 @@ declare global {
         }): Promise<PermissionState>;
     }
 }
-type FileWrapper = {
+export type FileWrapper = {
+    readonly kind: "file";
+    readonly name: string;
     getFile(): Promise<{
         size: number;
         lastModified: number;
@@ -44,7 +47,9 @@ type FileWrapper = {
         close(): Promise<void>;
     }>;
 };
-type DirectoryWrapper = {
+export type DirectoryWrapper = {
+    readonly kind: "directory";
+    readonly name: string;
     removeEntry(key: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
@@ -54,29 +59,15 @@ type DirectoryWrapper = {
     getDirectoryHandle(key: string, options?: {
         create?: boolean;
     }): Promise<DirectoryWrapper>;
-    [Symbol.asyncIterator](): AsyncIterableIterator<[
-        string,
-        {
-            kind: "file";
-            name: string;
-            getFile(): Promise<FileWrapper>;
-        } | {
-            kind: "directory";
-            name: string;
-            getDirectoryHandle(key: string, options?: {
-                create?: boolean;
-            }): Promise<DirectoryWrapper>;
-        }
-    ]>;
+    entries(): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
 };
 export declare function setFileAPIKey(key: string): void;
-type RemoteConfig = {
-    url: string;
-    password: string;
-};
 export declare class NodeJSFileHandleWrapper implements FileWrapper {
     private filePath;
     constructor(filePath: string);
+    readonly kind: "file";
+    get name(): string;
     getFile(): Promise<{
         size: number;
         lastModified: number;
@@ -96,6 +87,9 @@ export declare class NodeJSFileHandleWrapper implements FileWrapper {
 export declare class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
     private rootPath;
     constructor(rootPath: string);
+    readonly kind: "directory";
+    get name(): string;
+    entries(): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
     removeEntry(key: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
@@ -105,33 +99,8 @@ export declare class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
     getDirectoryHandle(key: string, options?: {
         create?: boolean;
     }): Promise<DirectoryWrapper>;
-    [Symbol.asyncIterator](): AsyncIterableIterator<[
-        string,
-        {
-            kind: "file";
-            name: string;
-            getFile(): Promise<FileWrapper>;
-        } | {
-            kind: "directory";
-            name: string;
-            getDirectoryHandle(key: string, options?: {
-                create?: boolean;
-            }): Promise<DirectoryWrapper>;
-        }
-    ]>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
 }
-type StorageChoice = {
-    type: "local";
-    handle: DirectoryWrapper;
-} | {
-    type: "remote";
-    config: RemoteConfig;
-};
-export declare const getStorageChoice: {
-    (): Promise<StorageChoice>;
-    reset(): void;
-    set(newValue: Promise<StorageChoice>): void;
-};
 export declare const getDirectoryHandle: {
     (): Promise<DirectoryWrapper>;
     reset(): void;
@@ -169,5 +138,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,13 @@ declare global {
 // DO NOT enable this is isNode
 const USE_INDEXED_DB = false;
 
-type FileWrapper = {
+// These mirror the subset of the native FileSystemFileHandle / FileSystemDirectoryHandle API we use, so
+// the native browser handles, the Node handles, and the remote handles are all interchangeable — and
+// code written against the native handle (e.g. a recursive walk over `handle.entries()`) works on any of
+// them. kind/name and entries() are part of that contract.
+export type FileWrapper = {
+    readonly kind: "file";
+    readonly name: string;
     getFile(): Promise<{
         size: number;
         lastModified: number;
@@ -51,19 +57,15 @@ type FileWrapper = {
         close(): Promise<void>;
     }>;
 };
-type DirectoryWrapper = {
+export type DirectoryWrapper = {
+    readonly kind: "directory";
+    readonly name: string;
     removeEntry(key: string, options?: { recursive?: boolean }): Promise<void>;
     getFileHandle(key: string, options?: { create?: boolean }): Promise<FileWrapper>;
     getDirectoryHandle(key: string, options?: { create?: boolean }): Promise<DirectoryWrapper>;
-    [Symbol.asyncIterator](): AsyncIterableIterator<[string, {
-        kind: "file";
-        name: string;
-        getFile(): Promise<FileWrapper>;
-    } | {
-        kind: "directory";
-        name: string;
-        getDirectoryHandle(key: string, options?: { create?: boolean }): Promise<DirectoryWrapper>;
-    }]>;
+    // Each entry IS a handle (file or directory), so a recursive walk keeps working at every level.
+    entries(): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]>;
 };
 
 let displayData = observable({
@@ -105,14 +107,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
@@ -134,12 +136,18 @@ class DirectoryPrompter extends preact.Component {
 }
 
 // "Connect to a server" option for the directory prompt: collapses to a button, expands to address +
-// password fields. On connect it actually connects to the server; on success it persists the config and
-// calls onConnected so the caller (getStorageChoice) resolves with the live remote storage — no reload.
-// Connection failures are shown to the user (and logged, without the password), never swallowed.
+// 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<{ onConnected: (config: RemoteConfig) => void }> {
-    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;
@@ -149,11 +157,11 @@ class ServerConnectForm extends preact.Component<{ onConnected: (config: RemoteC
         try {
             const url = this.cleanUrl();
             if (!url) { s.error = "Enter a server address."; return; }
-            const result = await probeRemoteConnection(url, s.password.trim());
+            const result = await testRemoteConnection(url, s.password.trim());
             if (result.status === "ok") {
                 const config: RemoteConfig = { url, password: s.password.trim() };
                 saveRemoteConfig(config);             // remember for next session
-                this.props.onConnected(config);       // resolve the pending storage request now (no reload)
+                this.props.onConnected(config);       // hand the verified server back to getDirectoryHandle
                 return;
             }
             if (result.status === "unauthorized") {
@@ -167,7 +175,6 @@ class ServerConnectForm extends preact.Component<{ onConnected: (config: RemoteC
                 console.error("Remote connect: unreachable", url, "-", result.error);
             }
         } catch (e) {
-            // Should be rare (probeRemoteConnection handles its own errors), but never swallow it.
             s.error = "Connection error: " + ((e as Error).message || String(e));
             console.error("Remote connect threw:", e);
         } finally {
@@ -217,6 +224,8 @@ class ServerConnectForm extends preact.Component<{ onConnected: (config: RemoteC
 export class NodeJSFileHandleWrapper implements FileWrapper {
     constructor(private filePath: string) {
     }
+    readonly kind = "file" as const;
+    get name() { return path.basename(this.filePath); }
 
     async getFile() {
         const stats = await fs.promises.stat(this.filePath);
@@ -280,6 +289,9 @@ export class NodeJSFileHandleWrapper implements FileWrapper {
 export class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
     constructor(private rootPath: string) {
     }
+    readonly kind = "directory" as const;
+    get name() { return path.basename(this.rootPath); }
+    entries() { return this[Symbol.asyncIterator](); }
 
     async removeEntry(key: string, options?: { recursive?: boolean }) {
         const entryPath = path.join(this.rootPath, key);
@@ -327,63 +339,48 @@ export class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
         return new NodeJSDirectoryHandleWrapper(dirPath);
     }
 
-    async *[Symbol.asyncIterator](): AsyncIterableIterator<[string, {
-        kind: "file";
-        name: string;
-        getFile(): Promise<FileWrapper>;
-    } | {
-        kind: "directory";
-        name: string;
-        getDirectoryHandle(key: string, options?: { create?: boolean }): Promise<DirectoryWrapper>;
-    }]> {
+    async *[Symbol.asyncIterator](): AsyncIterableIterator<[string, FileWrapper | DirectoryWrapper]> {
         // Ensure directory exists
         await fs.promises.mkdir(this.rootPath, { recursive: true });
 
         const entries = await fs.promises.readdir(this.rootPath, { withFileTypes: true });
 
         for (const entry of entries) {
+            const childPath = path.join(this.rootPath, entry.name);
             if (entry.isFile()) {
-                yield [entry.name, {
-                    kind: "file",
-                    name: entry.name,
-                    getFile: async () => new NodeJSFileHandleWrapper(path.join(this.rootPath, entry.name))
-                }];
+                yield [entry.name, new NodeJSFileHandleWrapper(childPath)];
             } else if (entry.isDirectory()) {
-                const dirPath = path.join(this.rootPath, entry.name);
-                yield [entry.name, {
-                    kind: "directory",
-                    name: entry.name,
-                    getDirectoryHandle: async (key: string, options?: { create?: boolean }) => {
-                        return new NodeJSDirectoryHandleWrapper(dirPath).getDirectoryHandle(key, options);
-                    }
-                }];
+                yield [entry.name, new NodeJSDirectoryHandleWrapper(childPath)];
             }
         }
     }
 }
 
 
-// What storage the user chose: a local directory handle, or a remote server config.
-type StorageChoice = { type: "local"; handle: DirectoryWrapper } | { type: "remote"; config: RemoteConfig };
-
-// Resolves (once) what storage to use. If a remote server was connected in a previous session we use it
-// straight away; otherwise we prompt (Pick directory / Connect to a server / Dismiss). The Connect path
-// actually connects to the server and resolves with its config — so when this returns, the storage is
-// ready. No page reload. Blocks until the user chooses (or dismisses, which rejects).
-export const getStorageChoice = lazy(async function getStorageChoice(): Promise<StorageChoice> {
+// 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 { type: "local", handle: new NodeJSDirectoryHandleWrapper(path.resolve("./data/")) };
+        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) return { type: "remote", config: savedRemote };
+    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 resolveChoice!: (c: StorageChoice) => void;
-        let rejectChoice!: (e: Error) => void;
-        const choicePromise = new Promise<StorageChoice>((res, rej) => { resolveChoice = res; rejectChoice = rej; });
+        let resolveHandle!: (h: DirectoryWrapper) => void;
+        let rejectHandle!: (e: Error) => void;
+        const promise = new Promise<DirectoryWrapper>((res, rej) => { resolveHandle = res; rejectHandle = rej; });
 
         const pickLocal = async () => {
             try {
@@ -391,30 +388,33 @@ export const getStorageChoice = lazy(async function getStorageChoice(): Promise<
                 await handle.requestPermission({ mode: "readwrite" });
                 const storedId = await storeFileSystemPointer({ mode: "readwrite", handle });
                 localStorage.setItem(getFileAPIKey(), storedId);
-                resolveChoice({ type: "local", handle: handle as any });
+                resolveHandle(handle as any);
             } catch (e) {
                 console.error("Directory pick failed/cancelled:", e); // stay on the prompt
             }
         };
-        // The three options, rendered fresh each time (so reused-vnode issues can't arise).
+        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={config => resolveChoice({ type: "remote", config })} />
+                <ServerConnectForm onConnected={onConnected} initial={savedRemote} />
                 <button className={css.fontSize(40).pad2(80, 40)}
-                    onClick={() => rejectChoice(new Error("User dismissed file system access prompt"))}>Dismiss</button>
+                    onClick={() => rejectHandle(new Error("User dismissed file system access prompt"))}>Dismiss</button>
             </>
         );
 
-        // A previously-picked local folder: try to restore its handle (may need a click for activation).
-        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) displayData.ui = "Click anywhere to allow file system access"; }, 500);
             try {
                 const handle = await tryToLoadPointer(storedId);
                 doneLoad = true;
-                if (handle) return { type: "local", handle };
+                if (handle) return handle;
             } catch (e) {
                 doneLoad = true;
                 console.error(e);
@@ -426,37 +426,27 @@ export const getStorageChoice = lazy(async function getStorageChoice(): Promise<
                                 displayData.ui = "Loading...";
                                 try {
                                     const h = await tryToLoadPointer(storedId);
-                                    if (h) { resolveChoice({ type: "local", handle: h }); return; }
+                                    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>
                     );
-                    return await choicePromise;
+                    return await promise;
                 }
             }
         }
         displayData.ui = <div className={css.vbox(20).center}>{renderOptions()}</div>;
-        return await choicePromise;
+        return await promise;
     } finally {
         preact.render(null, root);
         root.remove();
     }
 });
 
-// Local-only directory handle, for callers that don't support remote storage. Throws if the user has
-// configured a remote server (rather than silently doing the wrong thing).
-export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Promise<DirectoryWrapper> {
-    const choice = await getStorageChoice();
-    if (choice.type === "remote") throw new Error("Storage is configured to use a remote server; a local directory handle isn't available here.");
-    return choice.handle;
-});
-
 export const getFileStorageNested = cache(async function getFileStorage(path: string): Promise<FileStorage> {
-    const choice = await getStorageChoice();
-    if (choice.type === "remote") return getRemoteFactory(choice.config)(path);
-    let base = choice.handle;
+    let base = await getDirectoryHandle();
     for (let part of path.split("/")) {
         if (!part) continue;
         base = await base.getDirectoryHandle(part, { create: true });
@@ -473,9 +463,7 @@ export const getFileStorageNested2 = cache(async function getFileStorage(pathStr
         }
         base = new NodeJSDirectoryHandleWrapper(path.resolve("./data/"));
     } else {
-        const choice = await getStorageChoice();
-        if (choice.type === "remote") return getRemoteFactory(choice.config)(pathStr);
-        base = choice.handle;
+        base = await getDirectoryHandle();
         let dirs: string[] = [];
         let alls: string[] = [];
         for await (const [name, entry] of base) {
@@ -499,9 +487,8 @@ export const getFileStorage = lazy(async function getFileStorage(): Promise<File
     if (USE_INDEXED_DB) {
         return await getFileStorageIndexDB();
     }
-    const choice = await getStorageChoice();
-    if (choice.type === "remote") return getRemoteFactory(choice.config)("");
-    return wrapHandle(choice.handle);
+    let handle = await getDirectoryHandle();
+    return wrapHandle(handle);
 });
 export function resetStorageLocation() {
     localStorage.removeItem(getFileAPIKey());
@@ -715,6 +702,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 };
+
+// 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(/\/+$/, "");
+    }
 
-    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) }));
+    // 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,112 @@ 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 baseName = (p: string) => p.split("/").filter(Boolean).pop() || "";
 
-    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"));
-        },
-    };
+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) { }
+    // Mirror the native FileSystemFileHandle shape so code written against it works unchanged.
+    readonly kind = "file" as const;
+    get name() { return baseName(this.filePath); }
+    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);
+            },
+        };
+    }
+}
 
-    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 RemoteDirectoryWrapper implements DirectoryWrapper {
+    constructor(private conn: Connection, private dirPath: string) { }
+    // Mirror the native FileSystemDirectoryHandle shape (name/kind/entries) so code written against the
+    // native API — e.g. recursive walks using `handle.entries()` — works the same over the network.
+    readonly kind = "directory" as const;
+    get name() { return baseName(this.dirPath); }
+    async removeEntry(key: string): Promise<void> {
+        await this.conn.remove(joinPath(this.dirPath, key));
+    }
+    async getFileHandle(key: string, options?: { create?: boolean }): Promise<RemoteFileWrapper> {
+        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<RemoteDirectoryWrapper> {
+        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
+    }
+    // Each entry is itself a real handle (a sub-wrapper), so a recursive walk over .entries() keeps
+    // working at every level — exactly like the native API.
+    async *[Symbol.asyncIterator](): AsyncIterableIterator<[string, RemoteFileWrapper | RemoteDirectoryWrapper]> {
+        const entries = await this.conn.list(this.dirPath);
+        for (const e of entries) {
+            const childPath = joinPath(this.dirPath, e.name);
+            yield [e.name, e.dir ? new RemoteDirectoryWrapper(this.conn, childPath) : new RemoteFileWrapper(this.conn, childPath)];
+        }
+    }
+    entries() { return this[Symbol.asyncIterator](); }
+    keys() { return mapAsync(this[Symbol.asyncIterator](), ([name]) => name); }
+    values() { return mapAsync(this[Symbol.asyncIterator](), ([, handle]) => handle); }
 }
 
-export type RemoteStorageFactory = ((path: string) => Promise<FileStorage>) & { stats: Connection["stats"] };
+async function* mapAsync<T, U>(it: AsyncIterableIterator<T>, fn: (v: T) => U): AsyncIterableIterator<U> {
+    for await (const v of it) yield fn(v);
+}
 
-// 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) };
     }
 }