@mountra/mountra-sdk 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -21,13 +21,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   DEFAULT_S3_MULTIPART_PART_SIZE_BYTES: () => DEFAULT_S3_MULTIPART_PART_SIZE_BYTES,
+  DownloadHttpError: () => DownloadHttpError,
+  InMemoryDownloadCacheStore: () => InMemoryDownloadCacheStore,
+  InMemoryDownloadCheckpointStore: () => InMemoryDownloadCheckpointStore,
   InMemoryJumboChunkCheckpointStore: () => InMemoryJumboChunkCheckpointStore,
+  IndexedDBDownloadCacheStore: () => IndexedDBDownloadCacheStore,
+  IndexedDBDownloadCheckpointStore: () => IndexedDBDownloadCheckpointStore,
   JUMBO_CHUNK_THRESHOLD_BYTES: () => JUMBO_CHUNK_THRESHOLD_BYTES,
   LocalStorageJumboChunkCheckpointStore: () => LocalStorageJumboChunkCheckpointStore,
   MAX_S3_MULTIPART_PARTS: () => MAX_S3_MULTIPART_PARTS,
   MIN_S3_MULTIPART_PART_SIZE_BYTES: () => MIN_S3_MULTIPART_PART_SIZE_BYTES,
   MountraApiError: () => MountraApiError,
   MountraClient: () => MountraClient,
+  MountraDownloader: () => MountraDownloader,
+  MountraFile: () => MountraFile,
   MountraSDK: () => MountraClient,
   S3MultipartUploader: () => S3MultipartUploader,
   createMountraClient: () => createMountraClient,
