libfw-client 0.1.1 → 0.1.3

package/README.md

@@ -15,7 +15,9 @@ const client = new LibfwClient({
   onEvent: (e) => console.log(e), // { type: 'progress', done, total }
 });
 
-// Download a whole folder (showDirectoryPicker, preserves structure)
+// Download a whole folder. Uses showDirectoryPicker when the File System
+// Access API is available; otherwise the folder is zipped and saved via a
+// traditional browser download — no feature detection needed by the caller.
 await client.downloadFolder('your_token_here');
 
 // Upload a FileList
@@ -33,10 +35,13 @@ client.cancel();
 
 ## How it works
 
-- `downloadFolder(token, dirPath?)` — the engine lists the folder on the
-  server (recursively), then downloads each file with `Range`/`If-Range`
-  resume, decompresses the zrip stream, and pushes `Uint8Array` chunks to
-  the SDK, which writes them with `fileHandle.createWritable()`.
+- `downloadFolder(token, dirPath?)` / `downloadFile(token, filePath)` — the
+  engine lists (for folders) and downloads each file with `Range`/`If-Range`
+  resume, decompresses the zrip stream, and pushes `Uint8Array` chunks to the
+  SDK. With the File System Access API the SDK streams them to disk via
+  `fileHandle.createWritable()`; without it (or with `downloadMode: 'browser'`)
+  the SDK buffers the chunks and saves the result through a traditional
+  browser download — a single file as-is, a folder packed into a `.zip`.
 - `upload(token, files?)` — the engine slices each file into fixed-size
   chunks, reads them via `readFile`, compresses each chunk into one zstd
   frame, and POSTs them with `x-libfw-offset` for server-side resume
@@ -61,6 +66,7 @@ The resulting package contains:
 ```
 pkg/                  wasm-pack output (wasm + wasm-bindgen web glue)
 index.js              ESM SDK
+zip.js                dependency-free ZIP writer (browser-download fallback)
 index.d.ts            TypeScript types
 dist/libfw-client.umd.js   UMD bundle (after build:umd)
 ```
@@ -68,8 +74,18 @@ dist/libfw-client.umd.js   UMD bundle (after build:umd)
 ## API
 
 - `new LibfwClient(options?)`
+  - `downloadMode: 'auto' | 'fs' | 'browser'` (default `'auto'`) — `'fs'`
+    streams downloads through the File System Access API; `'browser'` buffers
+    and triggers a traditional browser download (folders become `.zip`);
+    `'auto'` uses `'fs'` when the API exists and falls back to `'browser'`.
+  - `maxFallbackBytes: number` (default `536870912`, 512 MiB) — memory cap
+    for the in-memory `'browser'` fallback. File sizes are pre-checked
+    against it before buffering; a download that would exceed it rejects
+    with a `too-large` `LibfwError` instead of risking an OOM. `0` disables.
 - `downloadFolder(token, dirPath?) → Promise<number>`
+- `downloadFile(token, filePath) → Promise<number>`
 - `upload(token, files?) → Promise<number>`
+- `clearResumeStore(direction?) → Promise<number>`
 - `pause()`, `resume()`, `cancel()`
 - `state()`, `progress()`, `doneBytes()`, `totalBytes()`
 - Errors: every rejection is a `LibfwError` with a stable `code`.

package/index.d.ts

@@ -16,7 +16,8 @@ export type LibfwErrorCode =
   | 'decompress'
   | 'compress'
   | 'protocol'
-  | 'cancelled';
+  | 'cancelled'
+  | 'too-large';
 
 /** Uniform error type thrown by every SDK operation. */
 export declare class LibfwError extends Error {
@@ -65,6 +66,27 @@ export interface LibfwClientOptions {
   maxRetryDelayMs?: number;
   /** Per-request timeout (ms). Default `60000`. */
   timeoutMs?: number;
+  /**
+   * Explicit URL of `libfw_client_bg.wasm`. When omitted it is resolved
+   * automatically for both ESM and classic-`<script>`/UMD consumers.
+   */
+  wasmUrl?: string;
+  /**
+   * How downloads reach the user's disk.
+   *
+   * - `'fs'` — File System Access API (`showDirectoryPicker`), streaming to disk.
+   * - `'browser'` — buffer each file, then trigger a traditional browser
+   *   download; folders are packed into a `.zip` archive.
+   * - `'auto'` (default) — `'fs'` when the API exists, else `'browser'`.
+   */
+  downloadMode?: 'auto' | 'fs' | 'browser';
+  /**
+   * Memory cap (bytes) for the in-memory `'browser'` download fallback.
+   * File sizes are pre-checked against it before buffering; a download that
+   * would exceed it is rejected with a `too-large` error. `0` disables the
+   * limit. Default `536870912` (512 MiB).
+   */
+  maxFallbackBytes?: number;
   /** Optional progress/state listener. */
   onEvent?: (event: LibfwEvent) => void;
 }
@@ -94,6 +116,16 @@ export declare class LibfwClient {
    */
   downloadFolder(token: string, dirPath?: string): Promise<number>;
 
+  /**
+   * Download a single file from the server at `filePath` into a user-selected
+   * local directory.
+   *
+   * @param token bearer token
+   * @param filePath virtual server path of the file to download
+   * @returns total bytes written
+   */
+  downloadFile(token: string, filePath: string): Promise<number>;
+
   /**
    * Upload files to the server.
    *
@@ -132,6 +164,17 @@ export declare class LibfwClient {
 
   /** Total bytes to transfer. */
   totalBytes(): number;
+
+  /**
+   * Delete persisted resume state (IndexedDB).
+   *
+   * Pass a direction to wipe only that transfer's state (`'download'` or
+   * `'upload'`); omit it to clear the whole store.
+   *
+   * @param direction restrict the wipe to one transfer direction
+   * @returns number of records removed
+   */
+  clearResumeStore(direction?: 'upload' | 'download'): Promise<number>;
 }
 
 export default LibfwClient;

package/index.js

@@ -4,7 +4,10 @@
  * A thin, dependency-free wrapper around the libfw WASM engine that owns:
  *  - WASM instantiation (via the wasm-bindgen `web` glue),
  *  - the File System Access API (`showDirectoryPicker`, `getFileHandle`,
- *    `createWritable`),
+ *    `createWritable`) for streaming downloads,
+ *  - a traditional browser-download fallback when the File System Access API
+ *    is unavailable: single files download directly, folders are packed into
+ *    a `.zip` archive (see `downloadMode`),
  *  - IndexedDB resume-state persistence,
  *  - converting engine callbacks (`onWriteChunk`, `getFileList`, …) into
  *    real file I/O.
