codex-overleaf-link 2.4.0 → 2.5.0

package/extension/src/content/writtenChangesView.js

@@ -0,0 +1,152 @@
+(function initCodexOverleafWrittenChangesView(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.CodexOverleafModuleRegistry.define('WrittenChangesView', [], factory);
+  }
+})(typeof window !== 'undefined' ? window : globalThis, function writtenChangesViewFactory() {
+  'use strict';
+
+  // Read-only receipt for changes already written to Overleaf: one folded row
+  // per file, and inside it only the changed lines with word-level marks.
+  // Reviewing-mode hunks with Accept/Reject stay in DiffReviewPanel.
+  const CONTEXT_LINES = 1;
+  const MAX_WORD_DIFF_TOKENS = 600;
+  // CJK characters diff one by one; Latin words, spaces and punctuation as runs.
+  const TOKEN = /[\u3000-\u9fff\uac00-\ud7af\uff00-\uffef]|[A-Za-z0-9_]+|\s+|\\[A-Za-z]+|[^\sA-Za-z0-9_\u3000-\u9fff\uac00-\ud7af\uff00-\uffef]/g;
+
+  function tokenize(text) {
+    return String(text || '').match(TOKEN) || [];
+  }
+
+  // Classic LCS over tokens; returns [{ type: 'same'|'del'|'ins', text }].
+  function diffWords(before, after) {
+    const a = tokenize(before), b = tokenize(after);
+    if (a.length > MAX_WORD_DIFF_TOKENS || b.length > MAX_WORD_DIFF_TOKENS) {
+      return [{ type: 'del', text: String(before) }, { type: 'ins', text: String(after) }];
+    }
+    const table = Array.from({ length: a.length + 1 }, () => new Uint16Array(b.length + 1));
+    for (let i = a.length - 1; i >= 0; i -= 1) {
+      for (let j = b.length - 1; j >= 0; j -= 1) {
+        table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+      }
+    }
+    const parts = [];
+    const push = (type, text) => {
+      const last = parts[parts.length - 1];
+      if (last?.type === type) last.text += text; else parts.push({ type, text });
+    };
+    let i = 0, j = 0;
+    while (i < a.length && j < b.length) {
+      if (a[i] === b[j]) { push('same', a[i]); i += 1; j += 1; }
+      else if (table[i + 1][j] >= table[i][j + 1]) { push('del', a[i]); i += 1; }
+      else { push('ins', b[j]); j += 1; }
+    }
+    while (i < a.length) push('del', a[i++]);
+    while (j < b.length) push('ins', b[j++]);
+    return parts;
+  }
+
+  // Turns diff hunk lines into display rows: paired remove/add runs become one
+  // merged row; long unchanged stretches fold into a gap row.
+  function buildRows(lines) {
+    const rows = [];
+    for (let index = 0; index < lines.length;) {
+      const line = lines[index];
+      if (line?.type !== 'remove' && line?.type !== 'add') {
+        rows.push({ kind: 'context', text: String(line?.text ?? '') });
+        index += 1;
+        continue;
+      }
+      const removed = [], added = [];
+      while (lines[index]?.type === 'remove') removed.push(String(lines[index++].text ?? ''));
+      while (lines[index]?.type === 'add') added.push(String(lines[index++].text ?? ''));
+      const paired = Math.min(removed.length, added.length);
+      for (let k = 0; k < paired; k += 1) rows.push({ kind: 'change', parts: diffWords(removed[k], added[k]) });
+      for (const text of removed.slice(paired)) rows.push({ kind: 'change', parts: [{ type: 'del', text }] });
+      for (const text of added.slice(paired)) rows.push({ kind: 'change', parts: [{ type: 'ins', text }] });
+    }
+    const near = rows.map((row, index) => row.kind === 'change'
+      || rows.slice(Math.max(0, index - CONTEXT_LINES), index + CONTEXT_LINES + 1).some(other => other.kind === 'change'));
+    const out = [];
+    for (let index = 0; index < rows.length;) {
+      if (near[index]) { out.push(rows[index]); index += 1; continue; }
+      let end = index;
+      while (end < rows.length && !near[end]) end += 1;
+      out.push({ kind: 'gap', count: end - index });
+      index = end;
+    }
+    return out;
+  }
+
+  function countLines(diff) {
+    let added = 0, removed = 0;
+    for (const hunk of diff || []) {
+      for (const line of hunk?.lines || []) {
+        if (line?.type === 'add') added += 1;
+        else if (line?.type === 'remove') removed += 1;
+      }
+    }
+    return { added, removed };
+  }
+
+  function render(changes, { document: doc = globalThis.document, tx = en => en } = {}) {
+    const make = (tag, className, text) => {
+      const el = doc.createElement(tag);
+      if (className) el.className = className;
+      if (text !== undefined) el.textContent = text;
+      return el;
+    };
+    const list = make('div', 'run-written-changes');
+    list.setAttribute('role', 'list');
+    for (const change of changes || []) {
+      if (!change?.path || !Array.isArray(change.diff) || !change.diff.length) continue;
+      const file = make('details', 'run-written-file');
+      file.setAttribute('role', 'listitem');
+      const summary = make('summary', 'run-written-file-sum');
+      const name = make('span', 'run-written-file-name', change.path.split('/').pop());
+      name.title = change.path;
+      const { added, removed } = countLines(change.diff);
+      summary.append(name);
+      if (change.path.includes('/')) summary.append(make('span', 'run-written-file-dir', change.path.slice(0, change.path.lastIndexOf('/'))));
+      const counts = make('span', 'run-written-file-counts');
+      counts.append(make('span', 'run-written-add', '+' + added), make('span', 'run-written-del', '−' + removed));
+      counts.setAttribute('aria-label', tx(`${added} lines added, ${removed} removed`, `新增 ${added} 行，删除 ${removed} 行`));
+      summary.append(counts);
+      file.append(summary);
+      // Lazy body: thesis chapters produce long diffs, so build on first open.
+      file.addEventListener('toggle', () => {
+        if (!file.open || file.dataset.built) return;
+        file.dataset.built = 'true';
+        const body = make('div', 'run-written-body');
+        for (const hunk of change.diff) {
+          if (hunk?.truncated) {
+            body.append(make('div', 'run-written-row run-written-note', String(hunk.lines?.[0]?.text || '')));
+            continue;
+          }
+          const head = make('div', 'run-written-hunk', tx(`Line ${hunk?.startB ?? '?'}`, `第 ${hunk?.startB ?? '?'} 行`));
+          body.append(head);
+          for (const row of buildRows(hunk?.lines || [])) {
+            if (row.kind === 'gap') {
+              body.append(make('div', 'run-written-row run-written-gap', tx(`… ${row.count} unchanged lines`, `… ${row.count} 行未改动`)));
+            } else if (row.kind === 'context') {
+              body.append(make('div', 'run-written-row', row.text || ' '));
+            } else {
+              const line = make('div', 'run-written-row is-changed');
+              for (const part of row.parts) {
+                line.append(part.type === 'same' ? doc.createTextNode(part.text)
+                  : make(part.type === 'ins' ? 'ins' : 'del', '', part.text));
+              }
+              body.append(line);
+            }
+          }
+        }
+        file.append(body);
+      });
+      list.append(file);
+    }
+    return list;
+  }
+
+  return { render, diffWords, buildRows, countLines };
+});

