codex-overleaf-link 2.4.0 → 2.5.0

package/extension/src/page/textFileCreator.js

@@ -4,6 +4,8 @@
 })(typeof window !== 'undefined' ? window : globalThis, function () {
   '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,148 @@
     };
     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 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)) 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',
+            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') });
+        }
+      }
+      // 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(' ');
@@ -51,9 +195,8 @@
       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);
@@ -139,15 +282,14 @@
         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 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 +316,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 +338,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' });
@@ -205,9 +347,22 @@
         assertCurrent();
         uploadHelpers.assignFilesToInput(input, data.files, window);
         mutationAttempted = 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 +377,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('/');
@@ -243,15 +407,21 @@
           await ensureFolderExpanded(folderPath);
         }
         await uploadText();
+        if (options.batch) return { ok: false, pendingVerification: true, changedDocument: true };
         return { ok: true, method: 'overleaf.native-text-upload', changedDocument: true,
-          verified: true, verification: 'overleaf-zip' };
+          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
+          ...verificationFailure(error, mutationAttempted, verificationPhase),
+          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();
+        }
       }
     }
     // Binary uploads use the same folder hierarchy as verified text uploads.
@@ -259,12 +429,33 @@
     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 anchor;
+      }
       const expand = async path => {
         assertCurrent();
         const node = findFolder(path);
@@ -358,40 +549,88 @@
     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 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 +645,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 { 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 +727,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 { 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 +776,9 @@
     async function createFile(operation, options = {}) {
       return createTextFileWithDom(operation, options);
     }
-    return { createFile, deleteFile, prepareEditor, ensureWriteMode, prepareUploadParent, findFolderNode: findFolder };
+    return { createFile, deleteFile, prepareEditor, ensureWriteMode, prepareUploadParent, findFolderNode: findFolder,
+      beginCreateBatch, finishCreateBatch,
+      cancelVerifications() { for (const controller of verificationReads) controller.abort(); } };
   }
   return { create };
 });