@@ -37,6 +44,1546 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/file.ts
+function normalizeMountraFileLocator(locator, fallbackWorkspace = {}) {
+  if (!locator || typeof locator !== "object") {
+    throw new TypeError("Mountra file locator is required");
+  }
+  const hasPath = locator.path !== void 0;
+  const hasIno = locator.ino !== void 0;
+  if (hasPath === hasIno) {
+    throw new TypeError("Mountra file locator requires exactly one of path or ino");
+  }
+  const workspaceId = locator.workspaceId ?? locator.wsid ?? fallbackWorkspace.workspaceId;
+  if (locator.workspaceId !== void 0 && locator.wsid !== void 0 && String(locator.workspaceId) !== String(locator.wsid)) {
+    throw new TypeError("workspaceId and wsid must identify the same workspace");
+  }
+  const workspaceCuid = locator.workspaceCuid ?? fallbackWorkspace.workspaceCuid;
+  if (workspaceCuid === void 0 && workspaceId === void 0) {
+    throw new TypeError("workspaceCuid, workspaceId, or wsid is required");
+  }
+  if (hasPath) {
+    const path = normalizePath(locator.path);
+    return {
+      ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
+      ...workspaceId !== void 0 ? { workspaceId } : {},
+      path
+    };
+  }
+  return {
+    ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
+    ...workspaceId !== void 0 ? { workspaceId } : {},
+    ino: normalizeIno(locator.ino)
+  };
+}
+var MountraFile = class {
+  constructor(client, locator) {
+    this.client = client;
+    this.locator = Object.freeze({ ...locator });
+  }
+  client;
+  locator;
+  get workspaceCuid() {
+    return this.locator.workspaceCuid;
+  }
+  get workspaceId() {
+    return this.locator.workspaceId;
+  }
+  /** `wsid` is the short alias used by the file-object API. */
+  get wsid() {
+    return this.locator.workspaceId;
+  }
+  get path() {
+    return "path" in this.locator ? this.locator.path : void 0;
+  }
+  get ino() {
+    return "ino" in this.locator ? this.locator.ino : void 0;
+  }
+  export(options = {}) {
+    return this.client.exportFile({ ...options, ...this.locator });
+  }
+  download(options = {}) {
+    return this.client.downloadFile({ ...options, ...this.locator });
+  }
+  async resume(options = {}) {
+    const { downloadKey, ...resumeOptions } = options;
+    const checkpoints = await this.client.listResumableDownloads();
+    const candidates = checkpoints.filter(
+      (checkpoint2) => checkpoint2.fileHandle && matchesLocator(checkpoint2.request, this.locator)
+    );
+    const checkpoint = downloadKey ? candidates.find((candidate) => candidate.key === downloadKey) : [...candidates].sort((left, right) => right.updatedAt - left.updatedAt)[0];
+    if (!checkpoint) {
+      if (downloadKey) {
+        throw new Error("Download checkpoint does not belong to this Mountra file");
+      }
+      throw new Error("No resumable download was found for this Mountra file");
+    }
+    return this.client.resumeDownload(checkpoint.key, resumeOptions);
+  }
+};
+function matchesLocator(request, locator) {
+  if (locator.workspaceCuid !== void 0 && request.workspaceCuid !== locator.workspaceCuid) {
+    return false;
+  }
+  if (locator.workspaceId !== void 0 && String(request.workspaceId) !== String(locator.workspaceId)) {
+    return false;
+  }
+  if ("path" in locator) {
+    if (request.path === void 0 || request.ino !== void 0) {
+      return false;
+    }
+    try {
+      return normalizePath(request.path) === locator.path;
+    } catch {
+      return false;
+    }
+  }
+  return String(request.ino) === String(locator.ino) && request.path === void 0;
+}
+function normalizePath(value) {
+  if (!value || !value.trim()) {
+    throw new TypeError("Mountra file path cannot be empty");
+  }
+  const raw = value.trim();
+  const absolute = raw.startsWith("/") ? raw : `/${raw}`;
+  const segments = absolute.split("/").filter((segment) => segment.length > 0 && segment !== ".");
+  const stack = [];
+  for (const segment of segments) {
+    if (segment === "..") {
+      stack.pop();
+      continue;
+    }
+    stack.push(segment);
+  }
+  return stack.length === 0 ? "/" : `/${stack.join("/")}`;
+}
+function normalizeIno(value) {
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new TypeError("Mountra file ino must be a non-negative safe integer");
+    }
+    return value;
+  }
+  if (!/^\d+$/.test(value)) {
+    throw new TypeError("Mountra file ino must be a non-negative integer string");
+  }
+  return value;
+}
+
+// src/cache.ts
+var DEFAULT_MAX_BYTES = 512 * 1024 * 1024;
+var DEFAULT_MAX_CHUNK_BYTES = 128 * 1024 * 1024;
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+function copyFile(file) {
+  return { ...file, chunks: file.chunks.map((chunk) => ({ ...chunk })) };
+}
+function memoryKey(workspace, key) {
+  return JSON.stringify([workspace, key]);
+}
+var InMemoryDownloadCacheStore = class {
+  files = /* @__PURE__ */ new Map();
+  /** Map iteration order is the LRU order: the first entry is the least recently used. */
+  chunks = /* @__PURE__ */ new Map();
+  bytes = 0;
+  async getFile(workspace, fileKey) {
+    const entry = this.files.get(memoryKey(workspace, fileKey));
+    return entry ? copyFile(entry.file) : null;
+  }
+  async putFile(workspace, fileKey, file) {
+    this.files.set(memoryKey(workspace, fileKey), { workspace, file: copyFile(file) });
+  }
+  async removeFile(workspace, fileKey) {
+    this.files.delete(memoryKey(workspace, fileKey));
+  }
+  async getChunk(workspace, storageKey) {
+    const key = memoryKey(workspace, storageKey);
+    const entry = this.chunks.get(key);
+    if (!entry) {
+      return null;
+    }
+    this.chunks.delete(key);
+    this.chunks.set(key, entry);
+    return entry.data;
+  }
+  async putChunk(workspace, storageKey, data, maxBytes) {
+    const key = memoryKey(workspace, storageKey);
+    this.removeChunk(key);
+    if (data.size > maxBytes) {
+      return;
+    }
+    this.chunks.set(key, { workspace, data });
+    this.bytes += data.size;
+    for (const candidate of this.chunks.keys()) {
+      if (this.bytes <= maxBytes) {
+        break;
+      }
+      this.removeChunk(candidate);
+    }
+  }
+  async clear(workspace) {
+    for (const [key, entry] of this.chunks) {
+      if (workspace === void 0 || entry.workspace === workspace) {
+        this.removeChunk(key);
+      }
+    }
+    for (const [key, entry] of this.files) {
+      if (workspace === void 0 || entry.workspace === workspace) {
+        this.files.delete(key);
+      }
+    }
+  }
+  async usage(workspace) {
+    const usage = { bytes: 0, chunks: 0 };
+    for (const entry of this.chunks.values()) {
+      if (workspace === void 0 || entry.workspace === workspace) {
+        usage.bytes += entry.data.size;
+        usage.chunks += 1;
+      }
+    }
+    return usage;
+  }
+  removeChunk(key) {
+    const entry = this.chunks.get(key);
+    if (entry) {
+      this.chunks.delete(key);
+      this.bytes -= entry.data.size;
+    }
+  }
+};
+var CACHE_DATABASE_NAME = "mountra-sdk-download-cache";
+var CACHE_DATABASE_VERSION = 1;
+var FILES_STORE = "files";
+var CHUNKS_STORE = "chunks";
+var CHUNK_DATA_STORE = "chunk-data";
+var META_STORE = "meta";
+var LRU_INDEX = "lastUsed";
+var USAGE_KEY = "bytes";
+var CLOCK_KEY = "clock";
+function getIndexedDb() {
+  return globalThis.indexedDB ?? null;
+}
+function workspaceRange(workspace) {
+  return IDBKeyRange.bound([workspace], [workspace, []]);
+}
+function sameKey(left, right) {
+  return Array.isArray(left) && left[0] === right[0] && left[1] === right[1];
+}
+async function nextClock(meta) {
+  const clock = (await requestResult(meta.get(CLOCK_KEY)) ?? 0) + 1;
+  await requestResult(meta.put(clock, CLOCK_KEY));
+  return clock;
+}
+function requestResult(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+  });
+}
+async function runTransaction(database, storeNames, mode, body) {
+  const transaction = database.transaction(storeNames, mode);
+  const done = new Promise((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB transaction failed"));
+    transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB transaction aborted"));
+  });
+  done.catch(() => void 0);
+  let result;
+  try {
+    result = await body(transaction);
+  } catch (error) {
+    try {
+      transaction.abort();
+    } catch {
+    }
+    throw error;
+  }
+  await done;
+  return result;
+}
+var IndexedDBDownloadCacheStore = class {
+  databaseName;
+  fallback = new InMemoryDownloadCacheStore();
+  databasePromise;
+  constructor(options = {}) {
+    this.databaseName = options.databaseName ?? CACHE_DATABASE_NAME;
+  }
+  async getFile(workspace, fileKey) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.getFile(workspace, fileKey);
+    }
+    return runTransaction(database, [FILES_STORE], "readonly", async (transaction) => {
+      const file = await requestResult(
+        transaction.objectStore(FILES_STORE).get([workspace, fileKey])
+      );
+      return file ? copyFile(file) : null;
+    });
+  }
+  async putFile(workspace, fileKey, file) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.putFile(workspace, fileKey, file);
+    }
+    await runTransaction(database, [FILES_STORE], "readwrite", async (transaction) => {
+      await requestResult(transaction.objectStore(FILES_STORE).put(copyFile(file), [workspace, fileKey]));
+    });
+  }
+  async removeFile(workspace, fileKey) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.removeFile(workspace, fileKey);
+    }
+    await runTransaction(database, [FILES_STORE], "readwrite", async (transaction) => {
+      await requestResult(transaction.objectStore(FILES_STORE).delete([workspace, fileKey]));
+    });
+  }
+  async getChunk(workspace, storageKey) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.getChunk(workspace, storageKey);
+    }
+    const key = [workspace, storageKey];
+    return runTransaction(
+      database,
+      [CHUNKS_STORE, CHUNK_DATA_STORE, META_STORE],
+      "readwrite",
+      async (transaction) => {
+        const chunks = transaction.objectStore(CHUNKS_STORE);
+        const record = await requestResult(chunks.get(key));
+        if (!record) {
+          return null;
+        }
+        const data = await requestResult(
+          transaction.objectStore(CHUNK_DATA_STORE).get(key)
+        );
+        const meta = transaction.objectStore(META_STORE);
+        if (!data) {
+          const bytes = await requestResult(meta.get(USAGE_KEY)) ?? 0;
+          await requestResult(chunks.delete(key));
+          await requestResult(meta.put(Math.max(bytes - record.size, 0), USAGE_KEY));
+          return null;
+        }
+        await requestResult(chunks.put({ size: record.size, lastUsed: await nextClock(meta) }, key));
+        return data;
+      }
+    );
+  }
+  async putChunk(workspace, storageKey, data, maxBytes) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.putChunk(workspace, storageKey, data, maxBytes);
+    }
+    const key = [workspace, storageKey];
+    await runTransaction(
+      database,
+      [CHUNKS_STORE, CHUNK_DATA_STORE, META_STORE],
+      "readwrite",
+      async (transaction) => {
+        const chunks = transaction.objectStore(CHUNKS_STORE);
+        const chunkData = transaction.objectStore(CHUNK_DATA_STORE);
+        const meta = transaction.objectStore(META_STORE);
+        let bytes = await requestResult(meta.get(USAGE_KEY)) ?? 0;
+        const existing = await requestResult(chunks.get(key));
+        if (existing) {
+          bytes -= existing.size;
+          await requestResult(chunks.delete(key));
+          await requestResult(chunkData.delete(key));
+        }
+        if (data.size <= maxBytes) {
+          await requestResult(chunks.put({ size: data.size, lastUsed: await nextClock(meta) }, key));
+          await requestResult(chunkData.put(data, key));
+          bytes += data.size;
+        }
+        if (bytes > maxBytes) {
+          const cursorRequest = chunks.index(LRU_INDEX).openCursor();
+          let cursor = await requestResult(cursorRequest);
+          while (cursor && bytes > maxBytes) {
+            if (!sameKey(cursor.primaryKey, key)) {
+              bytes -= cursor.value.size;
+              await requestResult(chunkData.delete(cursor.primaryKey));
+              await requestResult(cursor.delete());
+            }
+            cursor.continue();
+            cursor = await requestResult(cursorRequest);
+          }
+        }
+        await requestResult(meta.put(Math.max(bytes, 0), USAGE_KEY));
+      }
+    );
+  }
+  async clear(workspace) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.clear(workspace);
+    }
+    await runTransaction(
+      database,
+      [FILES_STORE, CHUNKS_STORE, CHUNK_DATA_STORE, META_STORE],
+      "readwrite",
+      async (transaction) => {
+        const files = transaction.objectStore(FILES_STORE);
+        const chunks = transaction.objectStore(CHUNKS_STORE);
+        const chunkData = transaction.objectStore(CHUNK_DATA_STORE);
+        const meta = transaction.objectStore(META_STORE);
+        if (workspace === void 0) {
+          await requestResult(files.clear());
+          await requestResult(chunks.clear());
+          await requestResult(chunkData.clear());
+          await requestResult(meta.put(0, USAGE_KEY));
+          return;
+        }
+        const range = workspaceRange(workspace);
+        const removed = await requestResult(chunks.getAll(range));
+        const bytes = await requestResult(meta.get(USAGE_KEY)) ?? 0;
+        await requestResult(files.delete(range));
+        await requestResult(chunks.delete(range));
+        await requestResult(chunkData.delete(range));
+        await requestResult(
+          meta.put(Math.max(bytes - removed.reduce((total, record) => total + record.size, 0), 0), USAGE_KEY)
+        );
+      }
+    );
+  }
+  async usage(workspace) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.usage(workspace);
+    }
+    return runTransaction(database, [CHUNKS_STORE], "readonly", async (transaction) => {
+      const records = await requestResult(
+        transaction.objectStore(CHUNKS_STORE).getAll(workspace === void 0 ? void 0 : workspaceRange(workspace))
+      );
+      return {
+        bytes: records.reduce((total, record) => total + record.size, 0),
+        chunks: records.length
+      };
+    });
+  }
+  async openDatabase() {
+    if (!this.databasePromise) {
+      const indexedDb = getIndexedDb();
+      if (!indexedDb) {
+        this.databasePromise = Promise.resolve(null);
+      } else {
+        this.databasePromise = new Promise((resolve) => {
+          let request;
+          try {
+            request = indexedDb.open(this.databaseName, CACHE_DATABASE_VERSION);
+          } catch {
+            resolve(null);
+            return;
+          }
+          request.onupgradeneeded = () => {
+            const database = request.result;
+            if (!database.objectStoreNames.contains(FILES_STORE)) {
+              database.createObjectStore(FILES_STORE);
+            }
+            if (!database.objectStoreNames.contains(CHUNKS_STORE)) {
+              database.createObjectStore(CHUNKS_STORE).createIndex(LRU_INDEX, "lastUsed");
+            }
+            if (!database.objectStoreNames.contains(CHUNK_DATA_STORE)) {
+              database.createObjectStore(CHUNK_DATA_STORE);
+            }
+            if (!database.objectStoreNames.contains(META_STORE)) {
+              database.createObjectStore(META_STORE);
+            }
+          };
+          request.onsuccess = () => {
+            const database = request.result;
+            database.onversionchange = () => {
+              database.close();
+              this.databasePromise = void 0;
+            };
+            resolve(database);
+          };
+          request.onerror = () => resolve(null);
+          request.onblocked = () => resolve(null);
+        });
+      }
+    }
+    return this.databasePromise;
+  }
+};
+function isImmutableStorageKey(storageKey) {
+  return /(?:^|\/)blobs\/sha256\/[0-9a-f]{64}$/.test(storageKey);
+}
+function workspaceCacheKey(baseUrl, selector) {
+  const workspaceCuid = selector.workspaceCuid?.trim();
+  const workspaceId = selector.workspaceId !== void 0 ? String(selector.workspaceId).trim() : "";
+  const workspace = workspaceCuid || workspaceId;
+  return workspace ? JSON.stringify([baseUrl, workspace]) : null;
+}
+function fileCacheKey(target) {
+  try {
+    if (target.ino !== void 0) {
+      return `ino:${BigInt(target.ino).toString()}`;
+    }
+    if (target.path !== void 0) {
+      return `path:${normalizePath(target.path)}`;
+    }
+  } catch {
+  }
+  return null;
+}
+function isValidLayout(file) {
+  let offset = 0;
+  for (const [index, chunk] of file.chunks.entries()) {
+    if (chunk.index !== index || chunk.offset !== offset || chunk.size < 0) {
+      return false;
+    }
+    offset += chunk.size;
+  }
+  return file.chunks.length > 0 && offset === file.size;
+}
+var DownloadCache = class {
+  maxBytes;
+  maxChunkBytes;
+  ttlMs;
+  store;
+  constructor(options) {
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (!Number.isSafeInteger(this.maxBytes) || this.maxBytes <= 0) {
+      throw new RangeError("downloadCache.maxBytes must be a positive safe integer");
+    }
+    const maxChunkBytes = options.maxChunkBytes ?? DEFAULT_MAX_CHUNK_BYTES;
+    if (!Number.isSafeInteger(maxChunkBytes) || maxChunkBytes <= 0) {
+      throw new RangeError("downloadCache.maxChunkBytes must be a positive safe integer");
+    }
+    this.maxChunkBytes = Math.min(maxChunkBytes, this.maxBytes);
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    if (Number.isNaN(this.ttlMs) || this.ttlMs < 0) {
+      throw new RangeError("downloadCache.ttlMs must be a non-negative number");
+    }
+    this.store = options.store ?? new IndexedDBDownloadCacheStore();
+  }
+  /** Return a file that has not expired together with all of its chunk bytes. */
+  async loadFile(workspace, fileKey) {
+    try {
+      const file = await this.store.getFile(workspace, fileKey);
+      if (!file) {
+        return null;
+      }
+      if (file.expiresAt <= Date.now() || !isValidLayout(file)) {
+        await this.store.removeFile(workspace, fileKey);
+        return null;
+      }
+      const chunks = /* @__PURE__ */ new Map();
+      for (const chunk of file.chunks) {
+        const data = await this.readChunk(workspace, chunk);
+        if (!data) {
+          return null;
+        }
+        chunks.set(chunk.index, data);
+      }
+      return { file, chunks };
+    } catch {
+      return null;
+    }
+  }
+  async readChunk(workspace, chunk) {
+    if (chunk.size === 0) {
+      return new Blob([]);
+    }
+    if (!isImmutableStorageKey(chunk.storageKey)) {
+      return null;
+    }
+    try {
+      const data = await this.store.getChunk(workspace, chunk.storageKey);
+      return data && data.size === chunk.size ? data : null;
+    } catch {
+      return null;
+    }
+  }
+  canStoreChunk(chunk) {
+    return isImmutableStorageKey(chunk.storageKey) && chunk.size <= this.maxChunkBytes;
+  }
+  /** Returns whether the chunk is now cached. */
+  async storeChunk(workspace, chunk, data) {
+    if (chunk.size === 0) {
+      return true;
+    }
+    if (!this.canStoreChunk(chunk) || data.size !== chunk.size) {
+      return false;
+    }
+    try {
+      await this.store.putChunk(workspace, chunk.storageKey, data, this.maxBytes);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async storeFile(workspace, fileKey, file) {
+    if (this.ttlMs <= 0) {
+      return;
+    }
+    const cachedAt = Date.now();
+    try {
+      await this.store.putFile(workspace, fileKey, {
+        path: file.path,
+        size: file.size,
+        ...file.contentType ? { contentType: file.contentType } : {},
+        chunks: file.chunks.map(({ index, offset, size, storageKey }) => ({
+          index,
+          offset,
+          size,
+          storageKey
+        })),
+        cachedAt,
+        expiresAt: cachedAt + this.ttlMs
+      });
+    } catch {
+    }
+  }
+  async invalidateFiles(workspace, fileKeys) {
+    await Promise.all(
+      fileKeys.map((fileKey) => this.store.removeFile(workspace, fileKey).catch(() => void 0))
+    );
+  }
+  clear(workspace) {
+    return this.store.clear(workspace);
+  }
+  usage(workspace) {
+    return this.store.usage(workspace);
+  }
+};
+
+// src/download.ts
+function copyCheckpoint(checkpoint) {
+  return {
+    ...checkpoint,
+    request: { ...checkpoint.request },
+    chunks: checkpoint.chunks.map((chunk) => ({ ...chunk }))
+  };
+}
+var InMemoryDownloadCheckpointStore = class {
+  records = /* @__PURE__ */ new Map();
+  async load(key) {
+    const value = this.records.get(key);
+    return value ? copyCheckpoint(value) : null;
+  }
+  async save(key, checkpoint) {
+    this.records.set(key, copyCheckpoint(checkpoint));
+  }
+  async remove(key) {
+    this.records.delete(key);
+  }
+  async list() {
+    return [...this.records.values()].map(copyCheckpoint);
+  }
+};
+var DOWNLOAD_DATABASE_NAME = "mountra-sdk";
+var DOWNLOAD_DATABASE_VERSION = 1;
+var DOWNLOAD_STORE_NAME = "download-checkpoints";
+function getIndexedDb2() {
+  return globalThis.indexedDB ?? null;
+}
+var IndexedDBDownloadCheckpointStore = class {
+  fallback = new InMemoryDownloadCheckpointStore();
+  databasePromise;
+  async load(key) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.load(key);
+    }
+    try {
+      const value = await this.request(
+        database,
+        "readonly",
+        (store) => store.get(key)
+      );
+      return value ? copyCheckpoint(value) : null;
+    } catch {
+      return this.fallback.load(key);
+    }
+  }
+  async save(key, checkpoint) {
+    const value = copyCheckpoint(checkpoint);
+    const database = await this.openDatabase();
+    if (!database) {
+      await this.fallback.save(key, value);
+      return;
+    }
+    try {
+      await this.request(database, "readwrite", (store) => store.put(value, key));
+    } catch {
+      await this.fallback.save(key, value);
+    }
+  }
+  async remove(key) {
+    const database = await this.openDatabase();
+    if (!database) {
+      await this.fallback.remove(key);
+      return;
+    }
+    try {
+      await this.request(database, "readwrite", (store) => store.delete(key));
+    } catch {
+      await this.fallback.remove(key);
+    }
+  }
+  async list() {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.list();
+    }
+    try {
+      const values = await this.request(
+        database,
+        "readonly",
+        (store) => store.getAll()
+      );
+      return values.map(copyCheckpoint);
+    } catch {
+      return this.fallback.list();
+    }
+  }
+  async openDatabase() {
+    if (!this.databasePromise) {
+      const indexedDb = getIndexedDb2();
+      if (!indexedDb) {
+        this.databasePromise = Promise.resolve(null);
+      } else {
+        this.databasePromise = new Promise((resolve) => {
+          let request;
+          try {
+            request = indexedDb.open(DOWNLOAD_DATABASE_NAME, DOWNLOAD_DATABASE_VERSION);
+          } catch {
+            resolve(null);
+            return;
+          }
+          request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains(DOWNLOAD_STORE_NAME)) {
+              request.result.createObjectStore(DOWNLOAD_STORE_NAME);
+            }
+          };
+          request.onsuccess = () => resolve(request.result);
+          request.onerror = () => resolve(null);
+          request.onblocked = () => resolve(null);
+        });
+      }
+    }
+    return this.databasePromise;
+  }
+  request(database, mode, createRequest) {
+    return new Promise((resolve, reject) => {
+      let transaction;
+      let request;
+      try {
+        transaction = database.transaction(DOWNLOAD_STORE_NAME, mode);
+        request = createRequest(transaction.objectStore(DOWNLOAD_STORE_NAME));
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      let result;
+      request.onsuccess = () => {
+        result = request.result;
+      };
+      request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+      transaction.oncomplete = () => resolve(result);
+      transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB transaction failed"));
+      transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB transaction aborted"));
+    });
+  }
+};
+var DownloadHttpError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "DownloadHttpError";
+    this.status = status;
+  }
+};
+function getShowSaveFilePicker() {
+  return globalThis.showSaveFilePicker ?? null;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readSafeNumber(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`Mountra export response field ${field} is invalid`);
+  }
+  return value;
+}
+function readString(value, field) {
+  if (typeof value !== "string" || !value) {
+    throw new TypeError(`Mountra export response field ${field} is invalid`);
+  }
+  return value;
+}
+function ensureExportFileResponse(value) {
+  if (!isRecord(value)) {
+    throw new TypeError("Mountra export response is invalid");
+  }
+  const response = {
+    path: readString(value.path, "path"),
+    storageKey: readString(value.storage_key, "storage_key"),
+    url: readString(value.url, "url"),
+    timeout: readSafeNumber(value.timeout, "timeout"),
+    size: readSafeNumber(value.size, "size")
+  };
+  try {
+    new URL(response.url);
+  } catch {
+    throw new TypeError("Mountra export response field url is invalid");
+  }
+  if (typeof value.content_type === "string" && value.content_type) {
+    response.contentType = value.content_type;
+  }
+  if (typeof value.chunk_method === "string") {
+    response.chunkMethod = value.chunk_method;
+  }
+  if (typeof value.is_fast_path === "boolean") {
+    response.isFastPath = value.is_fast_path;
+  }
+  if (Array.isArray(value.chunks)) {
+    response.chunks = value.chunks.map((rawChunk, position) => {
+      if (!isRecord(rawChunk)) {
+        throw new TypeError(`Mountra export response chunk ${position} is invalid`);
+      }
+      const chunk = {
+        index: readSafeNumber(rawChunk.index, `chunks[${position}].index`),
+        offset: readSafeNumber(rawChunk.offset, `chunks[${position}].offset`),
+        size: readSafeNumber(rawChunk.size, `chunks[${position}].size`),
+        storageKey: readString(rawChunk.storage_key, `chunks[${position}].storage_key`),
+        url: readString(rawChunk.url, `chunks[${position}].url`)
+      };
+      try {
+        new URL(chunk.url);
+      } catch {
+        throw new TypeError(`Mountra export response chunk ${position} URL is invalid`);
+      }
+      return chunk;
+    });
+    response.chunks.sort((left, right) => left.index - right.index);
+    response.chunks.forEach((chunk, index) => {
+      if (chunk.index !== index || chunk.offset + chunk.size > response.size || index > 0 && response.chunks[index - 1].offset + response.chunks[index - 1].size !== chunk.offset) {
+        throw new TypeError("Mountra export response has an invalid chunk layout");
+      }
+    });
+    const finalChunk = response.chunks[response.chunks.length - 1];
+    if (finalChunk && finalChunk.offset + finalChunk.size !== response.size) {
+      throw new TypeError("Mountra export response chunks do not cover the complete file");
+    }
+  }
+  return response;
+}
+function validateRetryOption(value, name) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError(`${name} must be a non-negative safe integer`);
+  }
+  return value;
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new DOMException("The download was aborted", "AbortError");
+  }
+}
+function isAbortError(error, signal) {
+  return signal?.aborted === true || error instanceof DOMException && error.name === "AbortError";
+}
+function isRetryableError(error) {
+  if (error instanceof DownloadHttpError) {
+    return [408, 425, 429, 500, 502, 503, 504].includes(error.status);
+  }
+  return true;
+}
+function waitForRetry(delayMs, signal) {
+  if (delayMs <= 0) {
+    throwIfAborted(signal);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    let timer;
+    const onAbort = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+      signal?.removeEventListener("abort", onAbort);
+      reject(new DOMException("The download was aborted", "AbortError"));
+    };
+    timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, delayMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+    }
+  });
+}
+var SpeedWindow = class {
+  samples = [];
+  record(bytes, at) {
+    this.samples.push({ at, bytes });
+    const cutoff = at - 1e3;
+    while (this.samples.length > 1 && this.samples[0].at < cutoff) {
+      this.samples.shift();
+    }
+    const first = this.samples[0];
+    if (!first || first.bytes === bytes) {
+      return 0;
+    }
+    const seconds = Math.max((at - first.at) / 1e3, 1e-3);
+    return (bytes - first.bytes) / seconds;
+  }
+};
+var BlobDownloadSink = class {
+  parts = [];
+  /** Parts arrive in file order, so the position is implied. */
+  async write(bytes, _position) {
+    this.parts.push(bytes instanceof Blob ? bytes : bytes.slice());
+  }
+  async flush() {
+  }
+  async finalize() {
+  }
+  blob(contentType) {
+    const buffers = this.parts.map((part) => {
+      if (part instanceof Blob) {
+        return part;
+      }
+      const buffer = new ArrayBuffer(part.byteLength);
+      new Uint8Array(buffer).set(part);
+      return buffer;
+    });
+    return new Blob(buffers, contentType ? { type: contentType } : void 0);
+  }
+};
+var FileSystemDownloadSink = class {
+  constructor(handle) {
+    this.handle = handle;
+  }
+  handle;
+  writable = null;
+  position = 0;
+  openedOnce = false;
+  async write(bytes, position) {
+    if (!this.writable) {
+      const keepExistingData = this.openedOnce || position > 0;
+      this.writable = await this.handle.createWritable({ keepExistingData });
+      if (position > 0) {
+        await this.writable.seek(position);
+      }
+      this.position = position;
+      this.openedOnce = true;
+    }
+    if (this.position !== position) {
+      throw new Error("File System Access writer position does not match the download checkpoint");
+    }
+    await this.writable.write(bytes);
+    this.position += bytes instanceof Blob ? bytes.size : bytes.byteLength;
+  }
+  async flush() {
+    if (this.writable) {
+      const writable = this.writable;
+      await writable.close();
+      this.writable = null;
+    }
+  }
+  async finalize(size) {
+    if (!this.writable) {
+      this.writable = await this.handle.createWritable({ keepExistingData: this.openedOnce });
+      this.openedOnce = true;
+      await this.writable.seek(size);
+    }
+    await this.writable.truncate(size);
+    const writable = this.writable;
+    this.writable = null;
+    await writable.close();
+  }
+  async abort() {
+    if (!this.writable) {
+      return;
+    }
+    const writable = this.writable;
+    this.writable = null;
+    if (writable.abort) {
+      await writable.abort();
+    } else {
+      await writable.close();
+    }
+  }
+};
+function downloadRequestFromOptions(options) {
+  if (options.path === void 0 && options.ino === void 0) {
+    throw new TypeError("download target requires path or ino");
+  }
+  if (options.path !== void 0 && !options.path.trim()) {
+    throw new TypeError("download path cannot be empty");
+  }
+  return {
+    ...options.workspaceCuid !== void 0 ? { workspaceCuid: options.workspaceCuid } : {},
+    ...options.workspaceId !== void 0 ? { workspaceId: options.workspaceId } : {},
+    ...options.path !== void 0 ? { path: options.path } : {},
+    ...options.ino !== void 0 ? { ino: options.ino } : {},
+    ...options.timeout !== void 0 ? { timeout: options.timeout } : {},
+    ...options.contentDisposition !== void 0 ? { contentDisposition: options.contentDisposition } : {},
+    ...options.downloadFilename !== void 0 ? { downloadFilename: options.downloadFilename } : {}
+  };
+}
+function requestBodyFromCheckpoint(request) {
+  return {
+    ...request.workspaceCuid !== void 0 ? { workspace_cuid: request.workspaceCuid } : {},
+    ...request.workspaceId !== void 0 ? { workspace_id: request.workspaceId } : {},
+    ...request.path !== void 0 ? { path: request.path } : {},
+    ...request.ino !== void 0 ? { ino: request.ino } : {},
+    ...request.timeout !== void 0 ? { timeout: request.timeout } : {},
+    ...request.contentDisposition !== void 0 ? { content_disposition: request.contentDisposition } : {},
+    ...request.downloadFilename !== void 0 ? { download_filename: request.downloadFilename } : {}
+  };
+}
+function requestKey(request, baseUrl) {
+  return encodeURIComponent(
+    JSON.stringify({
+      baseUrl,
+      workspaceCuid: request.workspaceCuid ?? null,
+      workspaceId: request.workspaceId ?? null,
+      path: request.path ?? null,
+      ino: request.ino ?? null
+    })
+  );
+}
+function buildDownloadChunks(exported, useClientAssembly) {
+  if (useClientAssembly && exported.chunks && exported.chunks.length > 1) {
+    return exported.chunks;
+  }
+  return [
+    {
+      index: 0,
+      offset: 0,
+      size: exported.size,
+      storageKey: exported.storageKey,
+      url: exported.url
+    }
+  ];
+}
+function buildDownloadKey(plan, baseUrl, request) {
+  return encodeURIComponent(
+    JSON.stringify({
+      request: requestKey(request, baseUrl),
+      path: plan.path,
+      size: plan.size,
+      chunks: plan.chunks.map((chunk) => [chunk.index, chunk.offset, chunk.size, chunk.storageKey])
+    })
+  );
+}
+function checkpointMatches(checkpoint, plan) {
+  if (checkpoint.version !== 1 || checkpoint.path !== plan.path || checkpoint.size !== plan.size) {
+    return false;
+  }
+  if (checkpoint.chunks.length !== plan.chunks.length) {
+    return false;
+  }
+  return checkpoint.chunks.every((saved, index) => {
+    const current = plan.chunks[index];
+    return Boolean(
+      current && saved.index === current.index && saved.offset === current.offset && saved.size === current.size && saved.storageKey === current.storageKey && saved.downloadedBytes >= 0 && saved.downloadedBytes <= saved.size
+    );
+  });
+}
+function createCheckpoint(key, baseUrl, request, plan, fileHandle) {
+  return {
+    version: 1,
+    key,
+    requestKey: requestKey(request, baseUrl),
+    request: { ...request },
+    path: plan.path,
+    size: plan.size,
+    chunks: plan.chunks.map((chunk) => ({
+      index: chunk.index,
+      offset: chunk.offset,
+      size: chunk.size,
+      storageKey: chunk.storageKey,
+      downloadedBytes: 0,
+      completed: chunk.size === 0
+    })),
+    ...fileHandle ? { fileHandle } : {},
+    updatedAt: Date.now()
+  };
+}
+function totalDownloadedBytes(checkpoint) {
+  return checkpoint.chunks.reduce((total, chunk) => total + chunk.downloadedBytes, 0);
+}
+function completedChunkCount(checkpoint) {
+  return checkpoint.chunks.filter((chunk) => chunk.completed).length;
+}
+function defaultFilename(path, requested) {
+  const candidate = requested?.trim() || path.split("/").filter(Boolean).pop() || "download";
+  return candidate.replace(/[\\/\r\n]/g, "_") || "download";
+}
+function triggerBrowserDownload(blob, filename) {
+  const documentValue = globalThis.document;
+  const urlApi = globalThis.URL;
+  if (!documentValue || !urlApi?.createObjectURL) {
+    return;
+  }
+  const url = urlApi.createObjectURL(blob);
+  const anchor = documentValue.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.style.display = "none";
+  documentValue.body?.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => urlApi.revokeObjectURL(url), 0);
+}
+var MountraDownloader = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async exportFile(options) {
+    return this.exportRequest(this.resolveRequest(options), options.signal);
+  }
+  async downloadFile(options) {
+    const preferFileSystemAccess = options.preferFileSystemAccess !== false;
+    const fileHandle = options.fileHandle ?? (preferFileSystemAccess && getShowSaveFilePicker() ? await this.pickSaveFile(options.downloadFilename ?? options.path?.split("/").filter(Boolean).pop()) : void 0);
+    const request = this.resolveRequest(options);
+    const plan = await this.loadCachedPlan(request, options.cache) ?? this.planExport(
+      await this.exportRequest(request, options.signal),
+      request,
+      options.cache,
+      fileHandle
+    );
+    return this.downloadResolved(plan, request, options, fileHandle, false);
+  }
+  async downloadExport(exported, options = { path: exported.path }) {
+    let fileHandle = options.fileHandle;
+    if (!fileHandle && options.preferFileSystemAccess !== false && getShowSaveFilePicker()) {
+      fileHandle = await this.pickSaveFile(
+        options.downloadFilename ?? defaultFilename(exported.path),
+        exported.contentType
+      );
+    }
+    const request = this.resolveRequest(
+      options.path === void 0 && options.ino === void 0 ? { ...options, path: exported.path } : options
+    );
+    return this.downloadResolved(
+      this.planExport(exported, request, options.cache, fileHandle),
+      request,
+      options,
+      fileHandle,
+      false
+    );
+  }
+  async resumeDownload(downloadKey, options = {}) {
+    if (!downloadKey.trim()) {
+      throw new TypeError("downloadKey is required");
+    }
+    const checkpoint = await this.transport.checkpointStore.load(downloadKey);
+    if (!checkpoint || !checkpoint.fileHandle) {
+      throw new Error("No resumable File System Access download was found");
+    }
+    await this.ensureWritePermission(checkpoint.fileHandle);
+    const exported = await this.exportFile({
+      ...checkpoint.request,
+      signal: options.signal
+    });
+    return this.downloadResolved(
+      this.planExport(exported, checkpoint.request, void 0, checkpoint.fileHandle),
+      checkpoint.request,
+      options,
+      checkpoint.fileHandle,
+      true
+    );
+  }
+  listResumableDownloads() {
+    return this.transport.checkpointStore.list();
+  }
+  clearDownloadCheckpoint(downloadKey) {
+    return this.transport.checkpointStore.remove(downloadKey);
+  }
+  /** Drop the cached layout of a file that was just written, so the next download sees the new content. */
+  async invalidateCachedFile(selector, target) {
+    await this.cachedFileScope(selector, target)?.invalidate();
+  }
+  /**
+   * Cache a file this client just uploaded, so downloading it needs no
+   * network. Falls back to invalidation when any chunk cannot be cached.
+   */
+  async cacheUploadedFile(selector, file, mode = "default") {
+    const scope = this.cachedFileScope(selector, file);
+    if (!scope) {
+      return;
+    }
+    await scope.invalidate();
+    if (mode === "no-store") {
+      return;
+    }
+    let complete = true;
+    for (const chunk of file.chunks) {
+      complete = await scope.cache.storeChunk(scope.workspace, chunk, chunk.data) && complete;
+    }
+    if (complete) {
+      for (const fileKey of scope.fileKeys) {
+        await scope.cache.storeFile(scope.workspace, fileKey, file);
+      }
+    }
+  }
+  cachedFileScope(selector, target) {
+    const cache = this.transport.cache;
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    if (!cache || workspace === null) {
+      return null;
+    }
+    const fileKeys = [
+      target.path !== void 0 ? fileCacheKey({ path: target.path }) : null,
+      target.ino !== void 0 ? fileCacheKey({ ino: target.ino }) : null
+    ].filter((fileKey) => fileKey !== null);
+    return {
+      cache,
+      workspace,
+      fileKeys,
+      invalidate: () => cache.invalidateFiles(workspace, fileKeys)
+    };
+  }
+  async clearCache(selector) {
+    const cache = this.transport.cache;
+    if (!cache) {
+      return;
+    }
+    await cache.clear(selector === void 0 ? void 0 : this.requireCacheWorkspace(selector));
+  }
+  async cacheUsage(selector) {
+    const cache = this.transport.cache;
+    if (!cache) {
+      return { bytes: 0, chunks: 0 };
+    }
+    return cache.usage(selector === void 0 ? void 0 : this.requireCacheWorkspace(selector));
+  }
+  requireCacheWorkspace(selector) {
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    if (workspace === null) {
+      throw new TypeError("workspaceCuid or workspaceId is required");
+    }
+    return workspace;
+  }
+  /** Fall back to the client workspace only when the request names none, as uploads do. */
+  resolveRequest(options) {
+    const hasWorkspace = options.workspaceCuid !== void 0 || options.workspaceId !== void 0;
+    return downloadRequestFromOptions(
+      hasWorkspace ? options : {
+        ...options,
+        workspaceCuid: this.transport.clientSelector.workspaceCuid,
+        workspaceId: this.transport.clientSelector.workspaceId
+      }
+    );
+  }
+  async exportRequest(request, signal) {
+    return ensureExportFileResponse(
+      await this.transport.requestJson("/file/export", requestBodyFromCheckpoint(request), signal)
+    );
+  }
+  cacheScope(request, mode = "default") {
+    const cache = this.transport.cache;
+    if (!cache || mode === "no-store") {
+      return null;
+    }
+    const workspace = workspaceCacheKey(this.transport.baseUrl, request);
+    const fileKey = fileCacheKey(request);
+    return workspace !== null && fileKey !== null ? { cache, workspace, fileKey } : null;
+  }
+  /** A plan that needs no network at all, when the cached layout is fresh and every chunk is cached. */
+  async loadCachedPlan(request, mode) {
+    const scope = this.cacheScope(request, mode);
+    if (!scope || mode === "no-cache") {
+      return null;
+    }
+    const cached = await scope.cache.loadFile(scope.workspace, scope.fileKey);
+    if (!cached) {
+      return null;
+    }
+    return {
+      path: cached.file.path,
+      size: cached.file.size,
+      ...cached.file.contentType ? { contentType: cached.file.contentType } : {},
+      chunks: cached.file.chunks,
+      cachedChunks: cached.chunks
+    };
+  }
+  planExport(exported, request, mode, fileHandle) {
+    const useClientAssembly = (exported.chunks?.length ?? 0) > 1 && (Boolean(fileHandle) || this.cacheScope(request, mode) !== null);
+    return {
+      path: exported.path,
+      size: exported.size,
+      ...exported.contentType ? { contentType: exported.contentType } : {},
+      chunks: buildDownloadChunks(exported, useClientAssembly),
+      exported
+    };
+  }
+  async pickSaveFile(requestedFilename, contentType) {
+    const picker = getShowSaveFilePicker();
+    if (!picker) {
+      throw new Error("File System Access API is not available");
+    }
+    const types = contentType ? [{ description: contentType, accept: { [contentType]: ["." + (requestedFilename?.split(".").pop() || "bin")] } }] : void 0;
+    return picker({
+      suggestedName: requestedFilename?.trim() || "download",
+      ...types ? { types } : {}
+    });
+  }
+  async ensureWritePermission(handle) {
+    if (!handle.queryPermission && !handle.requestPermission) {
+      return;
+    }
+    const descriptor = { mode: "readwrite" };
+    const current = await handle.queryPermission?.(descriptor);
+    if (current === "granted") {
+      return;
+    }
+    const requested = await handle.requestPermission?.(descriptor);
+    if (requested !== void 0 && requested !== "granted") {
+      throw new DOMException("Write permission was not granted", "NotAllowedError");
+    }
+  }
+  async downloadResolved(plan, request, options, fileHandle, forceResume) {
+    const chunks = plan.chunks;
+    const key = buildDownloadKey(plan, this.transport.baseUrl, request);
+    const existing = await this.transport.checkpointStore.load(key);
+    const resumeRequested = !("resume" in options) || options.resume !== false;
+    let checkpoint = existing && checkpointMatches(existing, plan) && (forceResume || resumeRequested) && (forceResume || fileHandle && await this.isSameFileHandle(existing.fileHandle, fileHandle)) ? existing : createCheckpoint(key, this.transport.baseUrl, request, plan, fileHandle);
+    const cacheScope = this.cacheScope(request, "cache" in options ? options.cache : void 0);
+    const cachedChunkIndexes = /* @__PURE__ */ new Set();
+    let cachedBytes = 0;
+    if (fileHandle) {
+      checkpoint.fileHandle = fileHandle;
+    }
+    const resumed = totalDownloadedBytes(checkpoint) > 0;
+    const maxRetries = validateRetryOption(options.maxRetries, "maxRetries") ?? 3;
+    const retryDelayMs = validateRetryOption(options.retryDelayMs, "retryDelayMs") ?? 500;
+    const sink = fileHandle ? new FileSystemDownloadSink(fileHandle) : new BlobDownloadSink();
+    const speedWindow = new SpeedWindow();
+    const startedAt = Date.now();
+    let retryCount = 0;
+    let lastCheckpointAt = 0;
+    const emit = (phase, currentChunkIndex) => {
+      const downloadedBytes = totalDownloadedBytes(checkpoint);
+      const speedBytesPerSecond = speedWindow.record(downloadedBytes, Date.now());
+      const remainingBytes = Math.max(plan.size - downloadedBytes, 0);
+      options.onProgress?.({
+        phase,
+        downloadedBytes,
+        totalBytes: plan.size,
+        downloadedChunks: completedChunkCount(checkpoint),
+        totalChunks: checkpoint.chunks.length,
+        ...currentChunkIndex !== void 0 ? { currentChunkIndex } : {},
+        speedBytesPerSecond,
+        ...speedBytesPerSecond > 0 && remainingBytes > 0 ? { estimatedRemainingSeconds: remainingBytes / speedBytesPerSecond } : {},
+        elapsedMs: Date.now() - startedAt,
+        retryCount
+      });
+    };
+    const persist = async (force) => {
+      const now = Date.now();
+      if (!force && now - lastCheckpointAt < 1e3) {
+        return;
+      }
+      await sink.flush();
+      checkpoint.updatedAt = now;
+      await this.transport.checkpointStore.save(key, checkpoint);
+      lastCheckpointAt = now;
+    };
+    await this.transport.checkpointStore.save(key, checkpoint);
+    try {
+      for (const chunk of chunks) {
+        const savedChunk = checkpoint.chunks[chunk.index];
+        if (!savedChunk) {
+          throw new Error(`Missing download checkpoint for chunk ${chunk.index}`);
+        }
+        if (savedChunk.completed) {
+          continue;
+        }
+        const cached = plan.cachedChunks?.get(chunk.index) ?? (cacheScope ? await cacheScope.cache.readChunk(cacheScope.workspace, chunk) : null);
+        if (cached) {
+          throwIfAborted(options.signal);
+          const remaining = cached.slice(savedChunk.downloadedBytes);
+          await sink.write(remaining, chunk.offset + savedChunk.downloadedBytes);
+          cachedBytes += remaining.size;
+          savedChunk.downloadedBytes = chunk.size;
+          savedChunk.completed = true;
+          cachedChunkIndexes.add(chunk.index);
+          emit("downloading", chunk.index);
+          await persist(false);
+          continue;
+        }
+        const url = chunk.url;
+        if (!url) {
+          throw new Error(`Chunk ${chunk.index} is no longer in the download cache`);
+        }
+        const capture = cacheScope && savedChunk.downloadedBytes === 0 && cacheScope.cache.canStoreChunk(chunk) ? [] : null;
+        let attempt = 0;
+        while (true) {
+          throwIfAborted(options.signal);
+          const rangeStart = savedChunk.downloadedBytes;
+          try {
+            const response = await this.transport.fetchImpl(url, {
+              method: "GET",
+              ...rangeStart > 0 ? { headers: { Range: `bytes=${rangeStart}-` } } : {},
+              ...options.signal ? { signal: options.signal } : {}
+            });
+            if (!response.ok) {
+              throw new DownloadHttpError(
+                response.status,
+                `Download for chunk ${chunk.index} failed with HTTP ${response.status}`
+              );
+            }
+            await this.consumeResponse(
+              response,
+              chunk,
+              savedChunk,
+              sink,
+              plan.size,
+              emit,
+              persist,
+              capture,
+              options.signal
+            );
+            if (savedChunk.downloadedBytes !== savedChunk.size) {
+              throw new Error(
+                `Download for chunk ${chunk.index} ended at ${savedChunk.downloadedBytes} of ${savedChunk.size} bytes`
+              );
+            }
+            savedChunk.completed = true;
+            await persist(true);
+            if (cacheScope && capture && await cacheScope.cache.storeChunk(cacheScope.workspace, chunk, new Blob(capture))) {
+              cachedChunkIndexes.add(chunk.index);
+            }
+            emit("downloading", chunk.index);
+            break;
+          } catch (error) {
+            await persist(true);
+            if (isAbortError(error, options.signal) || !isRetryableError(error) || attempt >= maxRetries) {
+              throw error;
+            }
+            attempt += 1;
+            retryCount += 1;
+            emit("retrying", chunk.index);
+            await waitForRetry(Math.min(retryDelayMs * 2 ** (attempt - 1), 3e4), options.signal);
+          }
+        }
+      }
+      if (totalDownloadedBytes(checkpoint) !== plan.size) {
+        throw new Error("Download completed with an unexpected byte count");
+      }
+      if (fileHandle) {
+        await sink.finalize(plan.size);
+      } else {
+        await sink.finalize();
+      }
+      await this.transport.checkpointStore.remove(key);
+      if (cacheScope && plan.exported && chunks.every((chunk) => chunk.size === 0 || cachedChunkIndexes.has(chunk.index))) {
+        await cacheScope.cache.storeFile(cacheScope.workspace, cacheScope.fileKey, plan);
+      }
+      emit("completed");
+      const blob = sink instanceof BlobDownloadSink ? sink.blob(plan.contentType) : void 0;
+      if (blob) {
+        const filename = "downloadFilename" in options ? options.downloadFilename : void 0;
+        triggerBrowserDownload(blob, defaultFilename(plan.path, filename));
+      }
+      return {
+        ...plan.exported ? { export: plan.exported } : {},
+        downloadKey: key,
+        downloadedBytes: plan.size,
+        cachedBytes,
+        resumed,
+        ...fileHandle ? { fileHandle } : {},
+        ...blob ? { blob } : {}
+      };
+    } catch (error) {
+      await persist(true);
+      throw error;
+    }
+  }
+  async consumeResponse(response, chunk, savedChunk, sink, totalSize, emit, persist, capture, signal) {
+    const sourceOffset = savedChunk.downloadedBytes;
+    let bytesToSkip = response.status === 200 && sourceOffset > 0 ? sourceOffset : 0;
+    const reader = response.body?.getReader();
+    if (!reader) {
+      const body = new Uint8Array(await response.arrayBuffer());
+      await this.consumeBytes(body, bytesToSkip, chunk, savedChunk, sink, totalSize, emit, persist, capture, signal);
+      return;
+    }
+    try {
+      while (true) {
+        throwIfAborted(signal);
+        const next = await reader.read();
+        if (next.done) {
+          break;
+        }
+        const bytes = next.value;
+        if (bytesToSkip > 0) {
+          const skipped = Math.min(bytesToSkip, bytes.byteLength);
+          bytesToSkip -= skipped;
+          if (skipped === bytes.byteLength) {
+            continue;
+          }
+          await this.consumeBytes(
+            bytes.subarray(skipped),
+            0,
+            chunk,
+            savedChunk,
+            sink,
+            totalSize,
+            emit,
+            persist,
+            capture,
+            signal
+          );
+        } else {
+          await this.consumeBytes(bytes, 0, chunk, savedChunk, sink, totalSize, emit, persist, capture, signal);
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    if (bytesToSkip > 0) {
+      throw new Error(`Download response did not contain the saved offset for chunk ${chunk.index}`);
+    }
+  }
+  async consumeBytes(bytes, offset, chunk, savedChunk, sink, totalSize, emit, persist, capture, signal) {
+    const remaining = chunk.size - savedChunk.downloadedBytes;
+    const writableBytes = bytes.byteLength - offset;
+    if (writableBytes > remaining) {
+      throw new Error(`Download response for chunk ${chunk.index} is larger than expected`);
+    }
+    if (writableBytes === 0) {
+      return;
+    }
+    throwIfAborted(signal);
+    const payload = bytes.subarray(offset);
+    const position = chunk.offset + savedChunk.downloadedBytes;
+    await sink.write(payload, position);
+    capture?.push(payload.slice());
+    savedChunk.downloadedBytes += payload.byteLength;
+    emit("downloading", chunk.index);
+    await persist(false);
+    if (savedChunk.downloadedBytes > totalSize) {
+      throw new Error("Download byte count exceeded the exported file size");
+    }
+  }
+  async isSameFileHandle(savedHandle, selectedHandle) {
+    if (!savedHandle) {
+      return false;
+    }
+    if (savedHandle === selectedHandle) {
+      return true;
+    }
+    if (savedHandle.isSameEntry) {
+      try {
+        return await savedHandle.isSameEntry(selectedHandle);
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+};
+
 // src/upload.ts
 var JUMBO_CHUNK_THRESHOLD_BYTES = 128 * 1024 * 1024;
 var MIN_S3_MULTIPART_PART_SIZE_BYTES = 5 * 1024 * 1024;
@@ -56,7 +1603,7 @@ var MountraApiError = class extends Error {
 };
 var memoryCheckpointRecords = /* @__PURE__ */ new Map();
 function parseJumboCheckpoint(value) {
-  if (!isRecord(value) || value.version !== 1 || typeof value.storageKey !== "string") {
+  if (!isRecord2(value) || value.version !== 1 || typeof value.storageKey !== "string") {
     return null;
   }
   if (typeof value.chunkIndex !== "number" || typeof value.chunkSize !== "number" || typeof value.chunkSha256 !== "string" || typeof value.partSize !== "number" || typeof value.uploadId !== "string" || !Array.isArray(value.parts)) {
@@ -64,7 +1611,7 @@ function parseJumboCheckpoint(value) {
   }
   const parts = [];
   for (const part of value.parts) {
-    if (!isRecord(part)) {
+    if (!isRecord2(part)) {
       return null;
     }
     if (typeof part.partNumber !== "number" || typeof part.etag !== "string" || typeof part.size !== "number" || typeof part.sha256 !== "string") {
@@ -237,17 +1784,17 @@ function getWorkspaceBody(clientSelector, requestSelector) {
     ...workspaceId !== void 0 ? { workspace_id: workspaceId } : {}
   };
 }
-function throwIfAborted(signal) {
+function throwIfAborted2(signal) {
   if (!signal?.aborted) {
     return;
   }
   throw new DOMException("The upload was aborted", "AbortError");
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
 function parseApiErrorBody(body) {
-  if (!isRecord(body)) {
+  if (!isRecord2(body)) {
     return {};
   }
   return {
@@ -256,7 +1803,7 @@ function parseApiErrorBody(body) {
   };
 }
 function ensurePrepareResponse(value) {
-  if (!isRecord(value) || typeof value.upload_id !== "string") {
+  if (!isRecord2(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra prepare response is invalid");
   }
   if (!Array.isArray(value.upload_targets)) {
@@ -265,13 +1812,13 @@ function ensurePrepareResponse(value) {
   return value;
 }
 function ensureFinishResponse(value) {
-  if (!isRecord(value) || typeof value.upload_id !== "string") {
+  if (!isRecord2(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra finish response is invalid");
   }
   return value;
 }
 function ensureUploadStatusResponse(value) {
-  if (!isRecord(value) || typeof value.upload_id !== "string") {
+  if (!isRecord2(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra upload status response is invalid");
   }
   if (!Array.isArray(value.chunks)) {
@@ -289,8 +1836,7 @@ function splitFileIntoChunks(file, chunkCount = 1) {
   }
   const chunkSize = Math.ceil(file.size / chunkCount);
   const chunks = [];
-  for (let index = 0; index < chunkCount; index += 1) {
-    const offset = index * chunkSize;
+  for (let index = 0, offset = 0; offset < file.size; index += 1, offset += chunkSize) {
     const end = Math.min(offset + chunkSize, file.size);
     chunks.push({
       index,
@@ -322,6 +1868,7 @@ var MountraClient = class {
   jumboChunkUploader;
   jumboChunkCheckpointStore;
   jumboPartSize;
+  downloader;
   constructor(options) {
     this.baseUrl = normalizeBaseUrl(options.baseUrl);
     this.apiPrefix = normalizeApiPrefix(options.apiPrefix ?? "/api");
@@ -340,6 +1887,46 @@ var MountraClient = class {
       throw new Error("fetch is not available; provide fetch in MountraClientOptions");
     }
     this.fetchImpl = fetchImpl;
+    this.downloader = new MountraDownloader({
+      baseUrl: this.baseUrl,
+      clientSelector: this.clientSelector,
+      fetchImpl: this.fetchImpl,
+      checkpointStore: options.downloadCheckpointStore ?? new IndexedDBDownloadCheckpointStore(),
+      cache: options.downloadCache ? new DownloadCache(options.downloadCache) : null,
+      requestJson: (path, body, signal) => this.requestJson(path, body, signal)
+    });
+  }
+  async exportFile(options) {
+    return this.downloader.exportFile(options);
+  }
+  async downloadFile(options) {
+    return this.downloader.downloadFile(options);
+  }
+  async downloadExport(exported, options) {
+    return this.downloader.downloadExport(exported, options);
+  }
+  async resumeDownload(downloadKey, options) {
+    return this.downloader.resumeDownload(downloadKey, options);
+  }
+  listResumableDownloads() {
+    return this.downloader.listResumableDownloads();
+  }
+  clearDownloadCheckpoint(downloadKey) {
+    return this.downloader.clearDownloadCheckpoint(downloadKey);
+  }
+  /** Clear the download cache of one workspace, or of every workspace when none is given. */
+  clearDownloadCache(selector) {
+    return this.downloader.clearCache(selector);
+  }
+  getDownloadCacheUsage(selector) {
+    return this.downloader.cacheUsage(selector);
+  }
+  /** Create a stable resource object for one file in this or another workspace. */
+  file(locator) {
+    return new MountraFile(
+      this,
+      normalizeMountraFileLocator(locator, this.clientSelector)
+    );
   }
   async prepareUpload(file, options) {
     const chunks = splitFileIntoChunks(file, options.chunkCount ?? 1);
@@ -347,7 +1934,7 @@ var MountraClient = class {
     const contentHash = await sha256Hex(file);
     const chunkMethod = chunks.length === 1 ? "none" : "fix";
     const contentType = options.contentType ?? ("type" in file ? file.type : void 0);
-    throwIfAborted(options.signal);
+    throwIfAborted2(options.signal);
     const response = ensurePrepareResponse(
       await this.requestJson("/upload/prepare", {
         ...getWorkspaceBody(this.clientSelector, options),
@@ -450,7 +2037,7 @@ var MountraClient = class {
       if (!chunk || target.chunk_index !== position) {
         throw new Error("Mountra upload targets must contain contiguous chunk indexes");
       }
-      throwIfAborted(options.signal);
+      throwIfAborted2(options.signal);
       if (isJumboChunk(chunk.size)) {
         const checkpointKey = this.buildJumboCheckpointKey(context, target, options);
         jumboCheckpointKeys.add(checkpointKey);
@@ -493,7 +2080,7 @@ var MountraClient = class {
         totalChunks: orderedTargets.length
       });
     }
-    throwIfAborted(options.signal);
+    throwIfAborted2(options.signal);
     options.onProgress?.({
       phase: "finishing",
       uploadedBytes: file.size,
@@ -514,6 +2101,26 @@ var MountraClient = class {
     if (finished.finish_status !== "completed") {
       throw new Error(`Mountra upload did not finish successfully: ${finished.finish_status}`);
     }
+    await this.downloader.cacheUploadedFile(
+      this.cacheWorkspace(options),
+      {
+        path: finished.path,
+        ...finished.ino !== void 0 ? { ino: finished.ino } : {},
+        size: context.fileSize,
+        ...context.contentType ? { contentType: context.contentType } : {},
+        chunks: orderedTargets.map((target) => {
+          const chunk = chunks[target.chunk_index];
+          return {
+            index: chunk.index,
+            offset: chunk.offset,
+            size: chunk.size,
+            storageKey: target.storage_key,
+            data: chunk.blob
+          };
+        })
+      },
+      options.cache
+    );
     await Promise.all(
       [...jumboCheckpointKeys].map(
         (checkpointKey) => this.jumboChunkCheckpointStore.remove(checkpointKey)
@@ -597,7 +2204,7 @@ var MountraClient = class {
     let uploadedBytes = 0;
     let uploadedParts = 0;
     for (let partNumber = 1; partNumber <= totalParts; partNumber += 1) {
-      throwIfAborted(options.signal);
+      throwIfAborted2(options.signal);
       const start = (partNumber - 1) * this.jumboPartSize;
       const partBlob = chunk.blob.slice(start, Math.min(start + this.jumboPartSize, chunk.size));
       const partHash = await sha256Hex(partBlob);
@@ -689,12 +2296,26 @@ var MountraClient = class {
     if (!uploadId.trim()) {
       throw new TypeError("uploadId is required");
     }
-    return ensureFinishResponse(
+    const finished = ensureFinishResponse(
       await this.requestJson("/upload/finish", {
         ...getWorkspaceBody(this.clientSelector, selector),
         upload_id: uploadId
       })
     );
+    if (finished.finish_status === "completed") {
+      await this.downloader.invalidateCachedFile(this.cacheWorkspace(selector), {
+        path: finished.path,
+        ...finished.ino !== void 0 ? { ino: finished.ino } : {}
+      });
+    }
+    return finished;
+  }
+  /** Same workspace resolution as `getWorkspaceBody`, so the cache key matches what Mountra used. */
+  cacheWorkspace(selector) {
+    return {
+      workspaceCuid: selector.workspaceCuid ?? this.clientSelector.workspaceCuid,
+      workspaceId: selector.workspaceId ?? this.clientSelector.workspaceId
+    };
   }
   endpoint(path) {
     return `${this.baseUrl}${this.apiPrefix}${path}`;
@@ -734,13 +2355,20 @@ function createMountraClient(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_S3_MULTIPART_PART_SIZE_BYTES,
+  DownloadHttpError,
+  InMemoryDownloadCacheStore,
+  InMemoryDownloadCheckpointStore,
   InMemoryJumboChunkCheckpointStore,
+  IndexedDBDownloadCacheStore,
+  IndexedDBDownloadCheckpointStore,
   JUMBO_CHUNK_THRESHOLD_BYTES,
   LocalStorageJumboChunkCheckpointStore,
   MAX_S3_MULTIPART_PARTS,
   MIN_S3_MULTIPART_PART_SIZE_BYTES,
   MountraApiError,
   MountraClient,
+  MountraDownloader,
+  MountraFile,
   MountraSDK,
   S3MultipartUploader,
   createMountraClient,