@@ -16,6 +19,7 @@
  */
 
 import init, { LibfwClient as WasmEngine } from './pkg/libfw_client.js';
+import { createZip } from './zip.js';
 
 /** Database / store names used by the IndexedDB resume-state layer. */
 const IDB_NAME = 'libfw';
@@ -106,6 +110,47 @@ const Idb = {
       tx.onerror = () => reject(new LibfwError(`idb put: ${tx.error}`, 'idb'));
     });
   },
+
+  /**
+   * Delete every key whose `direction:` prefix matches (e.g. all
+   * `download:*` keys) while leaving the other direction intact.
+   * @param {string} direction `'upload'` | `'download'`
+   * @returns {Promise<number>} number of records removed
+   */
+  async clearDirection(direction) {
+    const db = await Idb.open();
+    const prefix = `${direction}:`;
+    const keys = await new Promise((resolve, reject) => {
+      const tx = db.transaction(IDB_STORE, 'readonly');
+      const req = tx.objectStore(IDB_STORE).getAllKeys();
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(new LibfwError(`idb keys: ${req.error}`, 'idb'));
+    });
+    const matches = keys.filter((key) => String(key).startsWith(prefix));
+    if (matches.length === 0) return 0;
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(IDB_STORE, 'readwrite');
+      const store = tx.objectStore(IDB_STORE);
+      for (const key of matches) store.delete(key);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(new LibfwError(`idb clear direction: ${tx.error}`, 'idb'));
+    });
+    return matches.length;
+  },
+
+  /**
+   * Wipe the whole resume store.
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    const db = await Idb.open();
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(IDB_STORE, 'readwrite');
+      tx.objectStore(IDB_STORE).clear();
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(new LibfwError(`idb clear: ${tx.error}`, 'idb'));
+    });
+  },
 };
 
 /** Split a POSIX virtual path into segments. */
