codex-overleaf-link 2.4.1 → 2.5.1

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;
       }
@@ -299,16 +311,18 @@
         expected.set(path, entry.result.verifiedContent);
       }
     }
-    const deadline = now() + Math.max(0, timeoutMs);
+    const deadline = Math.min(now() + Math.max(0, timeoutMs), params.deadlineAt == null ? Infinity
+      : Number.isFinite(params.deadlineAt) ? params.deadlineAt : now());
     let attempts = 0;
     if (expected.size && typeof readSnapshot === 'function') {
       do {
-        if (!params.runProjectId || getProjectId() !== params.runProjectId) break;
+        if (now() >= deadline || params.reviewGuard?.() || !params.runProjectId || getProjectId() !== params.runProjectId) break;
         try {
-          const snapshot = await readSnapshot({ force: true, maxAgeMs: 0,
+          const read = () => readSnapshot({ force: true, maxAgeMs: 0,
             zipTimeoutMs: Math.max(1, Math.min(8000, deadline - now())) });
+          const snapshot = params.reviewAwait ? await params.reviewAwait(read) : await read();
           attempts++;
-          if (getProjectId() !== params.runProjectId) break;
+          if (now() >= deadline || params.reviewGuard?.() || 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))) {

package/extension/src/page/snapshotRouter.js

@@ -22,6 +22,7 @@
       : () => '';
     let invalidatedAt = 0;
     let preferredZipEndpoint = '';
+    const writebackReads = new Set();
 
     function getProjectId() {
       return treeOperations.getProjectId?.() || null;
@@ -96,9 +97,10 @@
             };
           }),
           capabilities: {
-            fullProjectSnapshot: true,
+            fullProjectSnapshot: zipSnapshot.pathIdentityComplete !== false,
+            pathIdentityComplete: zipSnapshot.pathIdentityComplete,
             method: 'overleaf-zip-file-list',
-            skipped: [],
+            skipped: zipSnapshot.skipped || [],
             diagnostics: {
               zipEndpoint: zipSnapshot.endpoint,
               zipTiming: zipSnapshot.diagnostics,
@@ -212,7 +214,7 @@
   }
 
   async function buildProjectSnapshot(params = {}) {
-    if (params.zipOnly) {
+    if (params.zipOnly || params.serverOnly === true) {
       return buildZipOnlyProjectSnapshot(params);
     }
 
@@ -242,7 +244,7 @@
     if (zipSnapshot.ok && zipSnapshot.files.length) {
       const mergedFiles = mergeSnapshotFiles(
         zipSnapshot.files,
-        filterZipSnapshotOverlayFiles(zipSnapshot.files, lightweightSnapshot?.files || [])
+        filterZipSnapshotOverlayFiles(zipSnapshot.files, lightweightSnapshot?.files || [], zipSnapshot.skipped)
       );
       const files = filterRequestedSnapshotFiles(mergedFiles, params, activePath);
       const requestedPathsComplete = params.restrictToRequestedPathsOnly === true
@@ -254,7 +256,9 @@
         activePath,
         files,
         capabilities: {
-          fullProjectSnapshot: params.restrictToRequestedPathsOnly === true ? false : true,
+          fullProjectSnapshot: params.restrictToRequestedPathsOnly !== true && zipSnapshot.pathIdentityComplete !== false,
+          pathIdentityComplete: zipSnapshot.pathIdentityComplete,
+          contentComplete: !(zipSnapshot.skipped || []).length,
           requestedPathsComplete,
           method: 'overleaf-zip',
           skipped: zipSnapshot.skipped || [],
@@ -315,7 +319,8 @@
       80
     );
     const files = [];
-    const skipped = [];
+    const skipped = [...(zipSnapshot?.skipped || [])];
+    const ambiguousPaths = new Set(skipped.filter(file => file.reason === 'zip_path_duplicate').map(file => file.path));
     if (zipSnapshot && !zipSnapshot.ok) {
       skipped.push({
         path: 'project.zip',
@@ -325,6 +330,7 @@
     let previousSignature = '';
 
     for (const filePath of projectPaths) {
+      if (ambiguousPaths.has(filePath)) continue;
       if (filePath === snapshotActivePath) {
         const ready = await waitForActiveEditorText(filePath, 5000);
         if (!ready.ok) {
@@ -403,7 +409,7 @@
       await waitForActiveEditorText(activePath, 5000);
     }
 
-    if (snapshotActivePath && !files.length && (!lightweightOnly || params.allowZipFallback === false)) {
+    if (snapshotActivePath && !ambiguousPaths.has(snapshotActivePath) && !files.length && (!lightweightOnly || params.allowZipFallback === false)) {
       files.push({
         path: snapshotActivePath,
         content: readActiveEditorText(),
@@ -418,7 +424,8 @@
       activePath: snapshotActivePath,
       files,
       capabilities: {
-        fullProjectSnapshot: params.restrictToRequestedPathsOnly === true ? false : requestedPathsComplete,
+        fullProjectSnapshot: params.restrictToRequestedPathsOnly !== true && requestedPathsComplete && zipSnapshot?.pathIdentityComplete !== false,
+        pathIdentityComplete: zipSnapshot?.pathIdentityComplete,
         requestedPathsComplete,
         method: resolvePageSnapshotMethod(files, lightweightOnly),
         skipped,
@@ -437,15 +444,14 @@
 
   async function buildZipOnlyProjectSnapshot(params = {}) {
     const activePath = getPassiveActiveFilePath();
-    const activeText = activePath ? readActiveEditorText() : '';
+    // Capture read evidence together with the path/text before awaiting ZIP.
+    // A later editor identity cannot prove that an earlier empty read succeeded.
+    const activeOverlay = params.serverOnly === true ? [] : readActiveEditorOverlay(activePath);
 
     const zipSnapshot = await fetchProjectZipSnapshot(params);
     if (zipSnapshot.ok && zipSnapshot.files.length) {
-      const activeOverlay = buildActiveEditorOverlay(activePath, activeText, {
-        allowedPaths: zipSnapshot.files.map(file => file.path)
-      });
       const files = filterRequestedSnapshotFiles(
-        mergeSnapshotFiles(zipSnapshot.files, activeOverlay),
+        mergeSnapshotFiles(zipSnapshot.files, filterZipSnapshotOverlayFiles(zipSnapshot.files, activeOverlay, zipSnapshot.skipped)),
         params,
         activePath
       );
@@ -458,7 +464,9 @@
         activePath,
         files,
         capabilities: {
-          fullProjectSnapshot: params.restrictToRequestedPathsOnly === true ? false : true,
+          fullProjectSnapshot: params.restrictToRequestedPathsOnly !== true && zipSnapshot.pathIdentityComplete !== false,
+          pathIdentityComplete: zipSnapshot.pathIdentityComplete,
+          contentComplete: !(zipSnapshot.skipped || []).length,
           requestedPathsComplete,
           method: 'overleaf-zip',
           skipped: zipSnapshot.skipped || [],
@@ -477,28 +485,35 @@
       id: getProjectId(),
       url: window.location.href,
       activePath,
-      files: buildActiveEditorOverlay(activePath, activeText),
+      files: filterZipSnapshotOverlayFiles([], activeOverlay, zipSnapshot.skipped, true),
       capabilities: {
         fullProjectSnapshot: false,
-        method: activePath && window.CodexOverleafProjectFiles.isUsableProjectFileContent(activeText)
+        pathIdentityComplete: zipSnapshot.pathIdentityComplete,
+        method: params.serverOnly === true ? 'overleaf-zip-unavailable'
+          : activeOverlay.length
           ? 'active-editor-zip-only-fallback'
           : 'zip-only-fallback-empty',
-        skipped: [{
+        contentComplete: false,
+        skipped: [...(zipSnapshot.skipped || []), {
           path: 'project.zip',
-          reason: zipSnapshot.reason
+          reason: zipSnapshot.reason || 'ZIP file identities were incomplete'
         }],
         diagnostics: {
           docRecordCount: 0,
           docRecords: []
         },
-        note: 'Only the current editor was read because the Overleaf source ZIP was unavailable; no file tree navigation was attempted.'
+        note: params.serverOnly === true
+          ? 'The server snapshot was unavailable; editor content was not used as save evidence.'
+          : 'Only the current editor was read because the Overleaf source ZIP was unavailable; no file tree navigation was attempted.'
       }
     };
   }
 
-  function filterZipSnapshotOverlayFiles(zipFiles = [], overlayFiles = []) {
+  function filterZipSnapshotOverlayFiles(zipFiles = [], overlayFiles = [], skipped = [], allowMissing = false) {
     const zipPaths = new Set((zipFiles || []).map(file => file.path).filter(Boolean));
-    return (overlayFiles || []).filter(file => file?.source !== 'active-editor' || zipPaths.has(file.path));
+    const ambiguousPaths = new Set((skipped || []).filter(file => file.reason === 'zip_path_duplicate').map(file => file.path));
+    return (overlayFiles || []).filter(file => !ambiguousPaths.has(file?.path)
+      && (allowMissing || file?.source !== 'active-editor' || zipPaths.has(file.path)));
   }
 
   function getRequestedSnapshotPaths(params = {}, activePath = '') {
@@ -516,19 +531,32 @@
     return (files || []).filter(file => requestedSet.has(file?.path));
   }
 
-  function buildActiveEditorOverlay(activePath, activeText, options = {}) {
-    if (!activePath || !window.CodexOverleafProjectFiles.isUsableProjectFileContent(activeText)) {
-      return [];
-    }
-    if (Array.isArray(options.allowedPaths) && !options.allowedPaths.includes(activePath)) {
+  function readActiveEditorOverlay(activePath) {
+    if (!activePath) return [];
+    try {
+      const content = readActiveEditorText();
+      if (typeof content !== 'string') return [];
+      if (!content.trim()) {
+        // The legacy reader also returns '' when no surface exists. A readable
+        // identity must independently confirm blank text before it can erase ZIP.
+        const identity = deps.getActiveEditorIdentity?.();
+        let observed;
+        if (identity?.type === 'codemirror-view' && typeof identity.doc?.toString === 'function') {
+          observed = identity.doc.toString();
+        } else if (identity?.type === 'textarea') {
+          observed = identity.node?.value;
+        } else if (identity?.type === 'contenteditable') {
+          const node = identity.node;
+          if (typeof node?.innerText === 'string' || typeof node?.textContent === 'string') {
+            observed = node.innerText || node.textContent || '';
+          }
+        }
+        if (typeof observed !== 'string' || observed !== content) return [];
+      } else if (!window.CodexOverleafProjectFiles.isUsableProjectFileContent(content)) return [];
+      return [{ path: activePath, content, source: 'active-editor', kind: 'text' }];
+    } catch (_error) {
       return [];
     }
-    return [{
-      path: activePath,
-      content: activeText,
-      source: 'active-editor',
-      kind: 'text'
-    }];
   }
 
   function mergeSnapshotFiles(primaryFiles = [], overrideFiles = []) {
@@ -537,7 +565,7 @@
       if (!file?.path || file.kind === 'binary' || typeof file.content !== 'string') {
         continue;
       }
-      if (!window.CodexOverleafProjectFiles.isUsableProjectFileContent(file.content)) {
+      if (file.content.trim() && !window.CodexOverleafProjectFiles.isUsableProjectFileContent(file.content)) {
         continue;
       }
       filesByPath.set(file.path, {
@@ -631,8 +659,13 @@
     }
   }
 
-  async function fetchProjectZipSnapshot(params = {}) {
-    const projectId = getProjectId();
+  async function fetchProjectZipSnapshot(params = {}, reference = null) {
+    // Cross-project reads use a separate internal argument. Normal snapshot
+    // RPC parameters cannot change the active project's snapshot identity.
+    const projectId = reference ? String(reference.projectId || '') : getProjectId();
+    if (reference && !/^[a-f0-9]{24}$/i.test(projectId)) {
+      return { ok: false, reason: 'Reference project identity is invalid' };
+    }
     if (!projectId) {
       return {
         ok: false,
@@ -644,7 +677,9 @@
     const endpoints = [
       `${window.location.origin}/project/${encodeURIComponent(projectId)}/download/zip`,
       `${window.location.origin}/download/project/${encodeURIComponent(projectId)}`
-    ];
+    ].map(endpoint => params.serverOnly === true
+      ? endpoint + '?codex_save_check=' + encodeURIComponent(String(params.saveCheckId || Date.now()).slice(0, 80))
+      : endpoint);
     const orderedEndpoints = preferredZipEndpoint && endpoints.includes(preferredZipEndpoint)
       ? [preferredZipEndpoint, ...endpoints.filter(endpoint => endpoint !== preferredZipEndpoint)]
       : endpoints;
@@ -661,7 +696,9 @@
       }
       const attemptStartedAt = Date.now();
       try {
-        const { response, contentType, buffer, timing } = await fetchZipEndpoint(endpoint, remainingMs);
+        const { response, contentType, buffer, timing } = await fetchZipEndpoint(endpoint, remainingMs,
+          reference?.signal || params.signal, !reference && (params.writebackVerification === true || params.serverOnly === true));
+        if (reference?.signal?.aborted) throw new Error('Reference reading was cancelled');
         if (!response.ok) {
           attempts.push({
             endpoint,
@@ -678,7 +715,7 @@
         });
         const extractMs = Date.now() - extractStartedAt;
         const files = extracted.files || [];
-        if (!files.length) {
+        if (!files.length && extracted.pathIdentityComplete !== false) {
           attempts.push({
             endpoint,
             status: response.status,
@@ -702,6 +739,7 @@
         return {
           ok: true,
           endpoint,
+          pathIdentityComplete: extracted.pathIdentityComplete,
           skipped: extracted.skipped || [],
           files: files.map(file => ({
             ...file,
@@ -716,10 +754,12 @@
       } catch (error) {
         attempts.push({
           endpoint,
-          error: error.message,
+            error: error.message,
+            ...(error.timing || {}),
           elapsedMs: Date.now() - attemptStartedAt
         });
         errors.push(`${endpoint} failed: ${error.message}`);
+        if (reference?.signal?.aborted) break;
         if (error?.code === 'zip_timeout') {
           errors.push(`Overleaf ZIP download exhausted its ${timeoutMs}ms total timeout budget`);
           break;
@@ -738,8 +778,15 @@
     };
   }
 
-  function fetchZipEndpoint(endpoint, timeoutMs) {
+  function fetchZipEndpoint(endpoint, timeoutMs, parentSignal, writeback = false) {
     const controller = typeof AbortController === 'function' ? new AbortController() : null;
+    if (writeback && controller) writebackReads.add(controller);
+    const started = Date.now(), observedTiming = {};
+    const abort = () => controller?.abort();
+    if (controller && parentSignal) {
+      if (parentSignal.aborted) controller.abort();
+      else parentSignal.addEventListener('abort', abort, { once: true });
+    }
     const request = (async () => {
       const startedAt = Date.now();
       const response = await fetch(endpoint, {
@@ -750,6 +797,8 @@
         ...(controller ? { signal: controller.signal } : {})
       });
       const headersAt = Date.now();
+      observedTiming.timeToHeadersMs = headersAt - started;
+      observedTiming.status = response.status;
       const contentType = response.headers.get('content-type') || '';
       const buffer = response.ok ? await response.arrayBuffer() : null;
       return {
@@ -765,7 +814,13 @@
 
     return withTimeout(request, timeoutMs, () => {
       controller?.abort();
-    }, `Overleaf ZIP download timed out after ${timeoutMs}ms`);
+    }, `Overleaf ZIP download timed out after ${timeoutMs}ms`).catch(error => {
+      error.timing = { ...observedTiming, downloadMs: Date.now() - started };
+      throw error;
+    }).finally(() => {
+      if (controller) writebackReads.delete(controller);
+      parentSignal?.removeEventListener?.('abort', abort);
+    });
   }
 
   function withTimeout(promise, timeoutMs, onTimeout, message) {
@@ -811,6 +866,9 @@
     const entryCount = view.getUint16(eocdOffset + 10, true);
     const centralDirectoryOffset = view.getUint32(eocdOffset + 16, true);
     const decoder = new TextDecoder('utf-8');
+    const nameDecoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+    const seenPaths = new Set();
+    let pathIdentityComplete = true;
     const files = [];
     const skipped = [];
     let binaryBytes = 0;
@@ -829,7 +887,25 @@
       const commentLength = view.getUint16(offset + 32, true);
       const localHeaderOffset = view.getUint32(offset + 42, true);
       const rawName = bytes.slice(offset + 46, offset + 46 + fileNameLength);
-      const path = normalizeSafeProjectPath(decoder.decode(rawName));
+      let name = '';
+      try { name = nameDecoder.decode(rawName); } catch (_error) { /* unknown identity is incomplete */ }
+      const directory = name.endsWith('/');
+      const path = normalizeSafeProjectPath(directory ? name.slice(0, -1) : name);
+      if (!path || seenPaths.has(path)) {
+        if (path) {
+          const previousIndex = files.findIndex(file => file.path === path);
+          if (previousIndex >= 0) files.splice(previousIndex, 1);
+        }
+        pathIdentityComplete = false;
+        skipped.push({ path: name, reason: path ? 'zip_path_duplicate' : 'zip_path_invalid', unknownPath: !name });
+        offset += 46 + fileNameLength + extraLength + commentLength;
+        continue;
+      }
+      seenPaths.add(path);
+      if (directory) {
+        offset += 46 + fileNameLength + extraLength + commentLength;
+        continue;
+      }
       const isText = window.CodexOverleafProjectFiles.isTextProjectPath(path);
       const shouldInclude = path && !path.endsWith('/') && (isText || options.includeBinaryFiles);
 
@@ -874,7 +950,7 @@
       offset += 46 + fileNameLength + extraLength + commentLength;
     }
 
-    return { files, skipped };
+    return { files, skipped, pathIdentityComplete };
   }
 
   function uint8ArrayToBase64(bytes) {
@@ -999,16 +1075,16 @@
       getInvalidatedAt,
       getRequestedSnapshotPaths,
       invalidateCache,
+      cancelWritebackReads() { for (const controller of writebackReads) controller.abort(); },
       readFileTree
     };
   }
 
   function fallbackNormalizeSafeProjectPath(value) {
-    const text = String(value || '').replace(/\\/g, '/').replace(/\/+/g, '/').replace(/^\/+|\/+$/g, '').trim();
-    if (!text || text.split('/').some(part => !part || part === '.' || part === '..')) {
-      return '';
-    }
-    return text;
+    if (typeof value !== 'string' || !value || value.length > 2048 || value.trim() !== value
+      || /[\u0000-\u001f\u007f]/.test(value) || value.startsWith('/')
+      || value.includes('\\') || /^[A-Za-z]:/.test(value)) return '';
+    return value.split('/').some(part => !part || part === '.' || part === '..') ? '' : value;
   }
 
   return { create };

package/extension/src/page/textCoordinates.js

@@ -0,0 +1,102 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.CodexOverleafTextCoordinates = api;
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+
+  function resolveJumpToPositionRange(params, text, filePath) {
+    if (params.line === undefined && params.column === undefined) {
+      return {
+        ok: true,
+        from: params.from,
+        to: params.to
+      };
+    }
+
+    const lines = collectTextLineRanges(String(text || ''));
+    const lineCount = lines.length;
+    const lineNumber = Number(params.line);
+    const lineMetadata = { lineCount };
+    if (params.line !== undefined) {
+      lineMetadata.line = Number.isInteger(lineNumber) ? lineNumber : params.line;
+    }
+    if (!Number.isInteger(lineNumber) || lineNumber < 1) {
+      return jumpPositionOutOfRange('line_out_of_range', filePath, lineMetadata);
+    }
+
+    const line = lines[lineNumber - 1];
+    if (!line) {
+      return jumpPositionOutOfRange('line_out_of_range', filePath, {
+        line: lineNumber,
+        lineCount
+      });
+    }
+
+    const lineLength = line.end - line.start;
+    if (params.selectLine === true) {
+      return {
+        ok: true,
+        from: line.start,
+        to: line.end
+      };
+    }
+
+    if (params.column !== undefined) {
+      const columnNumber = Number(params.column);
+      const maxColumn = lineLength + 1;
+      if (!Number.isInteger(columnNumber) || columnNumber < 1 || columnNumber > maxColumn) {
+        return jumpPositionOutOfRange('column_out_of_range', filePath, {
+          line: lineNumber,
+          column: Number.isInteger(columnNumber) ? columnNumber : params.column,
+          lineLength
+        });
+      }
+      const offset = line.start + columnNumber - 1;
+      return {
+        ok: true,
+        from: offset,
+        to: offset
+      };
+    }
+
+    return {
+      ok: true,
+      from: line.start,
+      to: line.start
+    };
+  }
+
+  function jumpPositionOutOfRange(code, filePath, metadata = {}) {
+    return {
+      ok: false,
+      code,
+      reason: 'Requested jumpToPosition location is out of range',
+      path: filePath,
+      ...metadata
+    };
+  }
+
+  function collectTextLineRanges(text) {
+    const lines = [];
+    let start = 0;
+
+    for (let index = 0; index < text.length; index += 1) {
+      if (text[index] === '\r') {
+        lines.push({ start, end: index });
+        if (text[index + 1] === '\n') {
+          index += 1;
+        }
+        start = index + 1;
+      } else if (text[index] === '\n') {
+        lines.push({ start, end: index });
+        start = index + 1;
+      }
+    }
+
+    lines.push({ start, end: text.length });
+    return lines;
+  }
+
+  return { create: () => ({ resolveJumpToPositionRange }), resolveJumpToPositionRange, collectTextLineRanges };
+});