codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/page/textFileCreator.js

@@ -1,9 +1,11 @@
 (function (root, factory) {
-  if (typeof module === 'object' && module.exports) module.exports = factory();
-  else root.CodexOverleafTextFileCreator = factory();
-})(typeof window !== 'undefined' ? window : globalThis, function () {
+  if (typeof module === 'object' && module.exports) module.exports = factory(require('./ownedDirectoryCleanup'));
+  else root.CodexOverleafTextFileCreator = factory(root.CodexOverleafOwnedDirectoryCleanup);
+})(typeof window !== 'undefined' ? window : globalThis, function (OwnedDirectoryCleanup) {
   'use strict';
 
+  const MAX_CONFIRMATION_OBSERVATIONS = 8;
+
   function create(deps = {}) {
     const { window, document, treeOperations, uploadHelpers, snapshotRouter } = deps;
     const { getProjectId, findFileTreeNode, projectPathExists, collectProjectTextPaths,
@@ -14,6 +16,162 @@
     };
     const normalizeDomText = value => String(value || '').replace(/\s+/g, ' ').trim();
     const delay = ms => new Promise(resolve => window.setTimeout(resolve, ms));
+    const now = typeof deps.now === 'function' ? deps.now : Date.now;
+    const verificationReads = new Set();
+    const uploadParentProofs = new WeakMap();
+    const verificationBudget = () => ({ remainingMs: 90000 });
+    async function pauseVerification(budget, durationMs) {
+      const started = now();
+      await delay(Math.max(0, Math.min(durationMs, budget.remainingMs)));
+      budget.remainingMs = Math.max(0, budget.remainingMs - Math.max(0, now() - started));
+    }
+    function assertVerificationOwner(projectId, isCurrent) {
+      if (!projectId || getProjectId() !== projectId) {
+        throw Object.assign(new Error('The project changed during writeback.'), { code: 'aborted_project_changed' });
+      }
+      if (isCurrent?.() === false) {
+        throw Object.assign(new Error('Writeback was cancelled.'), { code: 'codex_cancelled' });
+      }
+    }
+    async function boundedSnapshotRead(params, controller, timeoutMs) {
+      const deadline = now() + timeoutMs;
+      const expired = diagnostics => Object.assign(new Error('The server snapshot request timed out.'), {
+        code: 'source_zip_unavailable', diagnostics,
+        technicalMessage: 'The server snapshot request reached its deletion verification deadline.'
+      });
+      let timer, onAbort;
+      try {
+        const interruption = new Promise((_, reject) => {
+          onAbort = () => reject(Object.assign(new Error('Writeback was cancelled.'), { code: 'codex_cancelled' }));
+          controller?.signal.addEventListener('abort', onAbort, { once: true });
+          timer = window.setTimeout(() => { reject(expired(null)); controller?.abort(); }, timeoutMs);
+        });
+        const result = await Promise.race([snapshotRouter.fetchProjectZipSnapshot(params), interruption]);
+        if (now() >= deadline) throw expired(result?.diagnostics);
+        return result;
+      } finally {
+        (window.clearTimeout || globalThis.clearTimeout)(timer);
+        controller?.signal.removeEventListener('abort', onAbort);
+      }
+    }
+    async function readServerSnapshot({ projectId, isCurrent, budget = verificationBudget(), includeBinaryFiles = false,
+      singleAttempt = false, deadlineAt = Infinity }) {
+      const started = now(), deadline = Math.min(started + Math.max(0, budget.remainingMs), deadlineAt);
+      const attemptLimit = singleAttempt ? 1 : 3;
+      let last;
+      try {
+        for (let attempt = 0; attempt < attemptLimit && now() < deadline; attempt++) {
+          assertVerificationOwner(projectId, isCurrent);
+          const Controller = window.AbortController || globalThis.AbortController;
+          const controller = typeof Controller === 'function' ? new Controller() : null;
+          if (controller) verificationReads.add(controller);
+          let result;
+          try {
+            const params = { force: true, maxAgeMs: 0,
+              serverOnly: true, writebackVerification: true, includeBinaryFiles, includeContent: true,
+              signal: controller?.signal, saveCheckId: String(now()) + '-' + attempt,
+              zipTimeoutMs: Math.min(30000, Math.max(1, deadline - now())) };
+            result = singleAttempt ? await boundedSnapshotRead(params, controller, params.zipTimeoutMs)
+              : await snapshotRouter.fetchProjectZipSnapshot(params);
+          } catch (error) {
+            if (singleAttempt) assertVerificationOwner(projectId, isCurrent);
+            if (['codex_cancelled', 'aborted_project_changed'].includes(error?.code)) throw error;
+            result = { ok: false, reason: error?.message || String(error), ...(singleAttempt ? {
+              reason: error?.technicalMessage || error?.message || String(error), diagnostics: error?.diagnostics,
+              status: error?.status || error?.statusCode || error?.response?.status, code: error?.code, retryable: error?.retryable
+            } : {}) };
+          } finally { if (controller) verificationReads.delete(controller); }
+          assertVerificationOwner(projectId, isCurrent);
+          if (result?.ok === true && Array.isArray(result.files)) {
+            const skipped = [...(Array.isArray(result.skipped) ? result.skipped : []),
+              ...(Array.isArray(result.capabilities?.skipped) ? result.capabilities.skipped : [])];
+            if (result.pathIdentityComplete === false || result.capabilities?.pathIdentityComplete === false
+              || skipped.some(file => file?.unknownPath || ['zip_path_invalid', 'zip_path_duplicate'].includes(file?.reason))) {
+              throw Object.assign(new Error('The server snapshot contains unresolved file identities; absence cannot be confirmed.'), {
+                code: 'source_zip_unavailable', originalCode: 'zip_path_identity_incomplete', retryable: false,
+                diagnostics: { ...(result.diagnostics || {}), pathIdentityComplete: false }
+              });
+            }
+            return result;
+          }
+          last = Object.assign(new Error('The server project snapshot could not be read.'), {
+            code: 'source_zip_unavailable', diagnostics: result?.diagnostics || null,
+            technicalMessage: result?.reason || 'No complete server snapshot was returned.',
+            ...(singleAttempt ? { status: result?.status || result?.statusCode, originalCode: result?.code, retryable: result?.retryable } : {})
+          });
+          const attempts = result?.diagnostics?.attempts || [];
+          if (attempts.length && attempts.every(item => [401, 403].includes(item.status))) break;
+          if (attempt < attemptLimit - 1 && now() < deadline) await delay(Math.min(1000 * (2 ** attempt), deadline - now()));
+        }
+        throw last || Object.assign(new Error('The project verification budget was exhausted.'), { code: 'source_zip_unavailable' });
+      } finally { budget.remainingMs = Math.max(0, budget.remainingMs - Math.max(0, now() - started)); }
+    }
+    function verificationFailure(error, changedDocument, phase) {
+      const interrupted = ['codex_cancelled', 'aborted_project_changed'].includes(error?.code);
+      const code = interrupted ? error.code : changedDocument ? 'file_upload_unconfirmed' : 'source_zip_unavailable';
+      const reason = interrupted ? error.message : changedDocument
+        ? 'The file was submitted, but its saved content could not be confirmed.'
+        : 'The project could not be checked before uploading this file.';
+      return { ok: false, code, reason, changedDocument, diagnostics: {
+        verificationPhase: phase, ...(error?.diagnostics || {}), reason: error?.technicalMessage || error?.message || ''
+      }, failure: { code, stage: changedDocument ? 'verify' : 'preflight', severity: changedDocument ? 'warning' : 'blocked',
+        retryable: !interrupted, terminalState: interrupted ? 'cancelled' : changedDocument ? 'needs_review' : 'blocked',
+        changedDocument, userMessage: reason, nextAction: interrupted ? '' : 'Retry sync to check the file and upload only if it is missing.',
+        technicalMessage: error?.technicalMessage || error?.message || '' } };
+    }
+    async function makeSaveReceipt(projectId, path, content) {
+      const cryptoApi = window.crypto || globalThis.crypto;
+      if (!cryptoApi?.subtle || typeof TextEncoder !== 'function') return undefined;
+      const digest = await cryptoApi.subtle.digest('SHA-256', new TextEncoder().encode(content));
+      return { v: 1, source: 'overleaf-zip', projectId, path,
+        sha256: Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join(''),
+        verifiedAt: new Date().toISOString() };
+    }
+    async function beginCreateBatch(operations, options = {}) {
+      const projectId = getProjectId(), budget = verificationBudget();
+      const batch = { projectId, budget, targets: new Set(operations.map(op => op.path)),
+        before: new Map(), pending: new Map(), blocked: new Set(), isCurrent: options.isCurrent, error: null };
+      try {
+        const snapshot = await readServerSnapshot({ projectId, budget, isCurrent: options.isCurrent });
+        batch.before = new Map(snapshot.files.map(file => [file.path, file]));
+      } catch (error) { batch.error = error; }
+      return batch;
+    }
+    async function finishCreateBatch(batch, entries, appliedEntries = []) {
+      let observed = new Map(), lastError = batch.error;
+      try {
+        for (let attempt = 0; entries.length && attempt < 3 && batch.budget.remainingMs > 0; attempt++) {
+          const snapshot = await readServerSnapshot(batch);
+          observed = new Map(snapshot.files.map(file => [file.path, file]));
+          if (entries.every(entry => observed.get(entry.operation.path)?.content === entry.operation.content)) break;
+          if (attempt < 2) await pauseVerification(batch.budget, 500 * (2 ** attempt));
+        }
+        assertVerificationOwner(batch.projectId, batch.isCurrent);
+      } catch (error) { lastError = error; }
+      const results = [];
+      for (const entry of entries) {
+        const operation = entry.operation;
+        if (!lastError && observed.get(operation.path)?.content === operation.content) {
+          results.push({ operation, result: { ok: true, verified: true, changedDocument: true,
+            method: 'overleaf.native-text-upload', verification: 'overleaf-zip',
+            createdDirectories: entry.result?.createdDirectories || [], fileUploadAttempted: entry.result?.fileUploadAttempted === true,
+            saveReceipt: await makeSaveReceipt(batch.projectId, operation.path, operation.content) } });
+        } else {
+          results.push({ operation, result: { ...verificationFailure(lastError || new Error(
+            observed.has(operation.path) ? 'Server content differs from the submitted file.' : 'The file is not yet present in the server snapshot.'
+          ), true, 'post-upload'), createdDirectories: entry.result?.createdDirectories || [],
+            fileUploadAttempted: entry.result?.fileUploadAttempted === true } });
+        }
+      }
+      // The final fresh snapshot can also prove unrelated edits in this batch.
+      if (!lastError) for (const entry of appliedEntries) {
+        const content = entry.result?.verifiedContent ?? (entry.operation?.type === 'create' ? entry.operation.content : undefined);
+        if (typeof content === 'string' && observed.get(entry.operation.path)?.content === content) {
+          entry.result.saveReceipt = await makeSaveReceipt(batch.projectId, entry.operation.path, content);
+        }
+      }
+      return results;
+    }
     const controlName = node => {
       const labelledBy = (node.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean)
         .map(id => document.getElementById?.(id)?.textContent || '').join(' ');
@@ -47,13 +205,16 @@
       return folder;
     };
 
+    const directoryCleanup = OwnedDirectoryCleanup.create({ document, treeOperations, delay, now,
+      readServerSnapshot, assertVerificationOwner, normalizeDomText, normalizeSafeProjectPath });
+    const { folderIdentity, cleanupCreatedDirectories } = directoryCleanup;
+
     async function createFolderWithDom(entryPath, options = {}) {
       const target = normalizeSafeProjectPath(entryPath);
       const projectId = getProjectId();
       const assertCurrent = () => {
-        if (!target || !projectId || getProjectId() !== projectId || options.isCurrent?.() === false) {
-          throw new Error('Project changed or folder creation was cancelled.');
-        }
+        if (!target) throw Object.assign(new Error('A valid folder path is required.'), { code: 'invalid_project_path' });
+        assertVerificationOwner(projectId, options.isCurrent);
       };
       const visible = node => Boolean(node && !node.disabled && node.getClientRects?.().length);
       const dialogs = () => Array.from(document.querySelectorAll('[role="dialog"]')).filter(visible);
@@ -87,7 +248,15 @@
         toggle.click();
         await waitFor(() => findFolder(parentPath)?.getAttribute('aria-expanded') === 'true');
       };
-      let ownedDialog = null;
+      let ownedDialog = null, createdProof = null;
+      const publishProof = () => {
+        if (!createdProof) return;
+        if (getProjectId() === projectId) {
+          const row = findFolder(target);
+          if (row) { createdProof.nativeFolderId = folderIdentity(row); createdProof.observedAfterCreate = true; }
+        }
+        options.onCreatedDirectory?.({ ...createdProof });
+      };
       try {
         assertCurrent();
         if (findFolder(target)) return;
@@ -116,12 +285,18 @@
         await delay(0);
         assertCurrent();
         if (findFolder(target) || projectPathExists(target)) throw new Error('The target path appeared during creation; no replacement was attempted.');
+        const confirm = choose(ownedDialog, /^(?:Create|创建)$/i);
+        createdProof = { v: 1, projectId, path: target, nativeFolderId: '', ownershipConfirmed: false, observedAfterCreate: false };
+        options.onCreatedDirectory?.({ ...createdProof });
         options.onMutation?.();
-        choose(ownedDialog, /^(?:Create|创建)$/i).click();
+        confirm.click();
+        publishProof();
         await waitFor(() => !dialogs().length);
         await expandParent();
         await waitFor(() => findFolder(target));
+        publishProof();
       } finally {
+        publishProof();
         if (ownedDialog && getProjectId() === projectId && dialogs().includes(ownedDialog)) {
           const cancel = Array.from(ownedDialog.querySelectorAll('button')).filter(node => visible(node) && /^(?:Cancel|取消)$/i.test(controlName(node)));
           if (cancel.length === 1) cancel[0].click();
@@ -138,16 +313,20 @@
       if (!target || !projectId || typeof operation.content !== 'string' || !window.CodexOverleafProjectFiles?.isTextProjectPath(target)) {
         return { ok: false, code: 'invalid_project_path', reason: 'A valid text-file path and project are required.' };
       }
-      let mutationAttempted = false;
-      const assertCurrent = () => {
-        if (getProjectId() !== projectId || options.isCurrent?.() === false) {
-          throw new Error('Project changed or the write was cancelled.');
-        }
+      let mutationAttempted = false, fileUploadAttempted = false;
+      const createdDirectories = [];
+      const recordDirectory = proof => {
+        const index = createdDirectories.findIndex(item => item.path === proof.path);
+        if (index < 0) createdDirectories.push(proof); else createdDirectories[index] = proof;
       };
+      let verificationPhase = 'preflight', zipReadCount = 0, lastZipFailure = null;
+      const readBudget = options.batch?.budget || verificationBudget();
+      let uploadDialog = null;
+      const assertCurrent = () => assertVerificationOwner(projectId, options.isCurrent);
       const visible = node => Boolean(node && !node.disabled && node.getClientRects?.().length);
       const dialogs = () => Array.from(document.querySelectorAll('[role="dialog"]')).filter(visible);
-      const waitFor = async read => {
-        const until = Date.now() + 5000;
+      const waitFor = async (read, timeoutMs = 5000) => {
+        const until = Date.now() + timeoutMs;
         do {
           assertCurrent();
           invalidateDomProjectPathCache();
@@ -174,13 +353,12 @@
         await waitFor(() => findFolder(folderPath)?.getAttribute('aria-expanded') === 'true');
       };
       const readServerFiles = async () => {
-        assertCurrent();
-        snapshotRouter.invalidateCache?.();
-        const result = await snapshotRouter.fetchProjectZipSnapshot({ force: true, maxAgeMs: 0,
-          includeBinaryFiles: false, includeContent: true, zipTimeoutMs: 15000 });
-        assertCurrent();
-        if (result?.ok !== true || !Array.isArray(result.files)) throw new Error('Server source ZIP is unavailable; text creation cannot be verified safely.');
-        return result.files;
+        zipReadCount += 1;
+        try {
+          const result = await readServerSnapshot({ projectId, budget: readBudget,
+            isCurrent: () => { assertCurrent(); return true; } });
+          return result.files;
+        } catch (error) { lastZipFailure = { reason: error.message, diagnostics: error.diagnostics }; throw error; }
       };
       const uploadText = async () => {
         const parentPath = target.split('/').slice(0, -1).join('/');
@@ -197,6 +375,7 @@
         const tree = document.querySelector('#ide-rail-tabs-tabpane-file-tree, #ide-redesign-file-tree, .ide-redesign-file-tree, .file-tree');
         chooseButton(tree, /^(?:Upload|上传)$/i).click();
         const dialog = await waitFor(() => dialogs().length === 1 && dialogs()[0]);
+        uploadDialog = dialog;
         const input = await waitFor(() => uploadHelpers.chooseOverleafFileInput(dialog.querySelectorAll('input[type="file"]')));
         if (projectPathExists(target)) throw new Error('The target appeared before upload; no replacement was attempted.');
         const file = new window.File([operation.content], target.split('/').pop(), { type: 'text/plain' });
@@ -204,10 +383,23 @@
         data.items.add(file);
         assertCurrent();
         uploadHelpers.assignFilesToInput(input, data.files, window);
-        mutationAttempted = true;
+        mutationAttempted = true; fileUploadAttempted = true;
+        options.batch?.pending.set(target, operation);
         input.dispatchEvent(new window.Event('change', { bubbles: true }));
         // Never click Replace/Overwrite. A concurrent name conflict must stop.
-        const deadline = Date.now() + 15000;
+        verificationPhase = 'post-upload';
+        const deadline = now() + readBudget.remainingMs;
+        let observations = 0;
+        if (options.batch) {
+          await waitFor(() => {
+            if (dialogs().some(d => /replace|overwrite|替换|覆盖/i.test(d.innerText || ''))) {
+              options.batch.blocked.add(target);
+              throw new Error('Overleaf reported an upload conflict; replacement was not authorized.');
+            }
+            return projectPathExists(target);
+          }, 30000);
+          return;
+        }
         do {
           assertCurrent();
           const conflict = dialogs().some(d => /replace|overwrite|替换|覆盖/i.test(d.innerText || ''));
@@ -222,15 +414,24 @@
             await waitFor(() => !dialogs().length);
             return;
           }
-          await delay(250);
-        } while (Date.now() < deadline);
+          const remaining = deadline - now();
+          if (remaining <= 0) break;
+          await pauseVerification(readBudget, Math.min(250 * (2 ** Math.min(observations++, 3)), remaining));
+        } while (now() < deadline && observations < MAX_CONFIRMATION_OBSERVATIONS);
         throw new Error('The new file content was not confirmed in the server source ZIP. No editor content was modified.');
       };
       try {
         assertCurrent();
+        if (options.batch?.error) throw options.batch.error;
+        const existing = options.batch?.before.get(target);
+        if (existing && options.allowExistingMatches === true && existing.content === operation.content) {
+          return { ok: true, verified: true, changedDocument: false, idempotent: true,
+            method: 'overleaf.existing-text-match', verification: 'overleaf-zip',
+            saveReceipt: await makeSaveReceipt(projectId, target, operation.content) };
+        }
         if (projectPathExists(target)) return { ok: false, code: 'target_file_already_exists', reason: 'The target file already exists.' };
         if (!uploadHelpers?.assignFilesToInput || !snapshotRouter?.fetchProjectZipSnapshot) throw new Error('Verified text upload support is unavailable.');
-        if ((await readServerFiles()).some(file => file.path === target)) {
+        if (options.batch ? options.batch.before.has(target) : (await readServerFiles()).some(file => file.path === target)) {
           return { ok: false, code: 'target_file_already_exists', reason: 'The server already contains the target file.' };
         }
         const parts = target.split('/');
@@ -238,33 +439,93 @@
           const folderPath = parts.slice(0, depth).join('/');
           if (!findFolder(folderPath)) await createFolderWithDom(folderPath, {
             isCurrent: () => { assertCurrent(); return true; },
-            onMutation: () => { mutationAttempted = true; }
+            onMutation: () => { mutationAttempted = true; }, onCreatedDirectory: recordDirectory
           });
           await ensureFolderExpanded(folderPath);
         }
         await uploadText();
-        return { ok: true, method: 'overleaf.native-text-upload', changedDocument: true,
-          verified: true, verification: 'overleaf-zip' };
+        if (options.batch) return { ok: false, pendingVerification: true, changedDocument: true, createdDirectories, fileUploadAttempted };
+        return { ok: true, method: 'overleaf.native-text-upload', changedDocument: true, createdDirectories, fileUploadAttempted,
+          verified: true, verification: 'overleaf-zip',
+          saveReceipt: await makeSaveReceipt(projectId, target, operation.content) };
       } catch (error) {
-        return {
-          ok: false,
-          code: mutationAttempted ? 'file_tree_operation_unverified' : 'file_tree_controls_unavailable',
-          reason: error.message,
-          changedDocument: mutationAttempted
-        };
+        const directoryCleanup = createdDirectories.length
+          ? await cleanupCreatedDirectories(createdDirectories, { projectId, isCurrent: options.isCurrent }) : undefined;
+        const result = verificationFailure(error, mutationAttempted, verificationPhase);
+        if (!fileUploadAttempted && mutationAttempted) {
+          const reason = directoryCleanup?.ok ? 'File upload did not start. The new empty folders were removed.'
+            : 'File upload did not start. Some new folders remain and need review.';
+          result.reason = reason; result.code = 'file_tree_operation_unverified';
+          result.failure = { ...result.failure, code: result.code, stage: 'directory-preparation', userMessage: reason,
+            nextAction: directoryCleanup?.ok ? 'Retry sync to create the file.' : 'Review the remaining folders before retrying.' };
+        }
+        return { ...result, createdDirectories: directoryCleanup?.remaining || createdDirectories,
+          fileUploadAttempted, directoryCleanup, diagnostics: { verificationPhase, zipReadCount, lastZipFailure } };
+      } finally {
+        if (uploadDialog && getProjectId() === projectId && dialogs().includes(uploadDialog)) {
+          const close = Array.from(uploadDialog.querySelectorAll('button')).find(node => visible(node)
+            && /^(?:Close dialog|Close|Done|Cancel|关闭|完成|取消)$/i.test(controlName(node)));
+          close?.click();
+        }
       }
     }
+    const rootUploadIdentity = row => row?.querySelector?.('[data-file-type="doc"][data-file-id], [data-file-type="file"][data-file-id]')
+      ?.getAttribute?.('data-file-id') || '';
+    function rememberUploadParent(path, node, projectId) {
+      if (node && typeof node === 'object') uploadParentProofs.set(node, Object.freeze({
+        path, projectId, nativeId: path ? folderIdentity(node) : rootUploadIdentity(node)
+      }));
+      return node;
+    }
+    // Synchronous last-moment guard after any uploader await. Snapshot the
+    // identity at preparation, since React can reuse a DOM row for a new ID.
+    function isUploadParentCurrent(folderPath, parentNode) {
+      const target = normalizeSafeProjectPath(folderPath);
+      const proof = parentNode && uploadParentProofs.get(parentNode);
+      if ((!target && folderPath !== '') || !proof?.projectId || !proof.nativeId
+        || proof.path !== target || getProjectId() !== proof.projectId) return false;
+      const root = document.querySelector('[data-testid="file-tree-list-root"], .file-tree-list[role="tree"]');
+      if (!root?.children) return false;
+      const selected = Array.from(root.querySelectorAll?.('[role="treeitem"]') || [])
+        .filter(row => row.getAttribute('aria-selected') === 'true');
+      if (selected.length !== 1 || selected[0] !== parentNode) return false;
+      if (!target) return parentNode.closest?.('[role="tree"]') === root
+        && !parentNode.querySelector('[data-file-type="folder"]') && rootUploadIdentity(parentNode) === proof.nativeId;
+      return findFolder(target) === parentNode && folderIdentity(parentNode) === proof.nativeId;
+    }
+
     // Binary uploads use the same folder hierarchy as verified text uploads.
     // A folder is not a text document and must never use basename fallback.
     async function prepareUploadParent(folderPath, options = {}) {
       const target = normalizeSafeProjectPath(folderPath);
       const projectId = getProjectId();
-      if (!target || !projectId) throw new Error('A valid upload parent and project are required.');
-      const assertCurrent = () => {
-        if (getProjectId() !== projectId || options.isCurrent?.() === false) {
-          throw new Error('Project changed or the upload was cancelled.');
+      if (!projectId || (!target && folderPath !== '')) throw new Error('A valid upload parent and project are required.');
+      const assertCurrent = () => assertVerificationOwner(projectId, options.isCurrent);
+      if (!target) {
+        // Uppy inherits the selected entity's parent. A previous nested upload
+        // must not redirect a root asset into that folder. Use a direct root
+        // file row, never the tree adapter's basename fallback.
+        assertCurrent();
+        const readRoot = () => document.querySelector('[data-testid="file-tree-list-root"], .file-tree-list[role="tree"]');
+        const root = readRoot();
+        const anchor = Array.from(root?.querySelectorAll?.('[role="treeitem"]') || []).find(row =>
+          row.closest?.('[role="tree"]') === root
+          && !row.querySelector('[data-file-type="folder"]')
+          && row.querySelector('[data-file-type="doc"][data-file-id], [data-file-type="file"][data-file-id]'));
+        if (!anchor) throw new Error('A root-level file could not be selected safely for asset upload.');
+        if (anchor.getAttribute('aria-selected') !== 'true') {
+          (anchor.querySelector('.file-tree-entity-button, .file-tree-entity-details') || anchor).click();
+          await delay(100);
         }
-      };
+        assertCurrent();
+        const currentRoot = readRoot();
+        const selected = Array.from(currentRoot?.querySelectorAll?.('[role="treeitem"]') || [])
+          .filter(row => row.getAttribute('aria-selected') === 'true');
+        if (selected.length !== 1 || selected[0] !== anchor || anchor.closest('[role="tree"]') !== currentRoot) {
+          throw new Error('Overleaf did not confirm the selected root upload parent.');
+        }
+        return rememberUploadParent('', anchor, projectId);
+      }
       const expand = async path => {
         assertCurrent();
         const node = findFolder(path);
@@ -288,7 +549,8 @@
         const path = parts.slice(0, depth).join('/');
         assertCurrent();
         if (!findFolder(path) && options.createMissing === true) await createFolderWithDom(path, {
-          isCurrent: () => { assertCurrent(); return true; }, onMutation: options.onMutation
+          isCurrent: () => { assertCurrent(); return true; }, onMutation: options.onMutation,
+          onCreatedDirectory: options.onCreatedDirectory
         });
         await expand(path);
       }
@@ -302,7 +564,7 @@
       if (selected.getAttribute('aria-selected') !== 'true') {
         throw new Error('Overleaf did not confirm the selected upload parent.');
       }
-      return selected;
+      return rememberUploadParent(target, selected, projectId);
     }
 
     async function prepareEditor(params = {}) {
@@ -358,40 +620,97 @@
     async function deleteFile(operation, options = {}) {
       const target = normalizeSafeProjectPath(operation.path);
       const projectId = getProjectId();
+      const deadlineAt = Math.min(now() + 90000, Number.isFinite(options.deadlineAt) ? options.deadlineAt : Infinity);
+      const preflightDeadlineAt = deadlineAt - 15000;
       const expected = options.expectedContent;
+      const finishCreatedDeletion = result => {
+        const proofs = operation.undoCreatedFile?.createdDirectories;
+        if (options.undoCreatedFile !== true || !Array.isArray(proofs) || !proofs.length) return result;
+        // The ZIP-confirmed file deletion completes its Undo checkpoint.
+        // Directory observations are retained separately and grant no deletion authority.
+        return { ...result, fileDeleted: true, directoryCleanup: {
+          ok: false, removed: [], remaining: proofs, changedDocument: false
+        } };
+      };
+      const binary = operation.undoCreatedFile?.v === 1 && operation.undoCreatedFile.kind === 'binary'
+        && options.undoCreatedFile === true && /^[a-f0-9]{64}$/i.test(options.expectedSha256 || '');
+      const matchesExpected = async file => {
+        if (!binary) return file && file.content === expected;
+        if (typeof file?.contentBase64 !== 'string') return false;
+        const cryptoApi = window.crypto || globalThis.crypto;
+        if (!cryptoApi?.subtle) return false;
+        const decode = window.atob || globalThis.atob;
+        if (typeof decode !== 'function') return false;
+        const bytes = Uint8Array.from(decode(file.contentBase64.replace(/\s/g, '')), value => value.charCodeAt(0));
+        const hash = await cryptoApi.subtle.digest('SHA-256', bytes);
+        return Array.from(new Uint8Array(hash), byte => byte.toString(16).padStart(2, '0')).join('')
+          === options.expectedSha256.toLowerCase();
+      };
       const canDelete = options.canDelete || (() => typeof deps.readActiveEditorText === 'function'
         && treeOperations.getActiveFilePath?.() === target && deps.readActiveEditorText() === expected);
       let mutationAttempted = false;
       let stage = 'preflight';
       let ownedDialog = null;
+      let zipReadCount = 0;
+      const zipFailures = [];
+      const remainingMs = () => Math.max(0, deadlineAt - now());
+      const budgetExpired = () => Object.assign(new Error('The deletion verification budget was exhausted.'), {
+        code: 'delete_confirmation_budget_exhausted',
+        technicalMessage: mutationAttempted ? 'No time remains to confirm the deletion in the server snapshot.'
+          : 'Deletion was not submitted because at least 15000ms must remain for server confirmation.'
+      });
       const visible = node => Boolean(node && !node.disabled && node.getClientRects?.().length);
       const dialogs = () => Array.from(document.querySelectorAll('[role="dialog"]')).filter(visible);
       const assertCurrent = () => {
-        if (!projectId || getProjectId() !== projectId || options.isCurrent?.() === false) {
-          throw new Error('Project changed or the deletion was cancelled.');
-        }
+        assertVerificationOwner(projectId, options.isCurrent);
+        if (now() >= (mutationAttempted ? deadlineAt : preflightDeadlineAt)) throw budgetExpired();
       };
       const waitFor = async (read, timeoutMs = 5000) => {
-        const deadline = Date.now() + timeoutMs;
-        do {
+        const deadline = Math.min(now() + timeoutMs, preflightDeadlineAt);
+        while (now() < deadline) {
           assertCurrent();
           invalidateDomProjectPathCache();
           const value = await read();
+          assertCurrent();
           if (value) return value;
-          await delay(100);
-        } while (Date.now() < deadline);
+          await delay(Math.max(0, Math.min(100, deadline - now())));
+        }
+        assertCurrent();
         throw new Error(`Overleaf did not confirm ${stage} before timeout.`);
       };
+      const canRetryRead = error => {
+        if (['codex_cancelled', 'aborted_project_changed'].includes(error?.code) || error?.retryable === false) return false;
+        const diagnostics = error?.diagnostics || {};
+        return ![error?.status, diagnostics.status, diagnostics.statusCode,
+          ...(Array.isArray(diagnostics.attempts) ? diagnostics.attempts.map(item => item?.status) : [])]
+          .some(status => [401, 403].includes(Number(status)));
+      };
       const readServerFiles = async () => {
-        assertCurrent();
-        snapshotRouter.invalidateCache?.();
-        const result = await snapshotRouter.fetchProjectZipSnapshot({ force: true, maxAgeMs: 0,
-          includeBinaryFiles: false, includeContent: true, zipTimeoutMs: 15000 });
-        assertCurrent();
-        if (result?.ok !== true || !Array.isArray(result.files)) {
-          throw new Error('Server source ZIP is unavailable; deletion cannot be verified safely.');
+        const deadline = mutationAttempted ? deadlineAt : preflightDeadlineAt;
+        for (let attempt = 0; ; attempt++) {
+          assertCurrent();
+          snapshotRouter.invalidateCache?.();
+          zipReadCount++;
+          try {
+            const result = await readServerSnapshot({ projectId, includeBinaryFiles: binary, singleAttempt: true,
+              deadlineAt: deadline, budget: { remainingMs: Math.max(0, deadline - now()) }, isCurrent: options.isCurrent });
+            assertCurrent();
+            if ((result.skipped || []).some(file => file?.path === target)) {
+              throw Object.assign(new Error('The target was skipped in the server snapshot.'), {
+                code: 'source_zip_unavailable', retryable: false, diagnostics: result.diagnostics || null,
+                technicalMessage: 'The target was skipped in the server snapshot; absence cannot confirm deletion.'
+              });
+            }
+            return result.files;
+          } catch (error) {
+            zipFailures.push({ code: error?.originalCode || error?.code, status: error?.status,
+              technicalMessage: error?.technicalMessage || error?.message, diagnostics: error?.diagnostics || null,
+              remainingMs: remainingMs() });
+            if (zipFailures.length > MAX_CONFIRMATION_OBSERVATIONS) zipFailures.shift();
+            if (!canRetryRead(error) || now() >= deadline) throw error;
+            await delay(Math.min(1000 * (2 ** Math.min(attempt, 2)), deadline - now()));
+          }
         }
-        return result.files;
       };
       const choose = (scope, selector, pattern) => {
         const matches = Array.from(scope.querySelectorAll(selector)).filter(node => visible(node)
@@ -406,26 +725,55 @@
       // Current Overleaf keeps the stable document ID on the draggable
       // entity inside the row. The menu only mounts on hover/selection.
       const rowIdentity = row => row?.querySelector('[data-file-type="doc"][data-file-id]')?.getAttribute('data-file-id')
+        || row?.querySelector('[data-file-type="file"][data-file-id]')?.getAttribute('data-file-id')
         || row?.getAttribute('data-entity-id') || row?.getAttribute('data-doc-id')
         || row?.getAttribute('data-file-id') || row?.querySelector('[id^="menu-button-"]')?.id || '';
       try {
-        if (!target || !projectId || typeof expected !== 'string' || typeof canDelete !== 'function'
-          || !window.CodexOverleafProjectFiles?.isTextProjectPath(target)) {
-          throw new Error('A checked text-file pre-image is required for deletion.');
+        if (!target || !projectId || typeof canDelete !== 'function'
+          || (!binary && (typeof expected !== 'string' || !window.CodexOverleafProjectFiles?.isTextProjectPath(target)))) {
+          throw new Error('A checked file pre-image is required for deletion.');
         }
         assertCurrent();
         if (dialogs().length) throw new Error('An existing Overleaf dialog must be closed before deleting files.');
         if (!snapshotRouter?.fetchProjectZipSnapshot) throw new Error('Verified deletion support is unavailable.');
         const original = (await readServerFiles()).find(file => file.path === target);
-        if (!original || original.content !== expected || canDelete() !== true) {
+        if (!original && options.undoCreatedFile === true && !resolveRow()) {
+          return finishCreatedDeletion({ ok: true, method: 'overleaf.native-created-file-delete', changedDocument: false,
+            idempotent: true, verified: true, verification: 'overleaf-zip' });
+        }
+        const originalMatches = await matchesExpected(original);
+        assertCurrent();
+        if (!originalMatches) {
           throw new Error('The file no longer matches the checked pre-image; deletion was stopped.');
         }
         const parentPath = target.split('/').slice(0, -1).join('/');
-        if (parentPath) await prepareUploadParent(parentPath, options);
+        // Folder expansion must share the preflight deadline too. Uploads keep their existing timing.
+        const parents = parentPath ? parentPath.split('/') : [];
+        for (let depth = 1; depth <= parents.length; depth++) {
+          assertCurrent();
+          const path = parents.slice(0, depth).join('/'), parent = findFolder(path);
+          if (!parent) throw new Error('The target parent folder is unavailable.');
+          if (parent.getAttribute('aria-expanded') !== 'false') continue;
+          stage = 'parent folder expansion';
+          const toggle = parent.querySelector('.folder-expand-collapse-button');
+          if (!toggle) throw new Error('The target parent folder cannot be expanded safely.');
+          toggle.click();
+          await waitFor(() => findFolder(path)?.getAttribute('aria-expanded') === 'true');
+        }
+        // Collapsed folders can hide an existing file from the tree adapter.
+        // Server presence proves existence; prepare its editor only after expansion.
+        if (!binary && canDelete() !== true && typeof options.prepareTextPreimage === 'function') {
+          const current = await options.prepareTextPreimage();
+          assertCurrent();
+          if (!current?.ok || current.text !== expected) {
+            throw new Error('The file no longer matches the checked pre-image; deletion was stopped.');
+          }
+        }
+        if (canDelete() !== true) throw new Error('The file no longer matches the checked pre-image; deletion was stopped.');
         const row = resolveRow();
         const identity = rowIdentity(row);
         if (!row || !identity || row.querySelector('[data-file-type="folder"]')) {
-          throw new Error('An exact Overleaf text-file row could not be identified.');
+          throw new Error('An exact Overleaf file row could not be identified.');
         }
         stage = 'file selection';
         (row.querySelector('.file-tree-entity-details, .file-tree-entity-button') || row).click();
@@ -459,21 +807,42 @@
         };
         if (!verifyDialog()) throw new Error('The deletion dialog does not name exactly the authorized file.');
         const latest = (await readServerFiles()).find(file => file.path === target);
+        const latestMatches = await matchesExpected(latest);
         assertCurrent();
-        if (!latest || latest.content !== expected || canDelete() !== true
+        if (!latestMatches || canDelete() !== true
           || rowIdentity(resolveRow()) !== identity || !verifyDialog()) {
           throw new Error('The target changed before confirmation; deletion was stopped.');
         }
         const confirm = choose(ownedDialog, 'button', /^(?:Delete|删除)$/i);
+        assertCurrent();
         stage = 'server deletion receipt';
         mutationAttempted = true;
         confirm.click();
-        await waitFor(async () => !(await readServerFiles()).some(file => file.path === target), 15000);
-        return { ok: true, method: 'overleaf.native-text-delete', changedDocument: true,
-          verified: true, verification: 'overleaf-zip' };
+        for (let observation = 0; ; observation++) {
+          const files = await readServerFiles();
+          if (!files.some(file => file.path === target)) {
+            return finishCreatedDeletion({ ok: true, method: binary ? 'overleaf.native-created-file-delete' : 'overleaf.native-text-delete', changedDocument: true,
+              verified: true, verification: 'overleaf-zip' });
+          }
+          await delay(Math.min(250 * (2 ** Math.min(observation, 3)), remainingMs()));
+        }
       } catch (error) {
-        return { ok: false, code: mutationAttempted ? 'file_tree_operation_unverified' : 'file_tree_controls_unavailable',
-          reason: error.message, stage: stage.replace(/ /g, '_'), changedDocument: mutationAttempted };
+        const interrupted = ['codex_cancelled', 'aborted_project_changed'].includes(error?.code);
+        const code = interrupted ? error.code : mutationAttempted ? 'file_tree_operation_unverified'
+          : error?.code || 'file_tree_controls_unavailable';
+        const retryable = canRetryRead(error), technicalMessage = error?.technicalMessage || error?.message || '';
+        const reason = interrupted ? error.message : mutationAttempted ? 'Deletion could not be confirmed.'
+          : code === 'source_zip_unavailable' ? 'The server copy could not be checked. No file was deleted.'
+            : code === 'delete_confirmation_budget_exhausted' ? 'Not enough time remains to verify deletion. No file was deleted.' : error.message;
+        return { ok: false, code, reason, stage: stage.replace(/ /g, '_'), changedDocument: mutationAttempted,
+          technicalMessage, deadlineAt, remainingMs: remainingMs(), diagnostics: {
+            ...(error?.diagnostics || {}), verificationPhase: 'delete-' + stage.replace(/ /g, '-'), zipReadCount, zipFailures,
+            reason: technicalMessage, originalCode: error?.originalCode || error?.code || '', status: error?.status,
+            deadlineAt, remainingMs: remainingMs(), mutationAttempted
+          }, failure: { code, stage: mutationAttempted ? 'verify' : 'preflight', severity: mutationAttempted ? 'warning' : 'blocked',
+            retryable, terminalState: interrupted ? 'cancelled' : mutationAttempted ? 'needs_review' : 'blocked',
+            changedDocument: mutationAttempted, file: target, operationType: 'delete', userMessage: reason,
+            nextAction: retryable ? 'Retry Undo to check the file.' : '', technicalMessage } };
       } finally {
         // Close only the dialog opened by this operation; never another modal.
         if (ownedDialog && dialogs().includes(ownedDialog) && getProjectId() === projectId) {
@@ -487,7 +856,9 @@
     async function createFile(operation, options = {}) {
       return createTextFileWithDom(operation, options);
     }
-    return { createFile, deleteFile, prepareEditor, ensureWriteMode, prepareUploadParent, findFolderNode: findFolder };
+    return { createFile, deleteFile, prepareEditor, ensureWriteMode, prepareUploadParent, isUploadParentCurrent, cleanupCreatedDirectories, findFolderNode: findFolder,
+      beginCreateBatch, finishCreateBatch,
+      cancelVerifications() { for (const controller of verificationReads) controller.abort(); } };
   }
   return { create };
 });