@@ -123,6 +168,22 @@ function splitPath(path) {
  * await client.downloadFolder('your_token_here');
  * await client.upload('your_token_here', fileInput.files);
  */
+
+/**
+ * `<script src>` of the bundle that is currently evaluating this module.
+ *
+ * `document.currentScript` is only non-null during a classic script's
+ * synchronous evaluation, so it is captured here once, at load time, rather
+ * than read later from an async callback (where it would already be `null`).
+ * In ESM this is `null` (modules never set `currentScript`), which is
+ * correct — the ESM path resolves the `.wasm` via `import.meta.url` instead.
+ * @type {string|null}
+ */
+const BUNDLE_SCRIPT_SRC =
+  typeof document !== 'undefined' && document.currentScript && document.currentScript.src
+    ? document.currentScript.src
+    : null;
+
 export class LibfwClient {
   /**
    * @param {object} [options]
@@ -134,6 +195,20 @@ export class LibfwClient {
    * @param {number} [options.baseRetryDelayMs=500] initial backoff (ms)
    * @param {number} [options.maxRetryDelayMs=30000] backoff ceiling (ms)
    * @param {number} [options.timeoutMs=60000] per-request timeout (ms)
+   * @param {string} [options.wasmUrl] explicit URL of `libfw_client_bg.wasm`;
+   *        when omitted it is resolved automatically for both ESM and
+   *        classic-`<script>`/UMD consumers (see {@link LibfwClient#_wasmUrl})
+   * @param {'auto'|'fs'|'browser'} [options.downloadMode='auto'] how downloads
+   *        reach the user's disk: `'fs'` uses the File System Access API
+   *        (`showDirectoryPicker`); `'browser'` buffers each file and triggers
+   *        a traditional browser download (folders are packed into a `.zip`);
+   *        `'auto'` picks `'fs'` when the API exists, otherwise `'browser'`.
+   * @param {number} [options.maxFallbackBytes=536870912] memory cap (bytes)
+   *        for the in-memory `'browser'` download fallback. Each file's size
+   *        (and the cumulative buffered total) is pre-checked against it
+   *        before any bytes are buffered; a download that would exceed it is
+   *        rejected with a `too-large` error instead of risking an OOM.
+   *        `0` disables the limit.
    * @param {(event: {type: string, done: number, total: number, path?: string, error?: string}) => void} [options.onEvent]
    *        optional progress/state listener
    */
@@ -147,6 +222,9 @@ export class LibfwClient {
       baseRetryDelayMs: 500,
       maxRetryDelayMs: 30000,
       timeoutMs: 60000,
+      wasmUrl: null,
+      downloadMode: 'auto',
+      maxFallbackBytes: 512 * 1024 * 1024,
       onEvent: null,
       ...options,
     };
@@ -158,12 +236,17 @@ export class LibfwClient {
     this._dirHandle = null;
     /** @type {Map<string, FileSystemFileHandle>} path → file handle */
     this._fileHandles = new Map();
-    /** @type {Map<string, FileSystemWritableFileStream>} path → writable stream */
+    /** @type {Map<string, FileSystemWritableFileStream>} path → open writable stream */
     this._writables = new Map();
     /** @type {Map<string, File>} path → File (upload) */
     this._uploadFiles = new Map();
     /** @type {Array<{path:string,size:number,mtime:number}>} upload plan */
     this._uploadPlan = [];
+    /**
+     * Active browser-download fallback state, or `null`.
+     * @type {{isFolder:boolean, buffers:Map<string,Uint8Array[]>, order:string[], sizes:Map<string,number>}|null}
+     */
+    this._fallback = null;
   }
 
   // ------------------------------------------------------------------ setup
@@ -176,7 +259,12 @@ export class LibfwClient {
   async _ready() {
     if (this._engine) return this._engine;
     if (!this._initPromise) {
-      this._initPromise = init().catch((err) => {
+      // Always pass the .wasm location explicitly so the generated glue's
+      // ESM-only `import.meta.url` fallback is never exercised — that
+      // fallback throws when the SDK is bundled for a classic <script>/UMD
+      // context. See _wasmUrl() for how the URL is resolved. The
+      // `{ module_or_path }` object form is the glue's non-deprecated API.
+      this._initPromise = init({ module_or_path: this._wasmUrl() }).catch((err) => {
         this._initPromise = null;
         throw toLibfwError(err);
       });
@@ -196,6 +284,31 @@ export class LibfwClient {
     return engine;
   }
 
+  /**
+   * Resolve the `.wasm` file URL without relying on `import.meta` (which is
+   * ESM-only and a parse error in a classic `<script>`).
+   *
+   * Order: explicit `wasmUrl` option → classic-script `document.currentScript`
+   * → ESM `import.meta.url`. The `wasmUrl` option is the escape hatch for
+   * deployments where neither auto-detection applies.
+   * @returns {string|URL}
+   * @private
+   */
+  _wasmUrl() {
+    if (this._options.wasmUrl) return this._options.wasmUrl;
+    // Classic <script> / UMD: the bundle's own <script src> (captured at load
+    // time in BUNDLE_SCRIPT_SRC) tells us where the sibling `.wasm` lives.
+    if (BUNDLE_SCRIPT_SRC) {
+      return new URL('libfw_client_bg.wasm', BUNDLE_SCRIPT_SRC);
+    }
+    // ESM: relative to this module.
+    if (typeof import.meta !== 'undefined' && import.meta.url) {
+      return new URL('./pkg/libfw_client_bg.wasm', import.meta.url);
+    }
+    // Last resort: same-origin relative path.
+    return 'libfw_client_bg.wasm';
+  }
+
   /**
    * Build the callbacks object handed to the WASM engine.
    * @returns {object}
@@ -203,12 +316,42 @@ export class LibfwClient {
    */
   _makeCallbacks() {
     return {
-      onFileStart: (path, size) => this._emit({ type: 'fileStart', path, done: 0, total: size }),
+      onFileStart: (path, size) => {
+        if (this._fallback) {
+          this._fallback.sizes.set(path, size);
+          // Pre-check the in-memory cap BEFORE any bytes are buffered so an
+          // oversized download is rejected instead of exhausting memory.
+          const max = this._maxFallbackBytes();
+          if (max > 0) {
+            if (size > max) {
+              throw new LibfwError(
+                `file too large for browser download (${size} > ${max} bytes): ${path}`,
+                'too-large'
+              );
+            }
+            this._fallback.total += size;
+            if (this._fallback.total > max) {
+              throw new LibfwError(
+                `browser download would buffer more than the ${max}-byte in-memory limit`,
+                'too-large'
+              );
+            }
+          }
+        }
+        this._emit({ type: 'fileStart', path, done: 0, total: size });
+      },
       onWriteChunk: (path, offset, data) => this._onWriteChunk(path, offset, data),
-      onFileCompleted: (path) => this._emit({ type: 'fileCompleted', path }),
+      onFileCompleted: (path) => this._onFileCompleted(path),
       onProgress: (done, total) => this._emit({ type: 'progress', done, total }),
       loadState: (direction, path) => Idb.loadState(`${direction}:${path}`),
-      saveState: (direction, path, state) => Idb.saveState(`${direction}:${path}`, state),
+      saveState: (direction, path, state) => {
+        // The in-memory browser-download fallback never commits bytes to
+        // disk, so a persisted download offset would be a phantom that
+        // poisons a later FS-API resume. Skip persisting download state
+        // while a fallback transfer is active.
+        if (direction === 'download' && this._fallback) return Promise.resolve();
+        return Idb.saveState(`${direction}:${path}`, state);
+      },
       getFileList: () => this._getFileList(),
       readFile: (path, offset, length) => this._readFile(path, offset, length),
       log: (msg) => {
@@ -228,24 +371,54 @@ export class LibfwClient {
     }
   }
 
+  /**
+   * Whether the File System Access API is available in this browser.
+   * @returns {boolean}
+   * @private
+   */
+  _supportsFsAccess() {
+    return (
+      typeof window !== 'undefined' &&
+      typeof window.showDirectoryPicker === 'function' &&
+      typeof FileSystemFileHandle !== 'undefined' &&
+      typeof FileSystemDirectoryHandle !== 'undefined'
+    );
+  }
+
+  /**
+   * Resolve the effective download mode from the `downloadMode` option:
+   * an explicit `'fs'`/`'browser'` wins; `'auto'` falls back to the browser
+   * download when the File System Access API is missing.
+   * @returns {'fs'|'browser'}
+   * @private
+   */
+  _effectiveMode() {
+    const mode = this._options.downloadMode || 'auto';
+    if (mode === 'fs' || mode === 'browser') return mode;
+    return this._supportsFsAccess() ? 'fs' : 'browser';
+  }
+
   // ------------------------------------------------------------ downloads
 
   /**
-   * Download a whole folder from the server into a local directory chosen
-   * by the user via `showDirectoryPicker()`.
+   * Download a whole folder from the server.
    *
-   * Folder structure (including nested directories) is preserved; bytes
-   * are streamed to disk through `createWritable({ type: 'write' })`.
+   * With the File System Access API available the folder is streamed into a
+   * user-selected local directory (`showDirectoryPicker`), preserving the
+   * structure through one `createWritable()` per file. Without FS API (or
+   * with `downloadMode: 'browser'`) the folder is buffered in memory, packed
+   * into a `.zip` and saved via a traditional browser download — no manual
+   * feature detection needed by the caller.
    *
    * @param {string} token bearer token
    * @param {string} [dirPath=''] virtual server path to download (root by default)
-   * @returns {Promise<number>} total bytes written
+   * @returns {Promise<number>} total bytes transferred
    * @throws {LibfwError}
    */
   async downloadFolder(token, dirPath = '') {
     const engine = await this._ready();
-    if (typeof window === 'undefined' || typeof window.showDirectoryPicker !== 'function') {
-      throw new LibfwError('File System Access API is not available in this browser', 'unsupported');
+    if (this._effectiveMode() === 'browser') {
+      return this._downloadViaBrowser(engine, token, dirPath, true);
     }
     this._dirHandle = await window.showDirectoryPicker();
     this._fileHandles.clear();
@@ -255,41 +428,283 @@ export class LibfwClient {
       throw toLibfwError(err);
     } finally {
       await this._flushWritables();
+      await this._syncResumeOffsets();
     }
   }
 
   /**
+   * Download a single file from the server at `filePath`.
+   *
+   * With the File System Access API available the file is streamed into the
+   * directory chosen via `showDirectoryPicker()`. Without FS API (or with
+   * `downloadMode: 'browser'`) the file is buffered and saved through a
+   * traditional browser download.
+   *
+   * @param {string} token bearer token
+   * @param {string} filePath virtual server path of the file to download
+   * @returns {Promise<number>} total bytes transferred
+   * @throws {LibfwError}
+   */
+  async downloadFile(token, filePath) {
+    const engine = await this._ready();
+    if (!filePath) throw new LibfwError('downloadFile requires a file path', 'path');
+    if (this._effectiveMode() === 'browser') {
+      return this._downloadViaBrowser(engine, token, filePath, false);
+    }
+    this._dirHandle = await window.showDirectoryPicker();
+    this._fileHandles.clear();
+    try {
+      return await engine.download_file(this._options.baseUrl, token, filePath);
+    } catch (err) {
+      throw toLibfwError(err);
+    } finally {
+      await this._flushWritables();
+      await this._syncResumeOffsets();
+    }
+  }
+
+  /**
+   * Buffer-chunk fallback download used when the File System Access API is
+   * unavailable (or `downloadMode: 'browser'`).
+   *
+   * `onWriteChunk` chunks are collected per path in memory (the engine keeps
+   * calling them in order). When the transfer finishes: a single file is
+   * emitted as a `Blob` and saved via a normal browser download; a folder is
+   * packed into a `.zip` (STORE method) and downloaded. Progress/state events
+   * keep flowing as usual. Note this buffers the whole transfer in memory —
+   * the cost of not having FS API to stream to disk.
+   *
+   * @param {WasmEngine} engine
+   * @param {string} token
    * @param {string} path virtual path
-   * @param {number} offset byte offset
+   * @param {boolean} isFolder
+   * @returns {Promise<number>} total bytes transferred
+   * @private
+   */
+  async _downloadViaBrowser(engine, token, path, isFolder) {
+    this._fallback = { isFolder, buffers: new Map(), order: [], sizes: new Map(), total: 0 };
+    try {
+      const total = isFolder
+        ? await engine.download_folder(this._options.baseUrl, token, path)
+        : await engine.download_file(this._options.baseUrl, token, path);
+      const { buffers, order, sizes } = this._fallback;
+      if (isFolder) {
+        const entries = [];
+        for (const p of order) {
+          entries.push({
+            name: this._safeEntryName(p),
+            data: this._concatBuffers(buffers.get(p) || []),
+          });
+        }
+        // Include files that were announced but produced no bytes (empty).
+        for (const p of sizes.keys()) {
+          if (!buffers.has(p)) {
+            entries.push({ name: this._safeEntryName(p), data: new Uint8Array(0) });
+          }
+        }
+        this._triggerBrowserDownload(createZip(entries), this._archiveName(path));
+      } else {
+        const data = this._concatBuffers(buffers.get(path) || []);
+        this._triggerBrowserDownload(new Blob([data], { type: 'application/octet-stream' }), this._downloadName(path));
+      }
+      return total;
+    } catch (err) {
+      throw toLibfwError(err);
+    } finally {
+      this._fallback = null;
+    }
+  }
+
+  /**
+   * Concatenate buffered chunks into one `Uint8Array`.
+   * @param {Uint8Array[]} bufs
+   * @returns {Uint8Array}
+   * @private
+   */
+  _concatBuffers(bufs) {
+    if (bufs.length === 0) return new Uint8Array(0);
+    if (bufs.length === 1) return bufs[0];
+    const len = bufs.reduce((n, b) => n + b.length, 0);
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const b of bufs) {
+      out.set(b, off);
+      off += b.length;
+    }
+    return out;
+  }
+
+  /**
+   * Strip a leading `/` so an entry path is archive/OS friendly.
+   * @param {string} path
+   * @returns {string}
+   * @private
+   */
+  _cleanPath(path) {
+    return String(path).replace(/^\/+/, '');
+  }
+
+  /**
+   * Validate a virtual path for use as a ZIP entry name, rejecting any
+   * traversal (`..`), absolute/drive-letter prefixes or Windows-style
+   * separators that could escape the archive on extraction (zip-slip).
+   * @param {string} path
+   * @returns {string}
+   * @private
+   */
+  _safeEntryName(path) {
+    const cleaned = this._cleanPath(path);
+    const segs = String(cleaned).split('/');
+    if (segs.some((seg) => seg === '..' || seg.includes('\\') || /^[a-zA-Z]:/.test(seg))) {
+      throw new LibfwError(`unsafe path in download: ${path}`, 'path');
+    }
+    return cleaned;
+  }
+
+  /**
+   * The configured in-memory cap for the browser-download fallback.
+   * @returns {number} 0 disables the limit.
+   * @private
+   */
+  _maxFallbackBytes() {
+    const max = Number(this._options.maxFallbackBytes);
+    return Number.isFinite(max) && max > 0 ? max : 0;
+  }
+
+  /**
+   * Derive a safe file name from a virtual path.
+   * @param {string} path
+   * @returns {string}
+   * @private
+   */
+  _downloadName(path) {
+    const name = this._cleanPath(path).split('/').pop();
+    return name || 'download';
+  }
+
+  /**
+   * Derive the `.zip` archive name for a folder download.
+   * @param {string} path
+   * @returns {string}
+   * @private
+   */
+  _archiveName(path) {
+    const base = this._cleanPath(path).split('/').pop() || 'download';
+    return `${base.replace(/[^\w.\- ]+/g, '_') || 'download'}.zip`;
+  }
+
+  /**
+   * Trigger a traditional browser download via a temporary `<a download>`.
+   * @param {Blob} blob
+   * @param {string} filename
+   * @returns {void}
+   * @private
+   */
+  _triggerBrowserDownload(blob, filename) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    // Revoke once the download has had a chance to start.
+    setTimeout(() => URL.revokeObjectURL(url), 60000);
+  }
+
+  /**
+   * Stream a decompressed chunk to disk, keeping memory bounded regardless
+   * of file size (no whole-file buffering).
+   *
+   * The destination writable is opened exactly once per file and written in
+   * **append mode** (`writable.write(data)` without an explicit `position`).
+   * The engine awaits this callback, so chunks for a file arrive strictly in
+   * order, making append writes correct for both fresh and resumed
+   * downloads. Crucially, this avoids per-write
+   * `{ type: 'write', position }` calls, which in Chromium can spawn a fresh
+   * `.crswap` swap file per write and leave the target file empty on close —
+   * the single `createWritable()` + sequential writes + one `close()` below
+   * commits the swap file atomically.
+   * @param {string} path virtual path
+   * @param {number} offset byte offset (informational; writes append)
    * @param {Uint8Array} data decompressed chunk
    * @returns {Promise<void>}
    * @private
    */
   async _onWriteChunk(path, offset, data) {
-    let writable = this._writables.get(path);
-    if (!writable) {
-      const handle = await this._ensureFileHandle(path);
+    if (this._fallback) {
+      // Browser-download fallback: collect chunks in memory instead of
+      // streaming to disk. Chunks arrive in order, so a plain append works.
+      let bufs = this._fallback.buffers.get(path);
+      if (!bufs) {
+        bufs = [];
+        this._fallback.buffers.set(path, bufs);
+        this._fallback.order.push(path);
+      }
+      bufs.push(data);
+      return;
+    }
+    let entry = this._writables.get(path);
+    if (!entry) {
+      const { dir, name, handle } = await this._ensureFileHandle(path);
       this._fileHandles.set(path, handle);
-      // Only a true resume (first chunk arrives at offset > 0) needs to
-      // keep the existing file's prefix. For a fresh download we open the
-      // writable WITHOUT keepExistingData, which truncates and lets us
-      // write sequentially. In real Chromium the keepExistingData +
-      // position-write path can leave empty target files behind a trail of
-      // orphaned `.crswap` swap files, so we avoid it unless required.
+      // A true resume (first chunk at offset > 0) keeps the existing prefix
+      // on disk; a fresh download opens a truncating writable.
       const isResume = offset > 0;
-      writable = await handle.createWritable(
+      if (!isResume) {
+        // Remove any orphaned `.crswap` left behind by a crashed/aborted run
+        // so a stale swap file can never shadow the new write.
+        await this._removeSwapFile(dir, name);
+      }
+      const writable = await handle.createWritable(
         isResume ? { keepExistingData: true } : undefined
       );
-      this._writables.set(path, writable);
+      entry = { writable, dir, name };
+      this._writables.set(path, entry);
+    }
+    await entry.writable.write(data);
+  }
+
+  /**
+   * Close the destination writable once a file's transfer completes.
+   * @param {string} path virtual path
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _onFileCompleted(path) {
+    if (this._fallback) {
+      // Nothing is open to flush in browser-download mode.
+      this._emit({ type: 'fileCompleted', path });
+      return;
+    }
+    await this._closeWritable(path);
+    this._emit({ type: 'fileCompleted', path });
+  }
+
+  /**
+   * Close (and forget) a file's writable, atomically committing the swap
+   * file to its final name. Best-effort so failure/abort never throws.
+   * @param {string} path virtual path
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _closeWritable(path) {
+    const entry = this._writables.get(path);
+    if (entry) {
+      this._writables.delete(path);
+      try {
+        await entry.writable.close();
+      } catch {
+        /* best-effort flush on failure/abort */
+      }
     }
-    await writable.write({ type: 'write', position: offset, data });
   }
 
   /**
    * Resolve (and create, if needed) the file handle for a virtual path,
    * creating any parent directories along the way.
    * @param {string} path
-   * @returns {Promise<FileSystemFileHandle>}
+   * @returns {Promise<{dir: FileSystemDirectoryHandle, name: string, handle: FileSystemFileHandle}>}
    * @private
    */
   async _ensureFileHandle(path) {
@@ -301,20 +716,73 @@ export class LibfwClient {
     for (let i = 0; i < segments.length - 1; i += 1) {
       dir = await dir.getDirectoryHandle(segments[i], { create: true });
     }
-    return dir.getFileHandle(segments[segments.length - 1], { create: true });
+    const name = segments[segments.length - 1];
+    const handle = await dir.getFileHandle(name, { create: true });
+    return { dir, name, handle };
   }
 
   /**
-   * Close all open writable streams (flush to disk).
+   * Delete a leftover Chromium swap file (`.<name>.crswap`) next to a file,
+   * ignoring any error (no swap file, or permission denied).
+   * @param {FileSystemDirectoryHandle} dir parent directory
+   * @param {string} name target file name
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _removeSwapFile(dir, name) {
+    try {
+      await dir.removeEntry(`.${name}.crswap`, { recursive: false });
+    } catch {
+      /* nothing to clean up */
+    }
+  }
+
+  /**
+   * Close all still-open writable streams (flush to disk). Called on
+   * success, failure or cancellation of a transfer.
    * @returns {Promise<void>}
    * @private
    */
   async _flushWritables() {
-    const pending = [...this._writables.values()].map((w) => w.close().catch(() => {}));
-    this._writables.clear();
+    const pending = [...this._writables.entries()].map(async ([path, entry]) => {
+      this._writables.delete(path);
+      try {
+        await entry.writable.close();
+      } catch {
+        /* best-effort flush */
+      }
+    });
     await Promise.allSettled(pending);
   }
 
+  /**
+   * Reconcile persisted download resume offsets with the bytes actually
+   * committed to disk.
+   *
+   * `createWritable()` only commits to the real file on `close()`, so an
+   * interrupted download's on-disk length can be ahead of (or behind) the
+   * engine's periodically-saved offset. Overwriting each file's stored
+   * offset with its real size keeps the append-based resume consistent:
+   * the next transfer resumes exactly where the file on disk ends.
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _syncResumeOffsets() {
+    for (const [path, handle] of this._fileHandles) {
+      try {
+        const file = await handle.getFile();
+        const size = file.size;
+        const state = await Idb.loadState(`download:${path}`);
+        if (state && typeof state.etag === 'string') {
+          await Idb.saveState(`download:${path}`, { ...state, offset: size, size });
+        }
+      } catch {
+        /* best-effort */
+      }
+    }
+    this._fileHandles.clear();
+  }
+
   // -------------------------------------------------------------- uploads
 
   /**
@@ -480,6 +948,36 @@ export class LibfwClient {
   totalBytes() {
     return this._engine ? this._engine.total_bytes() : 0;
   }
+
+  // ------------------------------------------------------------- resume store
+
+  /**
+   * Delete persisted resume state (IndexedDB).
+   *
+   * Pass a direction to wipe only that transfer's state, leaving the other
+   * direction intact — the targeted replacement for clearing the whole store
+   * before every transfer:
+   *
+   * - `await client.clearResumeStore('download')` — drop all download state.
+   * - `await client.clearResumeStore('upload')` — drop all upload state.
+   * - `await client.clearResumeStore()` — wipe everything (whole-store clear).
+   *
+   * @param {'upload'|'download'} [direction] restrict to one direction
+   * @returns {Promise<number>} number of records removed
+   */
+  async clearResumeStore(direction) {
+    if (direction !== undefined && direction !== 'upload' && direction !== 'download') {
+      throw new LibfwError(
+        `clearResumeStore: expected 'upload' | 'download' | undefined, got ${JSON.stringify(direction)}`,
+        'path'
+      );
+    }
+    if (direction === undefined) {
+      await Idb.clear();
+      return 0;
+    }
+    return Idb.clearDirection(direction);
+  }
 }
 
 export default LibfwClient;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "libfw-client",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "High-performance streaming file & folder transfer SDK for the browser (libfw WASM engine + File System Access API + IndexedDB resume).",
-  "license": "MIT OR Apache-2.0",
+  "license": "MIT",
   "type": "module",
   "main": "index.js",
   "module": "index.js",
@@ -17,6 +17,7 @@
   },
   "files": [
     "index.js",
+    "zip.js",
     "index.d.ts",
     "pkg/libfw_client.js",
     "pkg/libfw_client_bg.wasm",
@@ -26,7 +27,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build:wasm": "wasm-pack build ../crates/libfw-client --target web --out-dir ../sdk/pkg --release",
+    "build:wasm": "wasm-pack build ../crates/libfw-client --target web --out-dir ../../sdk/pkg --release",
     "build:umd": "rollup -c rollup.config.mjs",
     "build": "npm run build:wasm && npm run build:umd"
   },

package/pkg/libfw_client.d.ts

@@ -15,6 +15,12 @@ export class LibfwClient {
      * Bytes transferred so far.
      */
     done_bytes(): number;
+    /**
+     * Download a single file at `file_path` into the chosen local directory.
+     *
+     * Resolves with the number of bytes written.
+     */
+    download_file(base_url: string, token: string, file_path: string): Promise<any>;
     /**
      * Download every file under the virtual `dirPath` (empty = root).
      *
@@ -77,6 +83,7 @@ export interface InitOutput {
     readonly js_option_string: (a: any, b: number, c: number) => [number, number];
     readonly libfwclient_cancel: (a: number) => void;
     readonly libfwclient_done_bytes: (a: number) => number;
+    readonly libfwclient_download_file: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
     readonly libfwclient_download_folder: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
     readonly libfwclient_has_callbacks: (a: number) => number;
     readonly libfwclient_new: (a: any) => number;

package/pkg/libfw_client.js

@@ -28,6 +28,25 @@ export class LibfwClient {
         const ret = wasm.libfwclient_done_bytes(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * Download a single file at `file_path` into the chosen local directory.
+     *
+     * Resolves with the number of bytes written.
+     * @param {string} base_url
+     * @param {string} token
+     * @param {string} file_path
+     * @returns {Promise<any>}
+     */
+    download_file(base_url, token, file_path) {
+        const ptr0 = passStringToWasm0(base_url, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(token, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(file_path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len2 = WASM_VECTOR_LEN;
+        const ret = wasm.libfwclient_download_file(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
+        return ret;
+    }
     /**
      * Download every file under the virtual `dirPath` (empty = root).
      *
@@ -360,6 +379,10 @@ function __wbg_get_imports() {
             const ret = new Request(getStringFromWasm0(arg0, arg1), arg2);
             return ret;
         }, arguments); },
+        __wbg_of_5f1b88183ddb5d94: function(arg0, arg1) {
+            const ret = Array.of(arg0, arg1);
+            return ret;
+        },
         __wbg_prototypesetcall_4770620bbe4688a0: function(arg0, arg1, arg2) {
             Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
         },
@@ -374,6 +397,10 @@ function __wbg_get_imports() {
         __wbg_queueMicrotask_6a09b7bc46549209: function(arg0) {
             queueMicrotask(arg0);
         },
+        __wbg_race_ac5c7b465abcfa15: function(arg0) {
+            const ret = Promise.race(arg0);
+            return ret;
+        },
         __wbg_read_8afa15f12a160ef8: function(arg0) {
             const ret = arg0.read();
             return ret;
@@ -382,6 +409,10 @@ function __wbg_get_imports() {
             const ret = Promise.resolve(arg0);
             return ret;
         },
+        __wbg_setTimeout_725a27c387d005c7: function() { return handleError(function (arg0, arg1, arg2, arg3) {
+            const ret = arg0.setTimeout(arg1, arg2, arg3);
+            return ret;
+        }, arguments); },
         __wbg_setTimeout_cfa2cf195c3738db: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = arg0.setTimeout(arg1, arg2);
             return ret;
@@ -431,7 +462,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 128, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 135, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen_1e05ddb24c0b7df4___convert__closures_____invoke___wasm_bindgen_1e05ddb24c0b7df4___JsValue__core_9b3796e30d99ddb7___result__Result_____wasm_bindgen_1e05ddb24c0b7df4___JsError___true_);
             return ret;
         },

package/pkg/libfw_client_bg.wasm.d.ts

@@ -5,6 +5,7 @@ export const __wbg_libfwclient_free: (a: number, b: number) => void;
 export const js_option_string: (a: any, b: number, c: number) => [number, number];
 export const libfwclient_cancel: (a: number) => void;
 export const libfwclient_done_bytes: (a: number) => number;
+export const libfwclient_download_file: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
 export const libfwclient_download_folder: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
 export const libfwclient_has_callbacks: (a: number) => number;
 export const libfwclient_new: (a: any) => number;

package/pkg/package.json

@@ -2,7 +2,7 @@
   "name": "libfw-client",
   "type": "module",
   "description": "WASM engine + JS SDK for libfw browser clients",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/zip.js

@@ -0,0 +1,123 @@
+/**
+ * Minimal, dependency-free ZIP writer for the browser-download fallback.
+ *
+ * When the File System Access API is unavailable, folder downloads are
+ * buffered in memory and packed into a single `.zip` archive via
+ * {@link createZip}. The archive uses the STORE method (no compression) —
+ * the SDK stays dependency-free (no deflate implementation) and CPU cost is
+ * negligible. Entries carry the full virtual path (with `/` separators), so
+ * extractors recreate the folder structure automatically.
+ *
+ * @module libfw/zip
+ */
+
+/** CRC-32 (IEEE 802.3, reflected) table, generated once. */
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+/**
+ * Compute the CRC-32 checksum of a byte array.
+ * @param {Uint8Array} bytes
+ * @returns {number} unsigned 32-bit CRC
+ */
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i += 1) {
+    crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/**
+ * Pack a list of files into a ZIP `Blob` (STORE method).
+ *
+ * @param {Array<{name: string, data: Uint8Array}>} entries
+ *        `name` is the virtual path inside the archive (`/` separators);
+ *        `data` is the file content (may be empty).
+ * @returns {Blob} `application/zip` blob
+ */
+export function createZip(entries) {
+  const encoder = new TextEncoder();
+  const body = [];
+  const central = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    const nameBytes = encoder.encode(entry.name);
+    const data = entry.data;
+    const crc = crc32(data);
+
+    // Local file header (30 bytes + name).
+    const local = new Uint8Array(30 + nameBytes.length);
+    const dv = new DataView(local.buffer);
+    dv.setUint32(0, 0x04034b50, true); // "PK\x03\x04"
+    dv.setUint16(4, 20, true); // version needed to extract
+    dv.setUint16(6, 0, true); // general purpose flags
+    dv.setUint16(8, 0, true); // compression method: STORE
+    dv.setUint16(10, 0, true); // last mod time
+    dv.setUint16(12, 0x0021, true); // last mod date (1980-01-01)
+    dv.setUint32(14, crc, true);
+    dv.setUint32(18, data.length, true); // compressed size
+    dv.setUint32(22, data.length, true); // uncompressed size
+    dv.setUint16(26, nameBytes.length, true);
+    dv.setUint16(28, 0, true); // extra field length
+    local.set(nameBytes, 30);
+
+    body.push(local, data);
+    central.push({ nameBytes, crc, size: data.length, offset });
+    offset += local.length + data.length;
+  }
+
+  // Central directory.
+  const dir = [];
+  let cdSize = 0;
+  for (const c of central) {
+    const cd = new Uint8Array(46 + c.nameBytes.length);
+    const dv = new DataView(cd.buffer);
+    dv.setUint32(0, 0x02014b50, true); // "PK\x01\x02"
+    dv.setUint16(4, 20, true); // version made by
+    dv.setUint16(6, 20, true); // version needed to extract
+    dv.setUint16(8, 0, true); // flags
+    dv.setUint16(10, 0, true); // method: STORE
+    dv.setUint16(12, 0, true); // mod time
+    dv.setUint16(14, 0x0021, true); // mod date
+    dv.setUint32(16, c.crc, true);
+    dv.setUint32(20, c.size, true); // compressed size
+    dv.setUint32(24, c.size, true); // uncompressed size
+    dv.setUint16(28, c.nameBytes.length, true);
+    dv.setUint16(30, 0, true); // extra field length
+    dv.setUint16(32, 0, true); // comment length
+    dv.setUint16(34, 0, true); // disk number start
+    dv.setUint16(36, 0, true); // internal file attributes
+    dv.setUint32(38, 0, true); // external file attributes
+    dv.setUint32(42, c.offset, true); // local header offset
+    cd.set(c.nameBytes, 46);
+    dir.push(cd);
+    cdSize += cd.length;
+  }
+
+  const cdOffset = offset;
+
+  // End of central directory record (22 bytes).
+  const eocd = new Uint8Array(22);
+  const edv = new DataView(eocd.buffer);
+  edv.setUint32(0, 0x06054b50, true); // "PK\x05\x06"
+  edv.setUint16(4, 0, true); // disk number
+  edv.setUint16(6, 0, true); // disk with central dir
+  edv.setUint16(8, central.length, true); // entries on this disk
+  edv.setUint16(10, central.length, true); // total entries
+  edv.setUint32(12, cdSize, true); // central dir size
+  edv.setUint32(16, cdOffset, true); // central dir offset
+  edv.setUint16(20, 0, true); // comment length
+
+  return new Blob([...body, ...dir, eocd], { type: 'application/zip' });
+}