package/extension/src/page/binaryAssetUploader.js

@@ -13,6 +13,18 @@
     const treeOperations = deps.treeOperations;
     const snapshotRouter = deps.snapshotRouter;
     const transfers = new Map();
+    // Keep bounded receipts after payload release; status reads never re-upload.
+    const receipts = new Map();
+    function pruneReceipts() {
+      for (const [id, transfer] of receipts) {
+        if (transfer.finishedAt && Date.now() - transfer.finishedAt > 600000) receipts.delete(id);
+      }
+      while (receipts.size >= 32) {
+        const entry = Array.from(receipts).find(([, value]) => value.finishedAt);
+        if (!entry) break;
+        receipts.delete(entry[0]);
+      }
+    }
 
     function begin(params = {}) {
       let transferId;
@@ -30,6 +42,13 @@
       if (!/^[a-f0-9]{64}$/i.test(String(params.sha256 || ''))) {
         return failure('binary_asset_hash_invalid', 'Asset SHA-256 is missing or invalid.');
       }
+      pruneReceipts();
+      if (transfers.has(transferId) || receipts.has(transferId)) {
+        return failure('binary_upload_transfer_conflict', 'Asset transfer ID is already in use.');
+      }
+      if (transfers.size >= 32 || receipts.size >= 32) {
+        return failure('binary_upload_busy', 'Too many asset transfers are pending.');
+      }
       transfers.set(transferId, {
         id: transferId,
         path: projectPath,
@@ -62,7 +81,50 @@
       return { ok: true, transferId: transfer.id, received: transfer.received };
     }
 
-    async function commit(params = {}) {
+    function commit(params = {}) {
+      const id = String(params.transferId || '');
+      const existing = receipts.get(id);
+      if (existing) {
+        if (existing.projectId !== treeOperations.getProjectId()) {
+          return Promise.resolve(failure('binary_upload_scope_changed', 'Asset project changed.'));
+        }
+        return existing.promise;
+      }
+      const transfer = transfers.get(id);
+      if (!transfer) return Promise.resolve(failure('binary_upload_transfer_missing', 'Asset upload transfer was not found.'));
+      receipts.set(id, transfer);
+      transfer.promise = commitOnce(params).catch(error => ({
+        ...failure(error.code || 'binary_upload_failed', error.message),
+        changedDocument: transfer.mutationAttempted === true
+      })).then(result => {
+        transfer.result = result;
+        transfer.finishedAt = Date.now();
+        transfer.chunks = [];
+        return result;
+      });
+      return transfer.promise;
+    }
+
+    async function status(params = {}) {
+      pruneReceipts();
+      const transfer = receipts.get(String(params.transferId || ''));
+      if (!transfer || !params.runProjectId || transfer.projectId !== params.runProjectId
+        || treeOperations.getProjectId() !== transfer.projectId) {
+        return failure('binary_upload_receipt_missing', 'Asset upload receipt is unavailable for this project.');
+      }
+      if (transfer.result?.ok !== true && transfer.mutationAttempted === true) {
+        const evidence = await waitForPath(transfer, {}, 2500).catch(() => null);
+        if (evidence?.hashVerified === true) {
+          transfer.result = { ok: true, written: true, path: transfer.path,
+            changedDocument: true, method: 'remote-hash-reconciliation' };
+        }
+      }
+      return { ok: true, transferId: transfer.id, runProjectId: transfer.projectId,
+        state: transfer.finishedAt || transfer.result?.ok === true ? 'completed' : 'running',
+        result: transfer.result || null, changedDocument: transfer.mutationAttempted === true };
+    }
+
+    async function commitOnce(params = {}) {
       const transferId = String(params.transferId || '');
       const transfer = transfers.get(transferId);
       if (!transfer) return failure('binary_upload_transfer_missing', 'Asset upload transfer was not found.');
@@ -92,7 +154,7 @@
             const observed = evidence?.observed;
             const hashVerified = evidence?.hashVerified === true;
             assertTransferProject(transfer);
-            const overwriteVerified = !transfer.overwrite || hashVerified || result?.confirmedByTransport === true;
+            const overwriteVerified = hashVerified || result?.confirmedByTransport === true;
             if (result?.ok && observed && overwriteVerified) {
               return { ok: true, written: true, path: transfer.path, method: result.method, changedDocument: true };
             }
@@ -101,6 +163,16 @@
           } catch (error) {
             errors.push(error.message);
           }
+          // Once submission may have happened, changing transports can duplicate
+          // or overwrite a successful upload. Reconcile the same attempt instead.
+          if (transfer.mutationAttempted === true) {
+            const evidence = await waitForPath(transfer, {}, 12000).catch(() => null);
+            if (evidence?.hashVerified === true) {
+              return { ok: true, written: true, path: transfer.path,
+                method: 'remote-hash-reconciliation', changedDocument: true };
+            }
+            break;
+          }
         }
         return { ...failure('binary_upload_unavailable', errors.filter(Boolean).join('; ') || 'No supported Overleaf asset upload path succeeded.'),
           changedDocument: transfer.mutationAttempted === true };
@@ -110,11 +182,13 @@
     }
 
     function abort(params = {}) {
-      return { ok: true, aborted: transfers.delete(String(params.transferId || '')) };
+      const id = String(params.transferId || '');
+      if (receipts.has(id)) return { ok: true, aborted: false, committed: true };
+      return { ok: true, aborted: transfers.delete(id) };
     }
 
     function assertTransferProject(transfer) {
-      if (transfers.get(transfer.id) !== transfer) throw new Error('Asset upload was cancelled or replaced.');
+      if (transfers.get(transfer.id) !== transfer && receipts.get(transfer.id) !== transfer) throw new Error('Asset upload was cancelled or replaced.');
       if (!transfer.projectId || treeOperations.getProjectId() !== transfer.projectId) {
         throw new Error('Project changed during asset upload.');
       }
@@ -134,6 +208,7 @@
       const headers = csrf ? { 'X-CSRF-Token': csrf } : {};
       const query = folderId ? `?folder_id=${encodeURIComponent(folderId)}` : '';
       assertTransferProject(transfer);
+      transfer.mutationAttempted = true;
       const response = await windowRef.fetch(`/project/${encodeURIComponent(projectId)}/upload${query}`, {
         method: 'POST', body: form, credentials: 'same-origin', headers
       });
@@ -156,16 +231,14 @@
 
     async function uploadWithDom(file, transfer) {
       const parentPath = transfer.path.split('/').slice(0, -1).join('/');
-      if (parentPath) {
-        if (typeof deps.prepareUploadParent !== 'function') {
-          return { ok: false, reason: 'Verified folder selection is unavailable for nested asset upload.' };
-        }
-        await deps.prepareUploadParent(parentPath, {
-          createMissing: true,
-          onMutation: () => { transfer.mutationAttempted = true; },
-          isCurrent: () => treeOperations.getProjectId() === transfer.projectId && transfers.get(transfer.id) === transfer
-        });
+      if (typeof deps.prepareUploadParent !== 'function') {
+        return { ok: false, reason: 'Verified folder selection is unavailable for asset upload.' };
       }
+      await deps.prepareUploadParent(parentPath, {
+        createMissing: true,
+        onMutation: () => { transfer.mutationAttempted = true; },
+        isCurrent: () => treeOperations.getProjectId() === transfer.projectId && transfers.get(transfer.id) === transfer
+      });
       assertTransferProject(transfer);
       let input = findFileInput();
       if (!input) {
@@ -192,9 +265,10 @@
       for (const name of ['uploadFile', 'uploadAsset', 'createBinaryFile', 'createFile', 'addFile']) {
         if (typeof manager[name] !== 'function') continue;
         try {
+          transfer.mutationAttempted = true;
           await manager[name](transfer.path, file);
           return { ok: true, method: `fileTreeManager.${name}`, confirmedByTransport: true };
-        } catch (_error) { /* try the next adapter */ }
+        } catch (error) { return { ok: false, reason: error.message }; }
       }
       return { ok: false, reason: 'Legacy file-tree manager has no compatible asset method.' };
     }
@@ -293,9 +367,13 @@
       let lastObserved = null;
       while (Date.now() < deadline) {
         assertTransferProject(transfer);
-        const node = findNativeTreeNode(projectPath, 'file')
-          || treeOperations.findFileTreeNode(projectPath, { invalidateCache: true });
-        let observed = node || treeOperations.projectPathExists(projectPath)
+        // A matching digest identifies bytes, not their project path. In the
+        // native tree, require the exact ancestry; the generic tree adapter
+        // can resolve a root name to an identically named nested file.
+        const nativeRoot = documentRef.querySelector?.('[data-testid="file-tree-list-root"]');
+        const node = nativeRoot ? findNativeTreeNode(projectPath, 'file')
+          : treeOperations.findFileTreeNode(projectPath, { invalidateCache: true });
+        let observed = node || (!nativeRoot && treeOperations.projectPathExists(projectPath))
           ? { path: projectPath, id: readTreeEntityId(node) } : null;
         if (!observed?.id) {
           try {
@@ -313,7 +391,7 @@
           assertTransferProject(transfer);
           // An existing path is not replacement evidence. Re-read identity and
           // bytes while the native uploader and file-tree events settle.
-          if (!transfer.overwrite || hashVerified || result.confirmedByTransport === true) {
+          if (hashVerified || result.confirmedByTransport === true) {
             return { observed, hashVerified };
           }
         }
@@ -333,7 +411,7 @@
       return digest === transfer.sha256;
     }
     function delay(ms) { return new Promise(resolve => windowRef.setTimeout(resolve, ms)); }
-    return { abort, append, begin, commit };
+    return { abort, append, begin, commit, status };
   }
 
   function normalizePath(value) {

package/extension/src/page/overleafProjectSnapshot.js

@@ -120,6 +120,7 @@
         deps.getProjectId?.() || pageWindow.location.pathname || pageWindow.location.href,
         params.preferLightweight ? 'lightweight' : 'full',
         params.zipOnly ? 'zip-only' : 'zip-or-page',
+        params.serverOnly === true ? 'server-only' : 'editor-overlay',
         params.allowZipFallback === false ? 'no-zip-fallback' : 'zip-fallback',
         params.allowEditorNavigation === false ? 'no-editor-navigation' : params.allowEditorNavigation === true ? 'editor-navigation' : 'default-editor-navigation',
         params.requireFullProject ? 'require-full-project' : 'allow-partial-project',

package/extension/src/page/referenceProjects.js

@@ -0,0 +1,148 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.CodexOverleafReferenceProjects = api;
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+  const MAX_CATALOG_BYTES = 8 * 1024 * 1024;
+  const MAX_PROJECT_BYTES = 4 * 1024 * 1024;
+  const validId = value => /^[a-f0-9]{24}$/i.test(value);
+
+  function failure(code, message) { return Object.assign(new Error(message), { code }); }
+
+  function parseCatalog(doc) {
+    const element = doc.querySelector('meta[name="ol-prefetchedProjectsBlob"]')
+      || doc.querySelector('meta[name="ol-projects"]');
+    if (!element) throw failure('reference_catalog_unavailable',
+      'Overleaf did not return its project directory. Check that this account is signed in, then retry.');
+    let data;
+    try { data = JSON.parse(element.getAttribute('content') || ''); }
+    catch (_) { throw failure('reference_catalog_invalid', 'Overleaf returned an unreadable project directory. Retry loading projects.'); }
+    const rows = Array.isArray(data) ? data : data?.projects;
+    if (!Array.isArray(rows)) throw failure('reference_catalog_invalid', 'Overleaf returned an invalid project directory.');
+    const total = Array.isArray(data) ? rows.length : Number(data.totalSize);
+    if (Number.isFinite(total) && total > rows.length) {
+      throw failure('reference_catalog_incomplete', 'Overleaf returned only part of the project directory. Refresh Overleaf and retry loading projects.');
+    }
+    const result = new Map();
+    for (const row of rows) {
+      if (row?.trashed === true) continue;
+      const projectId = String(row?.id || row?._id || '');
+      if (!validId(projectId) || typeof row?.name !== 'string') {
+        throw failure('reference_catalog_invalid', 'A project entry could not be read. Retry loading the directory.');
+      }
+      result.set(projectId, {
+        projectId, name: row.name.slice(0, 300),
+        archived: row.archived === true,
+        shared: row.accessLevel !== 'owner',
+        readOnly: ['readOnly', 'read-only', 'read'].includes(row.accessLevel),
+        lastUpdated: typeof row.lastUpdated === 'string' ? row.lastUpdated : ''
+      });
+    }
+    return [...result.values()].sort((a, b) =>
+      (Date.parse(b.lastUpdated) || 0) - (Date.parse(a.lastUpdated) || 0) || a.name.localeCompare(b.name));
+  }
+
+  function create(deps = {}) {
+    const pageWindow = deps.window || window;
+    const fetchImpl = deps.fetch || pageWindow.fetch.bind(pageWindow);
+    const reads = new Map();
+
+    async function catalogText(response) {
+      if (Number(response.headers.get('content-length')) > MAX_CATALOG_BYTES) {
+        throw failure('reference_catalog_too_large', 'The Overleaf project directory is too large to load.');
+      }
+      if (!response.body?.getReader) {
+        const text = await response.text();
+        if (new TextEncoder().encode(text).byteLength > MAX_CATALOG_BYTES) {
+          throw failure('reference_catalog_too_large', 'The Overleaf project directory is too large to load.');
+        }
+        return text;
+      }
+      const reader = response.body.getReader(), decoder = new TextDecoder();
+      let bytes = 0, text = '';
+      try {
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          bytes += chunk.value.byteLength;
+          if (bytes > MAX_CATALOG_BYTES) {
+            await reader.cancel();
+            throw failure('reference_catalog_too_large', 'The Overleaf project directory is too large to load.');
+          }
+          text += decoder.decode(chunk.value, { stream: true });
+        }
+        return text + decoder.decode();
+      } finally { reader.releaseLock(); }
+    }
+
+    async function listProjects() {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 20000);
+      try {
+        const response = await fetchImpl(new URL('/project', pageWindow.location.origin).href, {
+          credentials: 'include', cache: 'no-store', headers: { accept: 'text/html' },
+          signal: controller.signal
+        });
+        if (!response.ok) throw failure('reference_catalog_http', 'Overleaf could not load projects (HTTP ' + response.status + '). Retry loading projects.');
+        if (response.url && new URL(response.url).origin !== pageWindow.location.origin) {
+          throw failure('reference_catalog_login', 'Sign in to Overleaf on this domain, then retry loading projects.');
+        }
+        const text = await catalogText(response);
+        const parser = new pageWindow.DOMParser();
+        const projects = parseCatalog(parser.parseFromString(text, 'text/html'));
+        return { ok: true, projects, total: projects.length, capturedAt: new Date().toISOString() };
+      } catch (error) {
+        return { ok: false, code: error.code || 'reference_catalog_failed',
+          error: controller.signal.aborted ? 'Loading Overleaf projects timed out. Retry loading projects.' : error.message };
+      } finally { clearTimeout(timer); }
+    }
+
+    async function readProject(params = {}) {
+      const projectId = String(params.projectId || '');
+      const requestId = String(params.requestId || '');
+      if (!validId(projectId) || !requestId || requestId.length > 160) {
+        return { ok: false, code: 'reference_project_invalid', error: 'Reference project identity is invalid.' };
+      }
+      if (reads.has(requestId)) return { ok: false, code: 'reference_read_busy', error: 'This reference read is already running.' };
+      const controller = new AbortController();
+      reads.set(requestId, controller);
+      try {
+        const snapshot = await deps.snapshotRouter.fetchProjectZipSnapshot({
+          includeBinaryFiles: false, includeContent: true, zipTimeoutMs: 30000
+        }, { projectId, signal: controller.signal });
+        if (controller.signal.aborted) throw failure('reference_read_cancelled', 'Reference reading was cancelled.');
+        if (!snapshot?.ok) throw failure('reference_project_unavailable', snapshot?.reason || 'The reference project could not be read.');
+        const files = (snapshot.files || []).filter(file => /\.tex$/i.test(file.path || ''));
+        if (!files.length) throw failure('reference_project_empty', 'This project contains no readable TeX files.');
+        if (files.length > 1000 || files.some(file => typeof file.content !== 'string')) {
+          throw failure('reference_project_incomplete', 'The reference project could not be read completely.');
+        }
+        const skipped = snapshot.skipped || [];
+        if (skipped.some(file => /\.tex$/i.test(typeof file === 'string' ? file : file?.path || ''))) {
+          throw failure('reference_project_incomplete', 'Some TeX files in the reference project could not be read.');
+        }
+        const encoder = new TextEncoder();
+        const size = files.reduce((sum, file) => sum + encoder.encode(file.content).byteLength, 0);
+        if (size > MAX_PROJECT_BYTES) throw failure('reference_project_too_large', 'Reference project text exceeds 4 MiB. Add a representative PDF instead.');
+        return {
+          ok: true, projectId, capturedAt: new Date().toISOString(),
+          files: files.map(file => ({ path: file.path, content: file.content, kind: 'text' })),
+          capabilities: { referenceTextComplete: true, method: 'overleaf-reference-zip' }
+        };
+      } catch (error) {
+        return { ok: false, code: error.code || 'reference_project_failed', error: error.message };
+      } finally { reads.delete(requestId); }
+    }
+
+    function cancelRead(params = {}) {
+      const requestId = String(params.requestId || '');
+      const controller = reads.get(requestId);
+      if (controller) controller.abort();
+      return { ok: true, cancelled: Boolean(controller) };
+    }
+
+    return { listProjects, readProject, cancelRead };
+  }
+  return { create, parseCatalog };
+});

package/extension/src/page/saveState.js

@@ -32,12 +32,13 @@
           };
         }
         if (current.state === 'verified_saved') {
-          return { ok: true, state: 'verified_saved' };
+          return { ok: true, state: 'verified_saved', signal: 'saved' };
         }
         if (current.state === 'unavailable') {
           return {
             ok: false,
             state: 'unavailable',
+            signal: current.signal || 'unavailable',
             reason: current.reason || 'Overleaf save state is unavailable.'
           };
         }
