libfw-client 0.1.2 → 0.1.4

package/README.md

@@ -11,11 +11,18 @@ import { LibfwClient } from 'libfw-client';
 const client = new LibfwClient({
   baseUrl: '/api',      // where libfw-server routes are mounted
   concurrency: 4,       // max parallel file transfers
+  uploadWindow: 8,      // in-flight chunks per single file upload (raise to
+                        // reduce upload stutter on high-latency links)
+  downloadWindow: 4,    // in-flight byte-range GETs per single file download
+                        // (tus-style parallel download: one file's throughput
+                        // isn't bounded by a single connection's RTT)
   compress: true,       // zrip streaming compression
   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,14 +40,28 @@ 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. Large files use the **tus-style parallel path**: `downloadWindow`
+  concurrent byte-range GETs, reordered in memory so the SDK still receives
+  bytes strictly in order (append-mode `createWritable()`, no `.crswap`
+  churn), with per-chunk independent retries. 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
-  validation.
+  frame, and POSTs them with an absolute `x-libfw-offset` into a shared
+  per-session temp file. Up to `uploadWindow` chunks of one file are kept in
+  flight concurrently (independent of the cross-file `concurrency`), so a
+  high-latency link stays saturated. Uploads are **tus-style
+  verify-then-complete**: the server is the source of truth — the client
+  probes the byte ranges the server actually persisted and re-sends only the
+  still-missing blocks, filling gaps a lost response may have left (and
+  re-probing + refilling if a commit fails) before the final `x-libfw-final`
+  request merges the temp into place.
 - Resume state (`etag`, `offset`, `size`) is persisted per path in
   IndexedDB and re-validated on every retry.
 - Pause/resume/cancel drive the WASM state machine
@@ -61,6 +82,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 +90,24 @@ dist/libfw-client.umd.js   UMD bundle (after build:umd)
 ## API
 
 - `new LibfwClient(options?)`
+  - `downloadWindow: number` (default `4`) — in-flight byte-range GETs per
+    single file download; `1` disables parallelism.
+  - `downloadChunkSize: number` (default `262144`, 256 KiB) — byte range size
+    for parallel downloads; the engine reorders in-flight chunks in memory
+    (worst case ≈ `downloadWindow * downloadChunkSize` bytes) so the SDK
+    still receives data in order.
+  - `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 {
@@ -51,8 +52,30 @@ export interface LibfwEvent {
 export interface LibfwClientOptions {
   /** Base URL the libfw server routes are mounted under. Default `''`. */
   baseUrl?: string;
-  /** Max concurrent file transfers. Default `4`. */
+  /** Max concurrently-transferring files. Default `4`. */
   concurrency?: number;
+  /**
+   * In-flight chunk window for a single file's upload, independent of
+   * `concurrency`. A higher value keeps high-latency links saturated and
+   * reduces upload stutter; keep it within your server's connection limit
+   * (~6 for HTTP/1.1). Default `8`.
+   */
+  uploadWindow?: number;
+  /**
+   * In-flight byte-range window for a single file's download. Large files
+   * are fetched as `downloadWindow` concurrent `Range` GETs (tus-style
+   * parallel transfer), so a single file's throughput is bounded by
+   * bandwidth instead of one connection's `chunkSize / RTT` on high-latency
+   * links. `1` disables parallelism. Default `4`.
+   */
+  downloadWindow?: number;
+  /**
+   * Byte range size for parallel downloads. Smaller than the upload chunk
+   * on purpose: the engine reorders in-flight chunks in memory (worst case
+   * ≈ `downloadWindow * downloadChunkSize` bytes) so the SDK still receives
+   * data strictly in order. Default `262144` (256 KiB).
+   */
+  downloadChunkSize?: number;
   /** Negotiate zrip compression. Default `true`. */
   compress?: boolean;
   /** Upload chunk size in bytes. Default 2 MiB. */
@@ -65,6 +88,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;
 }
@@ -142,6 +186,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,17 +168,62 @@ 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]
    * @param {string} [options.baseUrl=''] base URL the server routes are mounted under
-   * @param {number} [options.concurrency=4] max concurrent file transfers
+   * @param {number} [options.concurrency=4] max concurrently-transferring files
+   * @param {number} [options.uploadWindow=8] in-flight chunk window for a
+   *        single file's upload; independent of `concurrency`, keeps a
+   *        high-latency link saturated (raise it to reduce upload stutter;
+   *        keep within your server's connection limit, ~6 for HTTP/1.1)
+   * @param {number} [options.downloadWindow=4] in-flight byte-range window
+   *        for a single file's download. Large files are fetched as
+   *        `downloadWindow` concurrent `Range` GETs (tus-style parallel
+   *        transfer), so a single file's throughput is bounded by bandwidth
+   *        instead of one connection's `chunkSize / RTT` on high-latency
+   *        links. `1` disables parallelism (sequential downloads).
+   * @param {number} [options.downloadChunkSize=262144] byte range size for
+   *        parallel downloads (256 KiB default). Smaller than the upload
+   *        chunk on purpose: the engine reorders in-flight chunks in memory
+   *        (worst case ≈ `downloadWindow * downloadChunkSize` bytes) so the
+   *        SDK still receives data strictly in order.
    * @param {boolean} [options.compress=true] negotiate zrip compression
    * @param {number} [options.chunkSize=2097152] upload chunk size in bytes
    * @param {number} [options.maxRetries=3] retries per chunk/file before failing
    * @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
    */
@@ -141,12 +231,18 @@ export class LibfwClient {
     this._options = {
       baseUrl: '',
       concurrency: 4,
+      uploadWindow: 8,
+      downloadWindow: 4,
+      downloadChunkSize: 256 * 1024,
       compress: true,
       chunkSize: 2 * 1024 * 1024,
       maxRetries: 3,
       baseRetryDelayMs: 500,
       maxRetryDelayMs: 30000,
       timeoutMs: 60000,
+      wasmUrl: null,
+      downloadMode: 'auto',
+      maxFallbackBytes: 512 * 1024 * 1024,
       onEvent: null,
       ...options,
     };
@@ -164,6 +260,11 @@ export class LibfwClient {
     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 +277,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);
       });
@@ -184,6 +290,9 @@ export class LibfwClient {
     await this._initPromise;
     const engine = new WasmEngine({
       concurrency: this._options.concurrency,
+      uploadWindow: this._options.uploadWindow,
+      downloadWindow: this._options.downloadWindow,
+      downloadChunkSize: this._options.downloadChunkSize,
       compress: this._options.compress,
       chunkSize: this._options.chunkSize,
       maxRetries: this._options.maxRetries,
@@ -196,6 +305,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 +337,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._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 +392,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,24 +449,29 @@ export class LibfwClient {
       throw toLibfwError(err);
     } finally {
       await this._flushWritables();
+      await this._syncResumeOffsets();
     }
   }
 
   /**
-   * Download a single file from the server at `filePath` into a local
-   * directory chosen via `showDirectoryPicker()`.
+   * 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 written
+   * @returns {Promise<number>} total bytes transferred
    * @throws {LibfwError}
    */
   async downloadFile(token, filePath) {
     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 (!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 {
@@ -281,36 +480,210 @@ export class LibfwClient {
       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 {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';
   }
 
   /**
-   * Stream a decompressed chunk straight to disk at its absolute byte
-   * offset, keeping memory bounded regardless of file size (no whole-file
-   * buffering). The engine awaits this callback, so writes for a file are
-   * applied strictly in order.
+   * 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
+   * @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) {
-      // Open the destination once per file. A true resume (first chunk at
-      // offset > 0) keeps the existing prefix on disk; a fresh download opens
-      // a truncating writable. Always close the writable on completion/abort
-      // so no orphaned `.crswap` swap files are left behind.
-      const isResume = offset > 0;
-      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);
-      writable = await handle.createWritable(
+      // 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;
+      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 writable.write({ type: 'write', position: offset, data });
+    await entry.writable.write(data);
   }
 
   /**
@@ -320,22 +693,28 @@ export class LibfwClient {
    * @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, flushing buffered bytes to disk.
+   * 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 writable = this._writables.get(path);
-    if (writable) {
+    const entry = this._writables.get(path);
+    if (entry) {
       this._writables.delete(path);
       try {
-        await writable.close();
+        await entry.writable.close();
       } catch {
         /* best-effort flush on failure/abort */
       }
@@ -346,7 +725,7 @@ export class LibfwClient {
    * 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) {
@@ -358,7 +737,25 @@ 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 };
+  }
+
+  /**
+   * 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 */
+    }
   }
 
   /**
@@ -368,10 +765,10 @@ export class LibfwClient {
    * @private
    */
   async _flushWritables() {
-    const pending = [...this._writables.entries()].map(async ([path, writable]) => {
+    const pending = [...this._writables.entries()].map(async ([path, entry]) => {
       this._writables.delete(path);
       try {
-        await writable.close();
+        await entry.writable.close();
       } catch {
         /* best-effort flush */
       }
@@ -379,6 +776,34 @@ export class LibfwClient {
     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
 
   /**
@@ -544,6 +969,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,6 +1,6 @@
 {
   "name": "libfw-client",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "High-performance streaming file & folder transfer SDK for the browser (libfw WASM engine + File System Access API + IndexedDB resume).",
   "license": "MIT",
   "type": "module",
@@ -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

@@ -33,8 +33,9 @@ export class LibfwClient {
     has_callbacks(): boolean;
     /**
      * Create an engine. `options` may include:
-     * `{ concurrency, compress, chunkSize, maxRetries, baseRetryDelayMs,
-     * maxRetryDelayMs, timeoutMs }`.
+     * `{ concurrency, uploadWindow, downloadWindow, downloadChunkSize,
+     * compress, chunkSize, maxRetries, baseRetryDelayMs, maxRetryDelayMs,
+     * timeoutMs }`.
      */
     constructor(opts: any);
     /**

package/pkg/libfw_client.js

@@ -76,8 +76,9 @@ export class LibfwClient {
     }
     /**
      * Create an engine. `options` may include:
-     * `{ concurrency, compress, chunkSize, maxRetries, baseRetryDelayMs,
-     * maxRetryDelayMs, timeoutMs }`.
+     * `{ concurrency, uploadWindow, downloadWindow, downloadChunkSize,
+     * compress, chunkSize, maxRetries, baseRetryDelayMs, maxRetryDelayMs,
+     * timeoutMs }`.
      * @param {any} opts
      */
     constructor(opts) {
@@ -379,6 +380,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);
         },
@@ -393,6 +398,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;
@@ -401,6 +410,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;
@@ -450,7 +463,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: 133, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 145, 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/package.json

@@ -2,7 +2,7 @@
   "name": "libfw-client",
   "type": "module",
   "description": "WASM engine + JS SDK for libfw browser clients",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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' });
+}