@mountra/mountra-sdk 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,3 +1,655 @@
+// 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 isPathWithin(path, ancestor) {
+  return ancestor === "/" || path === ancestor || path.startsWith(`${ancestor}/`);
+}
+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/idb.ts
+function getIndexedDb() {
+  return globalThis.indexedDB ?? null;
+}
+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;
+}
+function workspaceRange(workspace) {
+  return IDBKeyRange.bound([workspace], [workspace, []]);
+}
+var CLOCK_KEY = "clock";
+async function nextClock(meta) {
+  const clock = (await requestResult(meta.get(CLOCK_KEY)) ?? 0) + 1;
+  await requestResult(meta.put(clock, CLOCK_KEY));
+  return clock;
+}
+function openDatabase(name, version, upgrade, onClose) {
+  const indexedDb = getIndexedDb();
+  if (!indexedDb) {
+    return Promise.resolve(null);
+  }
+  return new Promise((resolve) => {
+    let request;
+    try {
+      request = indexedDb.open(name, version);
+    } catch {
+      resolve(null);
+      return;
+    }
+    request.onupgradeneeded = () => upgrade(request.result);
+    request.onsuccess = () => {
+      const database = request.result;
+      database.onversionchange = () => {
+        database.close();
+        onClose();
+      };
+      resolve(database);
+    };
+    request.onerror = () => resolve(null);
+    request.onblocked = () => resolve(null);
+  });
+}
+
+// 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 removeFilesUnder(workspace, path) {
+    for (const [key, entry] of this.files) {
+      if (entry.workspace === workspace && isPathWithin(entry.file.path, path)) {
+        this.files.delete(key);
+      }
+    }
+  }
+  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";
+function sameKey(left, right) {
+  return Array.isArray(left) && left[0] === right[0] && left[1] === right[1];
+}
+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 removeFilesUnder(workspace, path) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.removeFilesUnder(workspace, path);
+    }
+    await runTransaction(database, [FILES_STORE], "readwrite", async (transaction) => {
+      const cursorRequest = transaction.objectStore(FILES_STORE).openCursor(workspaceRange(workspace));
+      let cursor = await requestResult(cursorRequest);
+      while (cursor) {
+        if (isPathWithin(cursor.value.path, path)) {
+          await requestResult(cursor.delete());
+        }
+        cursor.continue();
+        cursor = await requestResult(cursorRequest);
+      }
+    });
+  }
+  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() {
+    this.databasePromise ??= openDatabase(
+      this.databaseName,
+      CACHE_DATABASE_VERSION,
+      (database) => {
+        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);
+        }
+      },
+      () => {
+        this.databasePromise = void 0;
+      }
+    );
+    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))
+    );
+  }
+  /** Drop the files at or below `paths`, which a write changed; their chunks stay cached. */
+  async invalidatePaths(workspace, paths) {
+    try {
+      if (!this.store.removeFilesUnder) {
+        await this.store.clear(workspace);
+        return;
+      }
+      for (const path of paths) {
+        await this.store.removeFilesUnder(workspace, path);
+      }
+    } catch {
+      await this.store.clear(workspace).catch(() => void 0);
+    }
+  }
+  clear(workspace) {
+    return this.store.clear(workspace);
+  }
+  usage(workspace) {
+    return this.store.usage(workspace);
+  }
+};
+
 // src/download.ts
 function copyCheckpoint(checkpoint) {
   return {
@@ -25,7 +677,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 {
@@ -90,7 +742,7 @@ var IndexedDBDownloadCheckpointStore = class {
   }
   async openDatabase() {
     if (!this.databasePromise) {
-      const indexedDb = getIndexedDb();
+      const indexedDb = getIndexedDb2();
       if (!indexedDb) {
         this.databasePromise = Promise.resolve(null);
       } else {
@@ -285,8 +937,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() {
   }
@@ -294,6 +947,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;
@@ -323,7 +979,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) {
@@ -409,39 +1065,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,
@@ -459,8 +1115,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) {
@@ -485,33 +1141,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()) {
@@ -527,7 +1188,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,
@@ -540,6 +1201,132 @@ 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();
+  }
+  /** Drop the cached files at or below paths that a delete, move, or copy changed. */
+  async invalidateCachedPaths(selector, paths) {
+    const cache = this.transport.cache;
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    if (cache && workspace !== null) {
+      await cache.invalidatePaths(workspace, paths);
+    }
+  }
+  /**
+   * 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) {
@@ -565,13 +1352,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;
     }
@@ -586,11 +1375,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 } : {},
@@ -620,12 +1409,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 } : {}
@@ -641,9 +1448,10 @@ var MountraDownloader = class {
               chunk,
               savedChunk,
               sink,
-              exported.size,
+              plan.size,
               emit,
               persist,
+              capture,
               options.signal
             );
             if (savedChunk.downloadedBytes !== savedChunk.size) {
@@ -653,6 +1461,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) {
@@ -667,25 +1478,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 } : {}
@@ -695,13 +1510,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 {
@@ -727,10 +1542,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 {
@@ -740,7 +1556,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) {
@@ -752,11 +1568,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);
@@ -778,156 +1591,953 @@ var MountraDownloader = class {
         return false;
       }
     }
-    return false;
+    return false;
+  }
+};
+
+// src/errors.ts
+var MountraApiError = class extends Error {
+  status;
+  code;
+  body;
+  constructor(message, input) {
+    super(message);
+    this.name = "MountraApiError";
+    this.status = input.status;
+    this.code = input.code;
+    this.body = input.body;
+  }
+};
+
+// src/metadata.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function invalidField(field) {
+  return new TypeError(`Mountra metadata response field ${field} is invalid`);
+}
+function readString2(value, field) {
+  if (typeof value !== "string") {
+    throw invalidField(field);
+  }
+  return value;
+}
+function readCount(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw invalidField(field);
+  }
+  return value;
+}
+function readBoolean(value, field) {
+  if (typeof value !== "boolean") {
+    throw invalidField(field);
+  }
+  return value;
+}
+function optionalInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : void 0;
+}
+function optionalText(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function withoutUndefined(value) {
+  for (const key of Object.keys(value)) {
+    if (value[key] === void 0) {
+      delete value[key];
+    }
+  }
+  return value;
+}
+function readNodeFields(raw, field) {
+  return {
+    name: readString2(raw.name, `${field}.name`),
+    path: normalizePath(readString2(raw.path, `${field}.path`)),
+    ino: readCount(raw.ino, `${field}.ino`),
+    isDirectory: readBoolean(raw.is_directory, `${field}.is_directory`),
+    size: readCount(raw.size, `${field}.size`),
+    mtimeMs: readCount(raw.mtime_ms, `${field}.mtime_ms`),
+    uid: optionalInteger(raw.uid),
+    gid: optionalInteger(raw.gid),
+    uidSubjectId: optionalText(raw.uid_subject_id),
+    uidSubjectType: optionalText(raw.uid_subject_type),
+    gidSubjectId: optionalText(raw.gid_subject_id),
+    gidSubjectType: optionalText(raw.gid_subject_type)
+  };
+}
+function readEntry(raw, field) {
+  if (!isRecord2(raw)) {
+    throw invalidField(field);
+  }
+  return withoutUndefined({
+    ...readNodeFields(raw, field),
+    atimeMs: readCount(raw.atime_ms, `${field}.atime_ms`),
+    uidDisplayName: optionalText(raw.uid_display_name),
+    uidUsername: optionalText(raw.uid_username),
+    gidDisplayName: optionalText(raw.gid_display_name),
+    gidUsername: optionalText(raw.gid_username)
+  });
+}
+function readTreeNode(raw, field) {
+  if (!isRecord2(raw) || !Array.isArray(raw.children)) {
+    throw invalidField(field);
+  }
+  return withoutUndefined({
+    ...readNodeFields(raw, field),
+    children: raw.children.map((child, index) => readTreeNode(child, `${field}.children[${index}]`))
+  });
+}
+function readListResponse(value) {
+  if (!isRecord2(value) || !Array.isArray(value.entries)) {
+    throw invalidField("entries");
+  }
+  return value.entries.map((entry, index) => readEntry(entry, `entries[${index}]`));
+}
+function readOperationResponse(value) {
+  if (!isRecord2(value)) {
+    throw new TypeError("Mountra file operation response is invalid");
+  }
+  return {
+    path: normalizePath(readString2(value.path, "path")),
+    ino: readCount(value.ino, "ino")
+  };
+}
+function sameJson(left, right) {
+  if (left === right) {
+    return true;
+  }
+  if (!isRecord2(left) || !isRecord2(right) || Array.isArray(left) !== Array.isArray(right)) {
+    return false;
+  }
+  const leftKeys = Object.keys(left);
+  return leftKeys.length === Object.keys(right).length && leftKeys.every((key) => Object.hasOwn(right, key) && sameJson(left[key], right[key]));
+}
+function sameContent(left, right) {
+  return left.kind === "list" && right.kind === "list" ? sameJson(left.entries, right.entries) : left.kind === "tree" && right.kind === "tree" && sameJson(left.root, right.root);
+}
+function workspaceBody(selector) {
+  return {
+    ...selector.workspaceCuid !== void 0 ? { workspace_cuid: selector.workspaceCuid } : {},
+    ...selector.workspaceId !== void 0 ? { workspace_id: selector.workspaceId } : {}
+  };
+}
+var MountraMetadata = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  list(options = {}) {
+    return this.read("list", options, (record, source) => ({
+      path: record.path,
+      entries: record.entries,
+      source,
+      fetchedAt: record.fetchedAt
+    }));
+  }
+  tree(options = {}) {
+    return this.read("tree", options, (record, source) => ({
+      path: record.path,
+      root: record.root,
+      source,
+      fetchedAt: record.fetchedAt
+    }));
+  }
+  async mkdir(options) {
+    const selector = this.resolveWorkspace(options);
+    const created = await this.operate(selector, "/file/mkdir", { path: normalizePath(options.path) }, options.signal);
+    await this.afterWrite(selector, {
+      type: "create",
+      path: created.path,
+      ino: created.ino,
+      isDirectory: true,
+      size: 0
+    });
+    return created;
+  }
+  async rename(options) {
+    const selector = this.resolveWorkspace(options);
+    const fromPath = normalizePath(options.fromPath);
+    const renamed = await this.operate(
+      selector,
+      "/file/rename",
+      { from_path: fromPath, to_name: options.toName },
+      options.signal
+    );
+    await this.afterWrite(selector, { type: "move", fromPath, toPath: renamed.path, ino: renamed.ino });
+    return renamed;
+  }
+  async move(options) {
+    const selector = this.resolveWorkspace(options);
+    const fromPath = normalizePath(options.fromPath);
+    const moved = await this.operate(
+      selector,
+      "/file/move",
+      { from_path: fromPath, to_path: normalizePath(options.toPath) },
+      options.signal
+    );
+    await this.afterWrite(selector, { type: "move", fromPath, toPath: moved.path, ino: moved.ino });
+    return moved;
+  }
+  async copy(options) {
+    const selector = this.resolveWorkspace(options);
+    const fromPath = normalizePath(options.fromPath);
+    const copied = await this.operate(
+      selector,
+      "/file/copy",
+      { from_path: fromPath, to_path: normalizePath(options.toPath) },
+      options.signal
+    );
+    await this.afterWrite(selector, { type: "copy", fromPath, toPath: copied.path, ino: copied.ino });
+    return copied;
+  }
+  async delete(options) {
+    const selector = this.resolveWorkspace(options);
+    const path = normalizePath(options.path);
+    await this.transport.requestJson("/file/delete", { ...workspaceBody(selector), path }, options.signal);
+    await this.afterWrite(selector, { type: "remove", path });
+  }
+  /** Show a file that an upload just finished. The upload updates the download cache itself. */
+  recordUpload(selector, file) {
+    return this.applyChange(selector, {
+      type: "create",
+      path: normalizePath(file.path),
+      ...file.ino !== void 0 ? { ino: file.ino } : {},
+      isDirectory: false,
+      size: file.size
+    });
+  }
+  async clearCache(selector) {
+    const cache = this.transport.cache;
+    if (!cache) {
+      return;
+    }
+    if (selector === void 0) {
+      await cache.clear();
+      return;
+    }
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    if (workspace === null) {
+      throw new TypeError("workspaceCuid or workspaceId is required");
+    }
+    await cache.clear(workspace);
+  }
+  async read(kind, options, present) {
+    const selector = this.resolveWorkspace(options);
+    const path = normalizePath(options.path ?? "/");
+    const scope = this.cacheScope(selector);
+    const { signal, onUpdate, onError } = options;
+    const cached = options.mode === "async" && scope ? await scope.cache.get(scope.workspace, kind, path) : null;
+    if (!cached) {
+      return present(await this.fetch(kind, selector, path, signal), "remote");
+    }
+    void this.fetch(kind, selector, path, signal).then(
+      (fresh) => {
+        if (!signal?.aborted && !sameContent(cached, fresh)) {
+          onUpdate?.(present(fresh, "remote"));
+        }
+      },
+      (error) => {
+        if (!signal?.aborted) {
+          onError?.(error);
+        }
+      }
+    );
+    return present(cached, "cache");
+  }
+  /** Fetch from Mountra, and cache the result before returning it. */
+  async fetch(kind, selector, path, signal) {
+    const scope = this.cacheScope(selector);
+    const ticket = scope?.cache.beginFetch(scope.workspace);
+    let body;
+    try {
+      body = await this.transport.requestJson(`/file/${kind}`, { ...workspaceBody(selector), path }, signal);
+    } catch (error) {
+      if (scope && ticket && error instanceof MountraApiError && error.status === 404) {
+        await scope.cache.forgetFetched(scope.workspace, path, ticket);
+      }
+      throw error;
+    }
+    const fetchedAt = ticket?.startedAt ?? Date.now();
+    let record;
+    if (kind === "list") {
+      record = { kind, path, entries: readListResponse(body), fetchedAt };
+    } else {
+      if (!isRecord2(body)) {
+        throw invalidField("root");
+      }
+      record = { kind, path, root: readTreeNode(body.root, "root"), fetchedAt };
+    }
+    if (scope && ticket) {
+      await scope.cache.storeFetched(scope.workspace, record, ticket);
+    }
+    return record;
+  }
+  async operate(selector, endpoint, body, signal) {
+    return readOperationResponse(
+      await this.transport.requestJson(endpoint, { ...workspaceBody(selector), ...body }, signal)
+    );
+  }
+  /**
+   * Reflect a write in both caches. Any download cached at a path the write
+   * changed is stale: the file is gone, moved, or a new one now lives there.
+   */
+  async afterWrite(selector, change) {
+    const paths = change.type === "move" ? [change.fromPath, change.toPath] : change.type === "copy" ? [change.toPath] : [change.path];
+    await Promise.all([
+      this.applyChange(selector, change),
+      this.transport.invalidateDownloads(selector, paths)
+    ]);
+  }
+  async applyChange(selector, change) {
+    const scope = this.cacheScope(selector);
+    await scope?.cache.applyChange(scope.workspace, change);
+  }
+  /** Fall back to the client workspace only when the call names none, as downloads do. */
+  resolveWorkspace(selector) {
+    const named = selector.workspaceCuid !== void 0 || selector.workspaceId !== void 0;
+    const { workspaceCuid, workspaceId } = named ? selector : this.transport.clientSelector;
+    if (workspaceCuid === void 0 && workspaceId === void 0) {
+      throw new TypeError("workspaceCuid or workspaceId is required");
+    }
+    return {
+      ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
+      ...workspaceId !== void 0 ? { workspaceId } : {}
+    };
+  }
+  cacheScope(selector) {
+    const cache = this.transport.cache;
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    return cache && workspace !== null ? { cache, workspace } : null;
+  }
+};
+
+// src/metadata-cache.ts
+var DEFAULT_MAX_ENTRIES = 1e3;
+var KINDS = ["list", "tree"];
+function parentOf(path) {
+  const index = path.lastIndexOf("/");
+  return index <= 0 ? "/" : path.slice(0, index);
+}
+function baseName(path) {
+  return path.slice(path.lastIndexOf("/") + 1) || "/";
+}
+function selfAndAncestors(path) {
+  const paths = [path];
+  for (let current = path; current !== "/"; ) {
+    current = parentOf(current);
+    paths.push(current);
+  }
+  return paths;
+}
+function rebasePath(path, from, to) {
+  return `${to}${path.slice(from.length)}`;
+}
+function memoryKey2(workspace, kind, path) {
+  return JSON.stringify([workspace, kind, path]);
+}
+var InMemoryMetadataCacheStore = class {
+  /** Map iteration order is the eviction order: the first entry was written least recently. */
+  records = /* @__PURE__ */ new Map();
+  async get(workspace, kind, path) {
+    const entry = this.records.get(memoryKey2(workspace, kind, path));
+    return entry ? structuredClone(entry.record) : null;
+  }
+  async getSubtree(workspace, path, kind) {
+    return [...this.records.values()].filter(
+      (entry) => entry.workspace === workspace && (kind === void 0 || entry.record.kind === kind) && isPathWithin(entry.record.path, path)
+    ).map((entry) => structuredClone(entry.record));
+  }
+  async write(workspace, batch, maxEntries) {
+    for (const { kind, path } of batch.remove) {
+      this.records.delete(memoryKey2(workspace, kind, path));
+    }
+    for (const record of batch.put) {
+      const key = memoryKey2(workspace, record.kind, record.path);
+      this.records.delete(key);
+      this.records.set(key, { workspace, record: structuredClone(record) });
+    }
+    for (const key of this.records.keys()) {
+      if (this.records.size <= maxEntries) {
+        break;
+      }
+      this.records.delete(key);
+    }
+  }
+  async clear(workspace) {
+    for (const [key, entry] of this.records) {
+      if (workspace === void 0 || entry.workspace === workspace) {
+        this.records.delete(key);
+      }
+    }
+  }
+};
+var METADATA_DATABASE_NAME = "mountra-sdk-metadata-cache";
+var METADATA_DATABASE_VERSION = 1;
+var RECORDS_STORE = "records";
+var META_STORE2 = "meta";
+var WRITE_ORDER_INDEX = "written";
+var IndexedDBMetadataCacheStore = class {
+  databaseName;
+  fallback = new InMemoryMetadataCacheStore();
+  databasePromise;
+  constructor(options = {}) {
+    this.databaseName = options.databaseName ?? METADATA_DATABASE_NAME;
+  }
+  async get(workspace, kind, path) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.get(workspace, kind, path);
+    }
+    return runTransaction(database, [RECORDS_STORE], "readonly", async (transaction) => {
+      const stored = await requestResult(
+        transaction.objectStore(RECORDS_STORE).get([workspace, kind, path])
+      );
+      return stored?.record ?? null;
+    });
   }
-};
-
-// src/file.ts
-function normalizeMountraFileLocator(locator, fallbackWorkspace = {}) {
-  if (!locator || typeof locator !== "object") {
-    throw new TypeError("Mountra file locator is required");
+  async getSubtree(workspace, path, kind) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.getSubtree(workspace, path, kind);
+    }
+    const upper = path === "/" ? "0" : `${path}0`;
+    return runTransaction(database, [RECORDS_STORE], "readonly", async (transaction) => {
+      const records = [];
+      for (const candidate of kind === void 0 ? KINDS : [kind]) {
+        const stored = await requestResult(
+          transaction.objectStore(RECORDS_STORE).getAll(IDBKeyRange.bound([workspace, candidate, path], [workspace, candidate, upper], false, true))
+        );
+        records.push(
+          ...stored.map(({ record }) => record).filter((record) => isPathWithin(record.path, path))
+        );
+      }
+      return records;
+    });
   }
-  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");
+  async write(workspace, batch, maxEntries) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.write(workspace, batch, maxEntries);
+    }
+    await runTransaction(database, [RECORDS_STORE, META_STORE2], "readwrite", async (transaction) => {
+      const records = transaction.objectStore(RECORDS_STORE);
+      const meta = transaction.objectStore(META_STORE2);
+      for (const { kind, path } of batch.remove) {
+        await requestResult(records.delete([workspace, kind, path]));
+      }
+      for (const record of batch.put) {
+        const stored = { record, written: await nextClock(meta) };
+        await requestResult(records.put(stored, [workspace, record.kind, record.path]));
+      }
+      let count = await requestResult(records.count());
+      if (count <= maxEntries) {
+        return;
+      }
+      const cursorRequest = records.index(WRITE_ORDER_INDEX).openCursor();
+      let cursor = await requestResult(cursorRequest);
+      while (cursor && count > maxEntries) {
+        await requestResult(cursor.delete());
+        count -= 1;
+        cursor.continue();
+        cursor = await requestResult(cursorRequest);
+      }
+    });
   }