@@ -70,11 +71,16 @@
       return {
         ok: false,
         state: 'unknown_timeout',
+        signal: lastState.signal || 'unavailable',
+        observedState: lastState.state,
         reason: buildSaveStateTimeoutReason(lastState)
       };
     }
 
     function getOverleafSaveState() {
+      if (pageWindow.navigator?.onLine === false) {
+        return { state: 'unknown', signal: 'offline', reason: 'Overleaf is offline; saving cannot be confirmed.' };
+      }
       if (!document || typeof document.querySelectorAll !== 'function') {
         return {
           state: 'unavailable',
@@ -86,7 +92,9 @@
         '[class*="saving-status" i]',
         '[class*="save-status" i]',
         '[data-testid*="save" i]',
-        '[aria-label*="save" i]'
+        '[aria-label*="save" i]',
+        '[title*="saved" i]',
+        '[role="status"]'
       ];
       let sawSaveCandidate = false;
       let sawVerifiedSaved = false;
@@ -125,12 +133,14 @@
       if (sawNegativeState) {
         return {
           state: 'unknown',
+          signal: 'unsaved',
           reason: 'Overleaf save indicator reports changes are not saved.'
         };
       }
       if (sawSavingState) {
         return {
           state: 'saving',
+          signal: 'saving',
           reason: 'Overleaf is still saving or syncing changes.'
         };
       }
@@ -139,6 +149,7 @@
       }
       return {
         state: 'unknown',
+        signal: sawSaveCandidate ? 'unrecognized' : 'missing',
         reason: sawSaveCandidate
           ? 'Overleaf save indicator was present, but did not verify that all changes are saved.'
           : 'Overleaf save indicator was not found.'
@@ -149,6 +160,7 @@
       if (!node) {
         return true;
       }
+      if (node.closest?.('#codex-overleaf-panel')) return true;
       if (node.hidden === true || node.inert === true) {
         return true;
       }
@@ -288,5 +300,48 @@
     };
   }
 
