@mountra/mountra-sdk 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -22,8 +22,10 @@ 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,
@@ -42,6 +44,609 @@ __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 {
@@ -69,7 +674,7 @@ var InMemoryDownloadCheckpointStore = class {
 var DOWNLOAD_DATABASE_NAME = "mountra-sdk";
 var DOWNLOAD_DATABASE_VERSION = 1;
 var DOWNLOAD_STORE_NAME = "download-checkpoints";
-function getIndexedDb() {
+function getIndexedDb2() {
   return globalThis.indexedDB ?? null;
 }
 var IndexedDBDownloadCheckpointStore = class {
@@ -134,7 +739,7 @@ var IndexedDBDownloadCheckpointStore = class {
   }
   async openDatabase() {
     if (!this.databasePromise) {
-      const indexedDb = getIndexedDb();
+      const indexedDb = getIndexedDb2();
       if (!indexedDb) {
         this.databasePromise = Promise.resolve(null);
       } else {
@@ -329,8 +934,9 @@ var SpeedWindow = class {
 };
 var BlobDownloadSink = class {
   parts = [];
-  async write(bytes) {
-    this.parts.push(bytes.slice());
+  /** 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() {
   }
@@ -338,6 +944,9 @@ var BlobDownloadSink = class {
   }
   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;
@@ -367,7 +976,7 @@ var FileSystemDownloadSink = class {
       throw new Error("File System Access writer position does not match the download checkpoint");
     }
     await this.writable.write(bytes);
-    this.position += bytes.byteLength;
+    this.position += bytes instanceof Blob ? bytes.size : bytes.byteLength;
   }
   async flush() {
     if (this.writable) {
@@ -453,39 +1062,39 @@ function buildDownloadChunks(exported, useClientAssembly) {
     }
   ];
 }
-function buildDownloadKey(exported, chunks, baseUrl, request) {
+function buildDownloadKey(plan, baseUrl, request) {
   return encodeURIComponent(
     JSON.stringify({
       request: requestKey(request, baseUrl),
-      path: exported.path,
-      size: exported.size,
-      chunks: chunks.map((chunk) => [chunk.index, chunk.offset, chunk.size, chunk.storageKey])
+      path: plan.path,
+      size: plan.size,
+      chunks: plan.chunks.map((chunk) => [chunk.index, chunk.offset, chunk.size, chunk.storageKey])
     })
   );
 }
-function checkpointMatches(checkpoint, exported, chunks) {
-  if (checkpoint.version !== 1 || checkpoint.path !== exported.path || checkpoint.size !== exported.size) {
+function checkpointMatches(checkpoint, plan) {
+  if (checkpoint.version !== 1 || checkpoint.path !== plan.path || checkpoint.size !== plan.size) {
     return false;
   }
-  if (checkpoint.chunks.length !== chunks.length) {
+  if (checkpoint.chunks.length !== plan.chunks.length) {
     return false;
   }
   return checkpoint.chunks.every((saved, index) => {
-    const current = chunks[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, exported, chunks, fileHandle) {
+function createCheckpoint(key, baseUrl, request, plan, fileHandle) {
   return {
     version: 1,
     key,
     requestKey: requestKey(request, baseUrl),
     request: { ...request },
-    path: exported.path,
-    size: exported.size,
-    chunks: chunks.map((chunk) => ({
+    path: plan.path,
+    size: plan.size,
+    chunks: plan.chunks.map((chunk) => ({
       index: chunk.index,
       offset: chunk.offset,
       size: chunk.size,
@@ -503,8 +1112,8 @@ function totalDownloadedBytes(checkpoint) {
 function completedChunkCount(checkpoint) {
   return checkpoint.chunks.filter((chunk) => chunk.completed).length;
 }
-function defaultFilename(exported, requested) {
-  const candidate = requested?.trim() || exported.path.split("/").filter(Boolean).pop() || "download";
+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) {
@@ -529,33 +1138,38 @@ var MountraDownloader = class {
     this.transport = transport;
   }
   async exportFile(options) {
-    const request = downloadRequestFromOptions(options);
-    return ensureExportFileResponse(
-      await this.transport.requestJson(
-        "/file/export",
-        requestBodyFromCheckpoint(request),
-        options.signal
-      )
-    );
+    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 exported = await this.exportFile(options);
-    return this.downloadExport(exported, { ...options, ...fileHandle ? { fileHandle } : {} });
+    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),
+        options.downloadFilename ?? defaultFilename(exported.path),
         exported.contentType
       );
     }
-    const request = downloadRequestFromOptions(
+    const request = this.resolveRequest(
       options.path === void 0 && options.ino === void 0 ? { ...options, path: exported.path } : options
     );
-    return this.downloadResolved(exported, request, options, fileHandle, false);
+    return this.downloadResolved(
+      this.planExport(exported, request, options.cache, fileHandle),
+      request,
+      options,
+      fileHandle,
+      false
+    );
   }
   async resumeDownload(downloadKey, options = {}) {
     if (!downloadKey.trim()) {
@@ -571,7 +1185,7 @@ var MountraDownloader = class {
       signal: options.signal
     });
     return this.downloadResolved(
-      exported,
+      this.planExport(exported, checkpoint.request, void 0, checkpoint.fileHandle),
       checkpoint.request,
       options,
       checkpoint.fileHandle,
@@ -584,6 +1198,124 @@ var MountraDownloader = class {
   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) {
@@ -609,13 +1341,15 @@ var MountraDownloader = class {
       throw new DOMException("Write permission was not granted", "NotAllowedError");
     }
   }
-  async downloadResolved(exported, request, options, fileHandle, forceResume) {
-    const useClientAssembly = Boolean(fileHandle && (exported.chunks?.length ?? 0) > 1);
-    const chunks = buildDownloadChunks(exported, useClientAssembly);
-    const key = buildDownloadKey(exported, chunks, this.transport.baseUrl, request);
+  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, exported, chunks) && (forceResume || resumeRequested) && (forceResume || fileHandle && await this.isSameFileHandle(existing.fileHandle, fileHandle)) ? existing : createCheckpoint(key, this.transport.baseUrl, request, exported, chunks, fileHandle);
+    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;
     }
@@ -630,11 +1364,11 @@ var MountraDownloader = class {
     const emit = (phase, currentChunkIndex) => {
       const downloadedBytes = totalDownloadedBytes(checkpoint);
       const speedBytesPerSecond = speedWindow.record(downloadedBytes, Date.now());
-      const remainingBytes = Math.max(exported.size - downloadedBytes, 0);
+      const remainingBytes = Math.max(plan.size - downloadedBytes, 0);
       options.onProgress?.({
         phase,
         downloadedBytes,
-        totalBytes: exported.size,
+        totalBytes: plan.size,
         downloadedChunks: completedChunkCount(checkpoint),
         totalChunks: checkpoint.chunks.length,
         ...currentChunkIndex !== void 0 ? { currentChunkIndex } : {},
@@ -664,12 +1398,30 @@ var MountraDownloader = class {
         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(chunk.url, {
+            const response = await this.transport.fetchImpl(url, {
               method: "GET",
               ...rangeStart > 0 ? { headers: { Range: `bytes=${rangeStart}-` } } : {},
               ...options.signal ? { signal: options.signal } : {}
@@ -685,9 +1437,10 @@ var MountraDownloader = class {
               chunk,
               savedChunk,
               sink,
-              exported.size,
+              plan.size,
               emit,
               persist,
+              capture,
               options.signal
             );
             if (savedChunk.downloadedBytes !== savedChunk.size) {
@@ -697,6 +1450,9 @@ var MountraDownloader = class {
             }
             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) {
@@ -711,25 +1467,29 @@ var MountraDownloader = class {
           }
         }
       }
-      if (totalDownloadedBytes(checkpoint) !== exported.size) {
+      if (totalDownloadedBytes(checkpoint) !== plan.size) {
         throw new Error("Download completed with an unexpected byte count");
       }
       if (fileHandle) {
-        await sink.finalize(exported.size);
+        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(exported.contentType) : void 0;
+      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(exported, filename));
+        triggerBrowserDownload(blob, defaultFilename(plan.path, filename));
       }
       return {
-        export: exported,
+        ...plan.exported ? { export: plan.exported } : {},
         downloadKey: key,
-        downloadedBytes: exported.size,
+        downloadedBytes: plan.size,
+        cachedBytes,
         resumed,
         ...fileHandle ? { fileHandle } : {},
         ...blob ? { blob } : {}
@@ -739,13 +1499,13 @@ var MountraDownloader = class {
       throw error;
     }
   }
-  async consumeResponse(response, chunk, savedChunk, sink, totalSize, emit, persist, signal) {
+  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, signal);
+      await this.consumeBytes(body, bytesToSkip, chunk, savedChunk, sink, totalSize, emit, persist, capture, signal);
       return;
     }
     try {
@@ -771,10 +1531,11 @@ var MountraDownloader = class {
             totalSize,
             emit,
             persist,
+            capture,
             signal
           );
         } else {
-          await this.consumeBytes(bytes, 0, chunk, savedChunk, sink, totalSize, emit, persist, signal);
+          await this.consumeBytes(bytes, 0, chunk, savedChunk, sink, totalSize, emit, persist, capture, signal);
         }
       }
     } finally {
@@ -784,7 +1545,7 @@ var MountraDownloader = class {
       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, signal) {
+  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) {
@@ -796,11 +1557,8 @@ var MountraDownloader = class {
     throwIfAborted(signal);
     const payload = bytes.subarray(offset);
     const position = chunk.offset + savedChunk.downloadedBytes;
-    if (sink instanceof FileSystemDownloadSink) {
-      await sink.write(payload, position);
-    } else {
-      await sink.write(payload);
-    }
+    await sink.write(payload, position);
+    capture?.push(payload.slice());
     savedChunk.downloadedBytes += payload.byteLength;
     emit("downloading", chunk.index);
     await persist(false);
@@ -826,132 +1584,6 @@ var MountraDownloader = class {
   }
 };
 
-// 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/upload.ts
 var JUMBO_CHUNK_THRESHOLD_BYTES = 128 * 1024 * 1024;
 var MIN_S3_MULTIPART_PART_SIZE_BYTES = 5 * 1024 * 1024;
@@ -1204,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,
@@ -1261,6 +1892,7 @@ var MountraClient = class {
       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)
     });
   }
@@ -1282,6 +1914,13 @@ var MountraClient = class {
   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(
@@ -1462,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)
@@ -1637,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}`;
@@ -1683,8 +2356,10 @@ function createMountraClient(options) {
 0 && (module.exports = {
   DEFAULT_S3_MULTIPART_PART_SIZE_BYTES,
   DownloadHttpError,
+  InMemoryDownloadCacheStore,
   InMemoryDownloadCheckpointStore,
   InMemoryJumboChunkCheckpointStore,
+  IndexedDBDownloadCacheStore,
   IndexedDBDownloadCheckpointStore,
   JUMBO_CHUNK_THRESHOLD_BYTES,
   LocalStorageJumboChunkCheckpointStore,