-  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");
+  async clear(workspace) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.clear(workspace);
+    }
+    await runTransaction(database, [RECORDS_STORE], "readwrite", async (transaction) => {
+      const records = transaction.objectStore(RECORDS_STORE);
+      await requestResult(
+        workspace === void 0 ? records.clear() : records.delete(workspaceRange(workspace))
+      );
+    });
   }
-  const workspaceCuid = locator.workspaceCuid ?? fallbackWorkspace.workspaceCuid;
-  if (workspaceCuid === void 0 && workspaceId === void 0) {
-    throw new TypeError("workspaceCuid, workspaceId, or wsid is required");
+  async openDatabase() {
+    this.databasePromise ??= openDatabase(
+      this.databaseName,
+      METADATA_DATABASE_VERSION,
+      (database) => {
+        if (!database.objectStoreNames.contains(RECORDS_STORE)) {
+          database.createObjectStore(RECORDS_STORE).createIndex(WRITE_ORDER_INDEX, "written");
+        }
+        if (!database.objectStoreNames.contains(META_STORE2)) {
+          database.createObjectStore(META_STORE2);
+        }
+      },
+      () => {
+        this.databasePromise = void 0;
+      }
+    );
+    return this.databasePromise;
   }
-  if (hasPath) {
-    const path = normalizePath(locator.path);
-    return {
-      ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
-      ...workspaceId !== void 0 ? { workspaceId } : {},
-      path
-    };
+};
+var NODE_FIELDS = [
+  "name",
+  "path",
+  "ino",
+  "isDirectory",
+  "size",
+  "mtimeMs",
+  "uid",
+  "gid",
+  "uidSubjectId",
+  "uidSubjectType",
+  "gidSubjectId",
+  "gidSubjectType"
+];
+function pickDefined(source, keys) {
+  const picked = {};
+  for (const key of keys) {
+    if (source[key] !== void 0) {
+      picked[key] = source[key];
+    }
+  }
+  return picked;
+}
+function nodeFromEntry(entry, children) {
+  return { ...pickDefined(entry, NODE_FIELDS), children };
+}
+function entryFromNode(node, previous) {
+  return {
+    ...pickDefined(node, NODE_FIELDS),
+    atimeMs: previous.atimeMs,
+    ...node.uid === previous.uid ? pickDefined(previous, ["uidDisplayName", "uidUsername"]) : {},
+    ...node.gid === previous.gid ? pickDefined(previous, ["gidDisplayName", "gidUsername"]) : {}
+  };
+}
+function findNode(root, path) {
+  let node = root;
+  while (node && node.path !== path) {
+    node = isPathWithin(path, node.path) ? node.children.find((child) => isPathWithin(path, child.path)) : void 0;
   }
+  return node;
+}
+function rebaseNode(node, from, to) {
   return {
-    ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
-    ...workspaceId !== void 0 ? { workspaceId } : {},
-    ino: normalizeIno(locator.ino)
+    ...node,
+    ...node.path === from ? { name: baseName(to) } : {},
+    path: rebasePath(node.path, from, to),
+    children: node.children.map((child) => rebaseNode(child, from, to))
   };
 }
-var MountraFile = class {
-  constructor(client, locator) {
-    this.client = client;
-    this.locator = Object.freeze({ ...locator });
+function compareChildren(left, right) {
+  return Number(right.isDirectory) - Number(left.isDirectory) || left.name.localeCompare(right.name);
+}
+function withChild(children, child) {
+  const result = [...children];
+  const existing = result.findIndex((candidate) => candidate.path === child.path);
+  if (existing >= 0) {
+    result[existing] = child;
+    return result;
+  }
+  const position = result.findIndex((candidate) => compareChildren(child, candidate) < 0);
+  result.splice(position < 0 ? result.length : position, 0, child);
+  return result;
+}
+function recordKey(kind, path) {
+  return `${kind}:${path}`;
+}
+var MetadataDraft = class {
+  records = /* @__PURE__ */ new Map();
+  changed = /* @__PURE__ */ new Set();
+  removed = /* @__PURE__ */ new Map();
+  constructor(records) {
+    for (const record of records) {
+      this.records.set(recordKey(record.kind, record.path), record);
+    }
   }
-  client;
-  locator;
-  get workspaceCuid() {
-    return this.locator.workspaceCuid;
+  list(path) {
+    const record = this.records.get(recordKey("list", path));
+    return record?.kind === "list" ? record : void 0;
   }
-  get workspaceId() {
-    return this.locator.workspaceId;
+  tree(path) {
+    const record = this.records.get(recordKey("tree", path));
+    return record?.kind === "tree" ? record : void 0;
   }
-  /** `wsid` is the short alias used by the file-object API. */
-  get wsid() {
-    return this.locator.workspaceId;
+  /** Loaded trees that hold `path`: those rooted at `path` or at one of its ancestors. */
+  treesContaining(path) {
+    return [...this.records.values()].filter(
+      (record) => record.kind === "tree" && isPathWithin(path, record.path)
+    );
   }
-  get path() {
-    return "path" in this.locator ? this.locator.path : void 0;
+  /** Loaded records at `path` or below it. */
+  within(path) {
+    return [...this.records.values()].filter((record) => isPathWithin(record.path, path));
   }
-  get ino() {
-    return "ino" in this.locator ? this.locator.ino : void 0;
+  put(record) {
+    const key = recordKey(record.kind, record.path);
+    this.records.set(key, record);
+    this.removed.delete(key);
+    this.changed.add(key);
   }
-  export(options = {}) {
-    return this.client.exportFile({ ...options, ...this.locator });
+  /** Mark a loaded record that was changed in place. */
+  touch(record) {
+    this.changed.add(recordKey(record.kind, record.path));
   }
-  download(options = {}) {
-    return this.client.downloadFile({ ...options, ...this.locator });
+  remove(record) {
+    const key = recordKey(record.kind, record.path);
+    this.records.delete(key);
+    this.changed.delete(key);
+    this.removed.set(key, { kind: record.kind, path: record.path });
   }
-  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");
+  batch() {
+    return {
+      put: [...this.changed].map((key) => this.records.get(key)),
+      remove: [...this.removed.values()]
+    };
+  }
+  findEntry(path) {
+    return this.list(parentOf(path))?.entries.find((entry) => entry.path === path);
+  }
+  /** The node of `path` with its complete subtree, from any loaded tree. */
+  findNode(path) {
+    for (const tree of this.treesContaining(path)) {
+      const node = findNode(tree.root, path);
+      if (node) {
+        return node;
       }
-      throw new Error("No resumable download was found for this Mountra file");
     }
-    return this.client.resumeDownload(checkpoint.key, resumeOptions);
+    return void 0;
   }
-};
-function matchesLocator(request, locator) {
-  if (locator.workspaceCuid !== void 0 && request.workspaceCuid !== locator.workspaceCuid) {
-    return false;
+  /** Remove `path` from the listing and the trees that show it. */
+  removeEntry(path) {
+    const parentPath = parentOf(path);
+    const list = this.list(parentPath);
+    if (list?.entries.some((entry) => entry.path === path)) {
+      list.entries = list.entries.filter((entry) => entry.path !== path);
+      this.touch(list);
+    }
+    for (const tree of this.treesContaining(parentPath)) {
+      const parent = findNode(tree.root, parentPath);
+      if (parent?.children.some((child) => child.path === path)) {
+        parent.children = parent.children.filter((child) => child.path !== path);
+        this.touch(tree);
+      }
+    }
   }
-  if (locator.workspaceId !== void 0 && String(request.workspaceId) !== String(locator.workspaceId)) {
-    return false;
+  /**
+   * Show `path` in its parent's listing and in the trees holding its parent.
+   * A record that cannot show it faithfully, because the entry or the
+   * complete node is unknown, is dropped instead.
+   */
+  insertEntry(path, entry, node) {
+    const parentPath = parentOf(path);
+    const list = this.list(parentPath);
+    if (list && entry) {
+      list.entries = withChild(list.entries, entry);
+      this.touch(list);
+    } else if (list) {
+      this.remove(list);
+    }
+    for (const tree of this.treesContaining(parentPath)) {
+      const parent = findNode(tree.root, parentPath);
+      if (node && parent?.isDirectory) {
+        parent.children = withChild(parent.children, structuredClone(node));
+        this.touch(tree);
+      } else {
+        this.remove(tree);
+      }
+    }
   }
-  if ("path" in locator) {
-    if (request.path === void 0 || request.ino !== void 0) {
-      return false;
+  removeSubtree(path) {
+    for (const record of this.within(path)) {
+      this.remove(record);
     }
-    try {
-      return normalizePath(request.path) === locator.path;
-    } catch {
-      return false;
+  }
+  /** Re-key the records at or below `from` to `to`, rewriting the paths they hold. */
+  moveSubtree(from, to) {
+    for (const record of this.within(from)) {
+      this.remove(record);
+      const path = rebasePath(record.path, from, to);
+      this.put(
+        record.kind === "list" ? {
+          ...record,
+          path,
+          entries: record.entries.map((entry) => ({ ...entry, path: rebasePath(entry.path, from, to) }))
+        } : { ...record, path, root: rebaseNode(record.root, from, to) }
+      );
     }
   }
-  return String(request.ino) === String(locator.ino) && request.path === void 0;
+};
+function changeScope(change) {
+  const paths = change.type === "move" || change.type === "copy" ? [change.fromPath, change.toPath] : [change.path];
+  return {
+    lists: paths.map(parentOf),
+    trees: paths.flatMap((path) => selfAndAncestors(parentOf(path))),
+    // A copy keeps its source; any other change makes records below its paths stale or moves them.
+    subtrees: change.type === "copy" ? [change.toPath] : paths
+  };
 }
-function normalizePath(value) {
-  if (!value || !value.trim()) {
-    throw new TypeError("Mountra file path cannot be empty");
+function patchChange(draft, change, now) {
+  switch (change.type) {
+    case "create": {
+      const previousEntry = draft.findEntry(change.path);
+      const previousNode = draft.findNode(change.path);
+      draft.removeSubtree(change.path);
+      if (change.ino === void 0) {
+        draft.insertEntry(change.path, null, null);
+        return;
+      }
+      const fields = {
+        name: baseName(change.path),
+        path: change.path,
+        ino: change.ino,
+        isDirectory: change.isDirectory,
+        size: change.size,
+        mtimeMs: now
+      };
+      const sameKind = (previous) => previous?.isDirectory === change.isDirectory;
+      draft.insertEntry(
+        change.path,
+        { atimeMs: now, ...sameKind(previousEntry) ? previousEntry : {}, ...fields },
+        { ...sameKind(previousNode) ? previousNode : {}, ...fields, children: [] }
+      );
+      return;
+    }
+    case "remove":
+      draft.removeEntry(change.path);
+      draft.removeSubtree(change.path);
+      return;
+    case "move": {
+      const { fromPath, toPath } = change;
+      if (fromPath === toPath) {
+        return;
+      }
+      const entry = draft.findEntry(fromPath);
+      const node = draft.findNode(fromPath);
+      draft.removeEntry(fromPath);
+      draft.removeSubtree(toPath);
+      draft.moveSubtree(fromPath, toPath);
+      const fields = { name: baseName(toPath), path: toPath, ino: change.ino };
+      const movedEntry = entry ? { ...entry, ...fields } : null;
+      draft.insertEntry(
+        toPath,
+        movedEntry,
+        node ? { ...rebaseNode(node, fromPath, toPath), ino: change.ino } : movedEntry && !movedEntry.isDirectory ? nodeFromEntry(movedEntry, []) : null
+      );
+      return;
+    }
+    case "copy": {
+      const source = draft.findEntry(change.fromPath) ?? draft.findNode(change.fromPath);
+      draft.removeSubtree(change.toPath);
+      if (!source || source.isDirectory) {
+        draft.insertEntry(change.toPath, null, null);
+        return;
+      }
+      const fields = {
+        name: baseName(change.toPath),
+        path: change.toPath,
+        ino: change.ino,
+        isDirectory: false,
+        size: source.size,
+        mtimeMs: now
+      };
+      draft.insertEntry(change.toPath, { ...fields, atimeMs: now }, { ...fields, children: [] });
+      return;
+    }
   }
-  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();
+}
+function childrenFromEntries(directory, entries) {
+  const children = [];
+  for (const entry of entries) {
+    const previous = directory.children.find((child) => child.path === entry.path);
+    if (!entry.isDirectory) {
+      children.push(nodeFromEntry(entry, []));
+    } else if (previous?.isDirectory && previous.ino === entry.ino) {
+      children.push(nodeFromEntry(entry, previous.children));
+    } else {
+      return null;
+    }
+  }
+  return children;
+}
+function entriesFromNodes(entries, nodes) {
+  const previous = new Map(entries.map((entry) => [entry.path, entry]));
+  const fresh = new Map(nodes.map((node) => [node.path, node]));
+  for (const node of nodes) {
+    const entry = previous.get(node.path);
+    if (!entry || entry.ino !== node.ino || entry.isDirectory !== node.isDirectory) {
+      return null;
+    }
+  }
+  return entries.filter((entry) => fresh.has(entry.path)).map((entry) => entryFromNode(fresh.get(entry.path), entry));
+}
+function patchFetchedList(draft, record) {
+  if ((draft.list(record.path)?.fetchedAt ?? 0) > record.fetchedAt) {
+    return;
+  }
+  draft.put(record);
+  for (const tree of draft.treesContaining(record.path)) {
+    if (tree.fetchedAt > record.fetchedAt) {
       continue;
     }
-    stack.push(segment);
+    const directory = findNode(tree.root, record.path);
+    const children = directory?.isDirectory ? childrenFromEntries(directory, record.entries) : null;
+    if (directory && children) {
+      directory.children = children;
+      draft.touch(tree);
+    } else {
+      draft.remove(tree);
+    }
   }
-  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");
+function patchFetchedTree(draft, record) {
+  if ((draft.tree(record.path)?.fetchedAt ?? 0) > record.fetchedAt) {
+    return;
+  }
+  draft.put(record);
+  for (const other of draft.within(record.path)) {
+    if (other === record || other.fetchedAt > record.fetchedAt) {
+      continue;
+    }
+    const node = findNode(record.root, other.path);
+    if (other.kind === "tree") {
+      if (node?.isDirectory) {
+        draft.put({ ...other, root: structuredClone(node), fetchedAt: record.fetchedAt });
+      } else {
+        draft.remove(other);
+      }
+      continue;
+    }
+    const entries = node?.isDirectory ? entriesFromNodes(other.entries, node.children) : null;
+    if (entries) {
+      other.entries = entries;
+      draft.touch(other);
+    } else {
+      draft.remove(other);
     }
-    return value;
   }
-  if (!/^\d+$/.test(value)) {
-    throw new TypeError("Mountra file ino must be a non-negative integer string");
+  if (record.path === "/") {
+    return;
+  }
+  const parentPath = parentOf(record.path);
+  for (const tree of draft.treesContaining(parentPath)) {
+    if (tree.fetchedAt > record.fetchedAt) {
+      continue;
+    }
+    const parent = findNode(tree.root, parentPath);
+    if (parent?.isDirectory) {
+      parent.children = withChild(parent.children, structuredClone(record.root));
+      draft.touch(tree);
+    } else {
+      draft.remove(tree);
+    }
   }
-  return value;
 }
+var MetadataCache = class {
+  maxEntries;
+  store;
+  /** Per workspace, how many writes this client has applied. */
+  writeSeqs = /* @__PURE__ */ new Map();
+  /** Per workspace, the tail of the queue that serializes cache updates. */
+  queues = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries <= 0) {
+      throw new RangeError("metadataCache.maxEntries must be a positive safe integer");
+    }
+    this.store = options.store ?? new IndexedDBMetadataCacheStore();
+  }
+  async get(workspace, kind, path) {
+    try {
+      const record = await this.store.get(workspace, kind, path);
+      return record?.kind === kind && record.path === path ? record : null;
+    } catch {
+      return null;
+    }
+  }
+  beginFetch(workspace) {
+    return { startedAt: Date.now(), writeSeq: this.writeSeqs.get(workspace) ?? 0 };
+  }
+  /** Cache a fetched result, and bring the records it overlaps up to date with it. */
+  async storeFetched(workspace, record, ticket) {
+    await this.update(workspace, ticket, async () => {
+      if (record.kind === "list") {
+        const draft2 = await this.load(workspace, { lists: [record.path], trees: selfAndAncestors(record.path) });
+        patchFetchedList(draft2, record);
+        return draft2;
+      }
+      const draft = await this.load(workspace, { trees: selfAndAncestors(record.path), subtrees: [record.path] });
+      patchFetchedTree(draft, record);
+      return draft;
+    }).catch(() => void 0);
+  }
+  /** Mountra reported that `path` does not exist. */
+  async forgetFetched(workspace, path, ticket) {
+    const change = { type: "remove", path };
+    await this.update(workspace, ticket, async () => {
+      const draft = await this.load(workspace, changeScope(change));
+      patchChange(draft, change, Date.now());
+      return draft;
+    }).catch(() => void 0);
+  }
+  /** Reflect a write that Mountra completed. */
+  async applyChange(workspace, change) {
+    this.writeSeqs.set(workspace, (this.writeSeqs.get(workspace) ?? 0) + 1);
+    await this.update(workspace, null, async () => {
+      const draft = await this.load(workspace, changeScope(change));
+      patchChange(draft, change, Date.now());
+      return draft;
+    }).catch(
+      () => (
+        // A write that cannot be reflected must not leave records that contradict it.
+        this.store.clear(workspace).catch(() => void 0)
+      )
+    );
+  }
+  clear(workspace) {
+    return this.store.clear(workspace);
+  }
+  /**
+   * Run updates of one workspace one at a time. An update for a fetch is
+   * dropped when this client completed a write since the fetch started: the
+   * result may predate that write.
+   */
+  update(workspace, ticket, build) {
+    const run = async () => {
+      if (ticket && ticket.writeSeq !== (this.writeSeqs.get(workspace) ?? 0)) {
+        return;
+      }
+      const batch = (await build()).batch();
+      if (batch.put.length > 0 || batch.remove.length > 0) {
+        await this.store.write(workspace, batch, this.maxEntries);
+      }
+    };
+    const result = (this.queues.get(workspace) ?? Promise.resolve()).then(run);
+    const tail = result.catch(() => void 0);
+    this.queues.set(workspace, tail);
+    void tail.then(() => {
+      if (this.queues.get(workspace) === tail) {
+        this.queues.delete(workspace);
+      }
+    });
+    return result;
+  }
+  async load(workspace, scope) {
+    const [records, subtrees] = await Promise.all([
+      Promise.all([
+        ...[...new Set(scope.lists)].map((path) => this.store.get(workspace, "list", path)),
+        ...[...new Set(scope.trees)].map((path) => this.store.get(workspace, "tree", path))
+      ]),
+      Promise.all([...new Set(scope.subtrees)].map((path) => this.store.getSubtree(workspace, path)))
+    ]);
+    return new MetadataDraft([
+      ...records.filter((record) => record !== null),
+      ...subtrees.flat()
+    ]);
+  }
+};
 
 // src/upload.ts
 var JUMBO_CHUNK_THRESHOLD_BYTES = 128 * 1024 * 1024;
 var MIN_S3_MULTIPART_PART_SIZE_BYTES = 5 * 1024 * 1024;
 var DEFAULT_S3_MULTIPART_PART_SIZE_BYTES = 16 * 1024 * 1024;
 var MAX_S3_MULTIPART_PARTS = 1e4;
-var MountraApiError = class extends Error {
-  status;
-  code;
-  body;
-  constructor(message, input) {
-    super(message);
-    this.name = "MountraApiError";
-    this.status = input.status;
-    this.code = input.code;
-    this.body = input.body;
-  }
-};
 var memoryCheckpointRecords = /* @__PURE__ */ new Map();
 function parseJumboCheckpoint(value) {
-  if (!isRecord2(value) || value.version !== 1 || typeof value.storageKey !== "string") {
+  if (!isRecord3(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)) {
@@ -935,7 +2545,7 @@ function parseJumboCheckpoint(value) {
   }
   const parts = [];
   for (const part of value.parts) {
-    if (!isRecord2(part)) {
+    if (!isRecord3(part)) {
       return null;
     }
     if (typeof part.partNumber !== "number" || typeof part.etag !== "string" || typeof part.size !== "number" || typeof part.sha256 !== "string") {
@@ -1114,11 +2724,11 @@ function throwIfAborted2(signal) {
   }
   throw new DOMException("The upload was aborted", "AbortError");
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function parseApiErrorBody(body) {
-  if (!isRecord2(body)) {
+  if (!isRecord3(body)) {
     return {};
   }
   return {
@@ -1127,7 +2737,7 @@ function parseApiErrorBody(body) {
   };
 }
 function ensurePrepareResponse(value) {
-  if (!isRecord2(value) || typeof value.upload_id !== "string") {
+  if (!isRecord3(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra prepare response is invalid");
   }
   if (!Array.isArray(value.upload_targets)) {
@@ -1136,13 +2746,13 @@ function ensurePrepareResponse(value) {
   return value;
 }
 function ensureFinishResponse(value) {
-  if (!isRecord2(value) || typeof value.upload_id !== "string") {
+  if (!isRecord3(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra finish response is invalid");
   }
   return value;
 }
 function ensureUploadStatusResponse(value) {
-  if (!isRecord2(value) || typeof value.upload_id !== "string") {
+  if (!isRecord3(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra upload status response is invalid");
   }
   if (!Array.isArray(value.chunks)) {
@@ -1160,8 +2770,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,
@@ -1194,6 +2803,7 @@ var MountraClient = class {
   jumboChunkCheckpointStore;
   jumboPartSize;
   downloader;
+  metadata;
   constructor(options) {
     this.baseUrl = normalizeBaseUrl(options.baseUrl);
     this.apiPrefix = normalizeApiPrefix(options.apiPrefix ?? "/api");
@@ -1217,8 +2827,16 @@ 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)
     });
+    this.metadata = new MountraMetadata({
+      baseUrl: this.baseUrl,
+      clientSelector: this.clientSelector,
+      cache: options.metadataCache ? new MetadataCache(options.metadataCache) : null,
+      requestJson: (path, body, signal) => this.requestJson(path, body, signal),
+      invalidateDownloads: (selector, paths) => this.downloader.invalidateCachedPaths(selector, paths)
+    });
   }
   async exportFile(options) {
     return this.downloader.exportFile(options);
@@ -1238,6 +2856,40 @@ 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);
+  }
+  /** List the entries of a directory. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+  list(options) {
+    return this.metadata.list(options);
+  }
+  /** Return a directory with its complete subtree. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+  tree(options) {
+    return this.metadata.tree(options);
+  }
+  mkdir(options) {
+    return this.metadata.mkdir(options);
+  }
+  rename(options) {
+    return this.metadata.rename(options);
+  }
+  move(options) {
+    return this.metadata.move(options);
+  }
+  copy(options) {
+    return this.metadata.copy(options);
+  }
+  delete(options) {
+    return this.metadata.delete(options);
+  }
+  /** Clear the metadata cache of one workspace, or of every workspace when none is given. */
+  clearMetadataCache(selector) {
+    return this.metadata.clearCache(selector);
+  }
   /** Create a stable resource object for one file in this or another workspace. */
   file(locator) {
     return new MountraFile(
@@ -1418,6 +3070,27 @@ var MountraClient = class {
     if (finished.finish_status !== "completed") {
       throw new Error(`Mountra upload did not finish successfully: ${finished.finish_status}`);
     }
+    await this.metadata.recordUpload(this.cacheWorkspace(options), finished);
+    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)
@@ -1593,12 +3266,27 @@ 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.metadata.recordUpload(this.cacheWorkspace(selector), finished);
+      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}`;
@@ -1638,9 +3326,13 @@ function createMountraClient(options) {
 export {
   DEFAULT_S3_MULTIPART_PART_SIZE_BYTES,
   DownloadHttpError,
+  InMemoryDownloadCacheStore,
   InMemoryDownloadCheckpointStore,
   InMemoryJumboChunkCheckpointStore,
+  InMemoryMetadataCacheStore,
+  IndexedDBDownloadCacheStore,
   IndexedDBDownloadCheckpointStore,
+  IndexedDBMetadataCacheStore,
   JUMBO_CHUNK_THRESHOLD_BYTES,
   LocalStorageJumboChunkCheckpointStore,
   MAX_S3_MULTIPART_PARTS,