-  root.CodexOverleafSaveState = { create };
+  async function confirmReviewWriteback({ params, result, readSnapshot, getProjectId, delay,
+    now = Date.now, timeoutMs = 45000 }) {
+    if (result?.ok !== true || result.skipped?.length) return result;
+    const expected = new Map((params.expectedFiles || [])
+      .filter(file => file?.path && typeof file.content === 'string').map(file => [file.path, file.content]));
+    for (const entry of result.applied || []) {
+      const path = entry.trackedChange?.path || entry.operation?.path;
+      if (expected.has(path) && typeof entry.result?.verifiedContent === 'string') {
+        expected.set(path, entry.result.verifiedContent);
+      }
+    }
+    const deadline = now() + Math.max(0, timeoutMs);
+    let attempts = 0;
+    if (expected.size && typeof readSnapshot === 'function') {
+      do {
+        if (!params.runProjectId || getProjectId() !== params.runProjectId) break;
+        try {
+          const snapshot = await readSnapshot({ force: true, maxAgeMs: 0,
+            zipTimeoutMs: Math.max(1, Math.min(8000, deadline - now())) });
+          attempts++;
+          if (getProjectId() !== params.runProjectId) break;
+          if (snapshot?.ok === true && Array.from(expected).every(([path, content]) =>
+            snapshot.files?.some(file => file.path === path && file.source === 'overleaf-zip'
+              && file.content === content))) {
+            return { ...result, saveVerification: { ok: true, state: 'verified_saved',
+              source: 'overleaf-zip', attempts } };
+          }
+        } catch (_error) { /* A transient download failure grants no save proof. */ }
+        if (now() >= deadline) break;
+        await delay(Math.min(300, deadline - now()));
+      } while (now() < deadline);
+    }
+    const reason = 'Undo changed the editor, but its saved server content could not be confirmed. Keep this page open and check Overleaf before retrying.';
+    return { ...result, ok: false, saveVerification: { ok: false, state: 'unknown_timeout', attempts },
+      skipped: [...(result.skipped || []), { trackedChange: { path: expected.keys().next().value || '' },
+        result: { ok: false, code: 'undo_not_verified', reason, failure: {
+          code: 'undo_not_verified', stage: 'verification', severity: 'needs_review',
+          terminalState: 'needs_review', changedDocument: true, retryable: true, userMessage: reason
+        } } }] };
+  }
+
+  const api = { create, confirmReviewWriteback };
+  root.CodexOverleafSaveState = api;
+  if (typeof module === 'object' && module.exports) module.exports = api;
 })(typeof window !== 'undefined' ? window : globalThis);