codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/page/fileMover.js

@@ -0,0 +1,256 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafFileMover = factory();
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+
+  function create(deps = {}) {
+    const { window, document, treeOperations, snapshotRouter, textFileCreator } = deps;
+    const normalizePath = deps.normalizeSafeProjectPath || window.CodexOverleafProjectFiles?.normalizeSafeProjectPath;
+    const delay = deps.delay || (ms => new Promise(resolve => window.setTimeout(resolve, ms)));
+    const error = (code, message) => Object.assign(new Error(message), { code });
+    const parent = path => path.split('/').slice(0, -1).join('/');
+    const basename = path => path.split('/').pop();
+    const join = (folder, name) => [folder, name].filter(Boolean).join('/');
+    function entities() {
+      treeOperations.invalidateDomProjectPathCache?.();
+      const root = document.querySelector('[data-testid="file-tree-list-root"], .file-tree-list[role="tree"]');
+      const unique = new Map();
+      for (const row of root?.querySelectorAll?.('[role="treeitem"]') || []) {
+        const entity = row.querySelector?.(':scope > .entity[data-file-id]')
+          || row.querySelector?.('[data-file-type][data-file-id]');
+        const id = entity?.dataset?.fileId || entity?.getAttribute?.('data-file-id');
+        const type = entity?.dataset?.fileType || entity?.getAttribute?.('data-file-type');
+        const path = normalizePath?.(treeOperations.readProjectPathFromNode?.(row));
+        if (id && path && ['doc', 'file', 'folder'].includes(type)) unique.set(type + ':' + id + ':' + path, { id, path, type });
+      }
+      return [...unique.values()];
+    }
+    function at(path, type) {
+      const found = entities().filter(entry => entry.path === path && (!type || entry.type === type));
+      return found.length === 1 ? found[0] : null;
+    }
+    function folderId(path, projectId) {
+      if (path) return at(path, 'folder')?.id || '';
+      for (const root of [window._ide, window.Overleaf, window.overleaf, window.OL]) {
+        const project = root?.project;
+        if ((project?._id || project?.id) !== projectId) continue;
+        const folder = Array.isArray(project.rootFolder) ? project.rootFolder[0] : project.rootFolder;
+        if (folder?._id || folder?.id) return folder._id || folder.id;
+      }
+      return '';
+    }
+    async function digest(file, kind) {
+      let bytes;
+      if (kind === 'text' && typeof file?.content === 'string') bytes = new TextEncoder().encode(file.content);
+      else if (kind === 'binary' && typeof file?.contentBase64 === 'string') {
+        bytes = Uint8Array.from((window.atob || globalThis.atob)(file.contentBase64), char => char.charCodeAt(0));
+      } else throw error('file_move_source_unavailable', 'The source contents could not be verified.');
+      const hash = await (window.crypto || globalThis.crypto).subtle.digest('SHA-256', bytes);
+      return [...new Uint8Array(hash)].map(byte => byte.toString(16).padStart(2, '0')).join('');
+    }
+    function csrfToken() {
+      const meta = document.querySelector('meta[name="ol-csrfToken"], meta[name="csrf-token"], meta[name="_csrf"]');
+      let value = meta ? meta.content : window.csrfToken || window._csrf;
+      if (['json', 'number'].includes(meta?.dataset?.type)) {
+        try { value = JSON.parse(value); } catch (_error) { return ''; }
+      }
+      if (meta?.dataset?.type === 'boolean') return '';
+      return typeof value === 'string' && value.length > 0 && value.length <= 4096 && !/[\0\r\n]/.test(value) ? value : '';
+    }
+
+    // Compatibility consumer for identity-bound moves recorded by older builds.
+    // New mirror diffs never produce metadata moves.
+    async function moveFile(operation, options = {}) {
+      const source = normalizePath?.(operation?.path), target = normalizePath?.(operation?.to);
+      const proof = operation?.moveProof;
+      const projectId = options.runProjectId;
+      const entity = value => typeof value === 'string' && value.length > 0 && value.length <= 160 && !/[\0\r\n]/.test(value);
+      if (options.noTraceUndo !== true || !entity(proof?.sourceEntityId) || !entity(proof?.targetEntityId)
+        || proof.sourceEntityId !== proof.targetEntityId) return { ok: false, code: 'file_tree_controls_unavailable', changedDocument: false,
+        reason: 'A recorded same-entity move is required before its location can be restored.' };
+      const deadline = Math.min(Date.now() + 90000, Number.isFinite(options.deadlineAt) ? options.deadlineAt : Infinity);
+      const createdDirectories = [], completed = [];
+      let entityId = '', entityType = '', attempted = false, currentPath = source;
+      const assertCurrent = () => {
+        if (!projectId || treeOperations.getProjectId() !== projectId) throw error('aborted_project_changed', 'The project changed during the file move.');
+        if (options.isCurrent?.() === false) throw error('codex_cancelled', 'The file move was cancelled.');
+        if (Date.now() >= deadline) throw error('file_move_deadline_exceeded', 'The file move verification deadline was reached.');
+      };
+      const inspectRemainingDirectories = async () => {
+        if (!Array.isArray(proof.createdDirectories) || !proof.createdDirectories.length) return {};
+        try {
+          const directoryCleanup = await textFileCreator?.cleanupCreatedDirectories?.(proof.createdDirectories, {
+            projectId, isCurrent: () => { assertCurrent(); return true; }
+          });
+          if (directoryCleanup) return { directoryCleanup };
+        } catch (_error) { /* The verified file move remains complete; only its directory inspection is unresolved. */ }
+        return { directoryCleanup: { ok: false, removed: [], remaining: proof.createdDirectories, requiresExplicitCleanup: true } };
+      };
+      const observedPath = () => {
+        if (treeOperations.getProjectId() !== projectId) return '';
+        const found = entities().filter(entry => entry.id === entityId && entry.type === entityType);
+        return found.length === 1 ? found[0].path : '';
+      };
+      const snapshot = async () => {
+        assertCurrent(); snapshotRouter.invalidateCache?.();
+        const result = await snapshotRouter.fetchProjectZipSnapshot({ force: true, maxAgeMs: 0, serverOnly: true,
+          includeContent: true, includeBinaryFiles: true, writebackVerification: true,
+          zipTimeoutMs: Math.max(1, Math.min(30000, deadline - Date.now())) });
+        assertCurrent();
+        const skipped = [...(result?.skipped || []), ...(result?.capabilities?.skipped || [])];
+        if (!result?.ok || !Array.isArray(result.files) || result.partialSnapshot === true
+          || result.pathIdentityComplete === false || result.capabilities?.pathIdentityComplete === false
+          || skipped.some(file => file?.unknownPath || ['zip_path_invalid', 'zip_path_duplicate'].includes(file?.reason))
+          || result.capabilities?.fullProjectSnapshot === false || (result.id && result.id !== projectId)) {
+          throw error('file_move_source_unavailable', 'A complete server source snapshot is required to move a file.');
+        }
+        return result;
+      };
+      const contains = (data, path) => data.files.some(file => file.path === path)
+        || [...(data.skipped || []), ...(data.capabilities?.skipped || [])].some(file => file.path === path);
+      const verify = async (path, data) => {
+        assertCurrent();
+        const entity = at(path);
+        if (!entity || !['doc', 'file'].includes(entity.type) || (entityId && entity.id !== entityId)
+          || (entityType && entity.type !== entityType) || (proof.entityType && entity.type !== proof.entityType)
+          || (proof.sourceEntityId && entity.id !== proof.sourceEntityId)) {
+          throw error('file_move_identity_changed', 'The exact source file identity changed or is unavailable.');
+        }
+        const file = data.files.find(file => file.path === path);
+        if (await digest(file, proof.kind) !== proof.sha256.toLowerCase()) {
+          throw error('stale_source_changed', 'The source file changed after Codex read it.');
+        }
+        assertCurrent();
+        if (at(path)?.id !== entity.id || at(path)?.type !== entity.type) throw error('file_move_identity_changed', 'The source file identity changed while checking its contents.');
+        return entity;
+      };
+      const checkStep = async step => {
+        const data = await snapshot(); await verify(step.from, data);
+        if (contains(data, step.to) || at(step.to)) throw error('file_move_target_exists', 'The destination or an intermediate move path is occupied.');
+        if (step.action === 'move' && folderId(parent(step.to), projectId) !== step.folderId) {
+          throw error('file_move_folder_changed', 'The destination folder identity changed.');
+        }
+        assertCurrent();
+      };
+      const confirmStep = async step => {
+        for (let i = 0; i < 8; i++) {
+          const data = await snapshot();
+          if (!contains(data, step.from) && contains(data, step.to) && at(step.to)?.id === entityId) {
+            await verify(step.to, data); currentPath = step.to; return true;
+          }
+          if (i < 7) await delay(Math.min(250 * (i + 1), 1000));
+        }
+        return false;
+      };
+      const send = async step => {
+        await checkStep(step);
+        const csrf = csrfToken();
+        if (!csrf) throw error('file_move_identity_unavailable', 'The page request identity is unavailable. Reload Overleaf before moving files.');
+        const Controller = window.AbortController || globalThis.AbortController;
+        const controller = new Controller();
+        const timer = window.setTimeout(() => controller.abort(), Math.max(1, deadline - Date.now()));
+        let response, transportError;
+        try {
+          assertCurrent(); attempted = true;
+          response = await window.fetch(`/project/${encodeURIComponent(projectId)}/${entityType}/${encodeURIComponent(entityId)}/${step.action}`, {
+            method: 'POST', credentials: 'same-origin', signal: controller.signal,
+            headers: { 'Content-Type': 'application/json', 'X-Csrf-Token': csrf, Accept: 'application/json' },
+            body: JSON.stringify(step.action === 'rename' ? { name: basename(step.to) } : { folder_id: step.folderId })
+          });
+        } catch (caught) { transportError = caught; }
+        finally { window.clearTimeout(timer); }
+        assertCurrent();
+        if (await confirmStep(step)) return;
+        if (response && !response.ok && response.status >= 400 && response.status < 500 && response.status !== 408) {
+          const rejected = error('file_move_rejected', 'Overleaf rejected the file move.');
+          rejected.definitive = true; throw rejected;
+        }
+        const unknown = error('file_move_unconfirmed', transportError
+          ? 'The move response was lost. Check the file location before retrying.'
+          : 'The move result could not be confirmed. Check the file location before retrying.');
+        unknown.receiptUnconfirmed = true; throw unknown;
+      };
+      try {
+        assertCurrent();
+        if (!source || !target || source === target || operation.type !== 'move' || proof?.v !== 1
+          || !['text', 'binary'].includes(proof.kind) || !/^[a-f0-9]{64}$/i.test(proof.sha256 || '')) {
+          throw error('invalid_project_path', 'A verified source, different destination and content hash are required for a move.');
+        }
+        if (parent(source)) await textFileCreator?.prepareUploadParent?.(parent(source), { createMissing: false, isCurrent: () => { assertCurrent(); return true; } });
+        let data = await snapshot();
+        if (!contains(data, source) && proof.sourceEntityId && at(target)?.id === proof.sourceEntityId) {
+          entityId = proof.sourceEntityId; entityType = at(target).type;
+          await verify(target, data);
+          return { ok: true, verified: true, verification: 'overleaf-zip', idempotent: true, changedDocument: false,
+            method: 'overleaf.entity-move', moveProof: { ...proof, targetEntityId: entityId }, ...await inspectRemainingDirectories() };
+        }
+        const sourceEntity = await verify(source, data); entityId = sourceEntity.id; entityType = sourceEntity.type;
+        if (contains(data, target) || at(target)) throw error('file_move_target_exists', 'The move destination already exists.');
+        const originalParent = parent(source), destinationParent = parent(target);
+        const originalFolderId = originalParent === destinationParent ? '' : folderId(originalParent, projectId);
+        if (originalParent !== destinationParent && !originalFolderId) throw error('file_move_folder_changed', 'The original folder identity is unavailable.');
+        if (destinationParent && originalParent !== destinationParent && !folderId(destinationParent, projectId)) {
+          await textFileCreator?.prepareUploadParent?.(destinationParent, { createMissing: true, isCurrent: () => { assertCurrent(); return true; },
+            onCreatedDirectory: proof => createdDirectories.push(proof) });
+        }
+        const destinationFolderId = originalParent === destinationParent ? '' : folderId(destinationParent, projectId);
+        if (originalParent !== destinationParent && !destinationFolderId) throw error('file_move_folder_changed', 'The destination folder identity is unavailable.');
+        data = await snapshot(); await verify(source, data);
+        const steps = [];
+        const rename = to => { steps.push({ action: 'rename', from: currentPath, to }); currentPath = to; };
+        const move = to => { steps.push({ action: 'move', from: currentPath, to, folderId: destinationFolderId, fromFolderId: originalFolderId }); currentPath = to; };
+        if (originalParent === destinationParent) rename(target);
+        else if (basename(source) === basename(target)) move(target);
+        else if (!contains(data, join(originalParent, basename(target))) && !at(join(originalParent, basename(target)))) {
+          rename(join(originalParent, basename(target))); move(target);
+        } else if (!contains(data, join(destinationParent, basename(source))) && !at(join(destinationParent, basename(source)))) {
+          move(join(destinationParent, basename(source))); rename(target);
+        } else {
+          const token = window.crypto?.randomUUID?.().replace(/-/g, '').slice(0, 16);
+          if (!token) throw error('file_move_target_exists', 'An unoccupied intermediate name could not be reserved safely.');
+          const extension = basename(source).match(/\.[^.]+$/)?.[0] || '';
+          const temporary = 'codex-move-' + token + extension;
+          if ([originalParent, destinationParent].some(folder => contains(data, join(folder, temporary)) || at(join(folder, temporary)))) {
+            throw error('file_move_target_exists', 'The temporary move path is occupied. Retry on a fresh project snapshot.');
+          }
+          rename(join(originalParent, temporary)); move(join(destinationParent, temporary)); rename(target);
+        }
+        currentPath = source;
+        for (const step of steps) { await send(step); completed.push(step); }
+        return { ok: true, verified: true, verification: 'overleaf-zip', changedDocument: true, method: 'overleaf.entity-move',
+          moveProof: { v: 1, kind: proof.kind, sha256: proof.sha256.toLowerCase(), sourceEntityId: entityId, targetEntityId: entityId, entityType },
+          ...await inspectRemainingDirectories(),
+          ...(createdDirectories.length ? { createdDirectories } : {}) };
+      } catch (caught) {
+        let rolledBack = false;
+        // Only a definite refusal permits compensation. A lost response may
+        // still be in flight; never replay or reverse that uncertain mutation.
+        if (caught.definitive && completed.length && treeOperations.getProjectId() === projectId && options.isCurrent?.() !== false) {
+          try {
+            for (const prior of completed.slice().reverse()) {
+              await send({ action: prior.action, from: prior.to, to: prior.from, folderId: prior.fromFolderId });
+            }
+            rolledBack = true;
+          } catch (_rollbackError) { /* Preserve the verified entity and report its location for recovery. */ }
+        }
+        const observed = entityId ? observedPath() : '';
+        const changedDocument = attempted || createdDirectories.length > 0;
+        const reason = rolledBack ? 'The move was not completed; the original file location was restored.' : caught.message;
+        const moveRecovery = attempted && !rolledBack ? { v: 1, projectId, kind: proof?.kind, sha256: proof?.sha256,
+          entityId, entityType, sourcePath: source, targetPath: target, observedPath: observed } : null;
+        return { ok: false, code: rolledBack ? 'file_move_rolled_back' : caught.code || 'file_move_failed', reason,
+          changedDocument, rolledBack, receiptUnconfirmed: caught.receiptUnconfirmed === true,
+          ...(createdDirectories.length ? { createdDirectories } : {}),
+          ...(moveRecovery ? { moveRecovery } : {}),
+          failure: { code: caught.code || 'file_move_failed', stage: attempted ? 'verify' : 'preflight',
+            severity: changedDocument ? 'warning' : 'blocked', terminalState: changedDocument ? 'needs_review' : 'blocked',
+            changedDocument, retryable: false, file: observed || source,
+            ...(moveRecovery ? { evidence: { moveRecovery } } : {}),
+            userMessage: reason, nextAction: changedDocument ? 'Check the file location before retrying.' : 'Read the project again before retrying.' } };
+      }
+    }
+    return { moveFile };
+  }
+  return { create };
+});

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/ownedDirectoryCleanup.js

@@ -0,0 +1,94 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafOwnedDirectoryCleanup = factory();
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+  function create(deps = {}) {
+    const { document, treeOperations, delay, now, readServerSnapshot,
+      assertVerificationOwner, normalizeDomText, normalizeSafeProjectPath } = deps;
+    const { invalidateDomProjectPathCache } = treeOperations;
+    function folderIdentity(row) {
+      const entity = row?.querySelector?.('[data-file-type="folder"]');
+      return ['data-file-id', 'data-folder-id', 'data-entity-id']
+        .map(name => entity?.getAttribute?.(name) || row?.getAttribute?.(name) || '').find(Boolean) || '';
+    }
+    // Resolve every path component within its direct native child group. A
+    // collapsed/ambiguous tree is unknown, never proof that a folder is absent.
+    function locateOwnedFolder(path) {
+      let group = document.querySelector('[data-testid="file-tree-list-root"], .file-tree-list[role="tree"]');
+      const parts = path.split('/');
+      for (let index = 0; index < parts.length; index++) {
+        if (!group?.children) throw new Error('The native folder tree is unavailable.');
+        const inner = Array.from(group.children).find(node => node.classList?.contains('file-tree-folder-list-inner')) || group;
+        const matches = Array.from(inner.children).filter(node => node.getAttribute?.('role') === 'treeitem'
+          && node.querySelector?.('[data-file-type="folder"]') && normalizeDomText(node.getAttribute('aria-label')) === parts[index]);
+        if (matches.length > 1) throw new Error('The folder path is ambiguous.');
+        if (!matches.length) return null;
+        const row = matches[0];
+        if (index === parts.length - 1) return row;
+        if (row.getAttribute('aria-expanded') !== 'true') throw new Error('The ancestor folder must be expanded before cleanup.');
+        const sibling = row.nextElementSibling;
+        group = sibling?.getAttribute('role') === 'tree' ? sibling : row.querySelector('[role="tree"]');
+      }
+      return null;
+    }
+    // Native folder Delete can remove a subtree. Read/empty checks cannot
+    // make that mutation conditional on the subtree staying empty. Retain the
+    // proof for explicit native cleanup; never click Delete automatically.
+    async function cleanupCreatedDirectories(proofs, options = {}) {
+      const items = Array.isArray(proofs) ? proofs : [];
+      const removed = [], completed = new Set(), failures = [], review = [];
+      for (const proof of items.slice().sort((a, b) => String(b?.path || '').split('/').length - String(a?.path || '').split('/').length)) {
+        try {
+          const path = normalizeSafeProjectPath(proof?.path);
+          if (proof?.v !== 1 || !path || path !== proof.path || !proof.projectId || !proof.nativeFolderId
+            || (options.projectId && proof.projectId !== options.projectId)) throw new Error('The created folder identity is not proven.');
+          const assertCurrent = () => assertVerificationOwner(proof.projectId, options.isCurrent);
+          const exactRow = () => {
+            const row = locateOwnedFolder(path);
+            if (row && folderIdentity(row) !== proof.nativeFolderId) throw new Error('The created folder identity changed.');
+            return row;
+          };
+          assertCurrent();
+          for (let depth = 1; depth <= path.split('/').length; depth++) {
+            const prefix = path.split('/').slice(0, depth).join('/'), row = locateOwnedFolder(prefix);
+            if (!row) break;
+            if (prefix === path && folderIdentity(row) !== proof.nativeFolderId) throw new Error('The created folder identity changed.');
+            if (row.getAttribute('aria-expanded') === 'true') continue;
+            const toggle = row.querySelector('.folder-expand-collapse-button');
+            if (!toggle) throw new Error('The folder cannot be expanded safely.');
+            assertCurrent(); toggle.click();
+            const deadline = now() + 5000;
+            while (locateOwnedFolder(prefix)?.getAttribute('aria-expanded') !== 'true') {
+              assertCurrent(); if (now() >= deadline) throw new Error('The folder expansion was not confirmed.');
+              await delay(100); invalidateDomProjectPathCache();
+            }
+          }
+          exactRow();
+          const snapshot = await readServerSnapshot({ projectId: proof.projectId, isCurrent: options.isCurrent, includeBinaryFiles: true });
+          assertCurrent();
+          const row = exactRow();
+          const entries = [...snapshot.files, ...(snapshot.skipped || []), ...(snapshot.capabilities?.skipped || [])];
+          const serverHasEntries = entries.some(entry => String(entry?.path || '').startsWith(path + '/'));
+          if (!row) {
+            if (serverHasEntries) throw new Error('Server entries remain under the folder path; absence is unconfirmed.');
+            completed.add(proof); removed.push({ ...proof, alreadyAbsent: true, verification: 'overleaf-native-tree-and-zip' }); continue;
+          }
+          const sibling = row.nextElementSibling;
+          const group = sibling?.getAttribute('role') === 'tree' ? sibling : row.querySelector('[role="tree"]');
+          if (row.getAttribute('aria-expanded') !== 'true' || !group?.children) throw new Error('The folder contents are unknown.');
+          const inner = Array.from(group.children).find(node => node.classList?.contains('file-tree-folder-list-inner')) || group;
+          const empty = inner.children.length === 0 && !serverHasEntries;
+          review.push({ ...proof, empty, requiresExplicitCleanup: true });
+          failures.push({ path, code: empty ? 'directory_requires_explicit_cleanup' : 'created_directory_not_empty',
+            reason: empty ? 'The new empty folder remains. Review and remove it through Overleaf if appropriate.'
+              : 'The created folder contains entries or unread files and was left untouched.' });
+        } catch (error) { failures.push({ path: proof?.path || '', code: error?.code || 'created_directory_cleanup_unconfirmed', reason: error?.message || '' }); }
+      }
+      return { ok: completed.size === items.length, removed, remaining: items.filter(item => !completed.has(item)),
+        failures, review, requiresExplicitCleanup: review.length > 0, changedDocument: false };
+    }
+    return { folderIdentity, cleanupCreatedDirectories };
+  }
+  return { create };
+});

package/extension/src/page/referenceProjects.js

@@ -0,0 +1,149 @@
+(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.');
+        if (snapshot.pathIdentityComplete === false) throw failure('reference_project_incomplete', 'Some ZIP file identities could not be read unambiguously.');
+        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/reviewContext.js

@@ -0,0 +1,113 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.CodexOverleafReviewContext = api;
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+
+  const cancelledOwners = new Map();
+  function cancelOwner(token) {
+    if (typeof token !== 'string' || !token || token.length > 256) return false;
+    for (const [id, until] of cancelledOwners) if (until <= Date.now()) cancelledOwners.delete(id);
+    cancelledOwners.set(token, Date.now() + 120000); return true;
+  }
+
+  // One context per request. The small response reserve lets an expired review
+  // return its known partial evidence before the caller's transport timer fires.
+  function create(deps, input = {}) {
+    const now = deps.now || Date.now;
+    const timers = typeof deps.window?.setTimeout === 'function' ? deps.window : globalThis;
+    const started = now(), limit = input.deadlineAt == null ? started + 120000 : input.deadlineAt;
+    const deadlineAt = Number.isFinite(limit) ? limit - Math.min(250, Math.max(0, limit - started) / 10) : started;
+    const cancellation = deps.readWriteCancellationSequence?.();
+    const appliedLists = new Set(), observations = new Map();
+    let stopped = null, mutationStarted = false;
+    const params = { ...input, deadlineAt };
+    const failure = (code, reason) => ({ ok: false, code, reason, changedDocument: false,
+      failure: { code: code === 'codex_cancelled' ? 'codex_run_cancelled' : 'tracked_changes_remain',
+        stage: 'reviewing', severity: 'blocked', terminalState: 'blocked', changedDocument: false,
+        userMessage: reason, nextAction: 'Check the retained per-file results in Overleaf before retrying.',
+        evidence: { originalCode: code, writeStarted: false } } });
+    function check() {
+      if (stopped) return stopped;
+      if (params.reviewOwnerToken && cancelledOwners.has(params.reviewOwnerToken))
+        return stopped = failure('codex_cancelled', 'The Undo owner disconnected; no further review writes were started.');
+      if (!Number.isFinite(limit) || now() >= deadlineAt)
+        return stopped = failure('writeback_deadline_exceeded', 'The review time budget expired; no further review writes were started.');
+      if (typeof deps.readWriteCancellationSequence === 'function' && deps.readWriteCancellationSequence() !== cancellation)
+        return stopped = failure('codex_cancelled', 'The review was cancelled; no further review writes were started.');
+      const project = deps.getProjectId?.() || /\/project\/([^/?#]+)/.exec(deps.window?.location?.pathname || '')?.[1];
+      if (!params.runProjectId || (project && project !== params.runProjectId))
+        return stopped = failure('aborted_project_changed', 'The original review project is no longer active.');
+      const blocked = deps.checkWritebackRunProjectId?.(params);
+      if (blocked) return stopped = blocked.skipped?.[0]?.result || blocked;
+      return null;
+    }
+    function assert() {
+      const blocked = check();
+      if (blocked) throw Object.assign(new Error(blocked.reason || blocked.code), { reviewFailure: blocked });
+    }
+    async function wait(work) {
+      assert();
+      let timer;
+      try {
+        const timeout = new Promise((_, reject) => {
+          timer = timers.setTimeout(() => {
+            const blocked = check() || failure('writeback_deadline_exceeded', 'The review time budget expired.');
+            stopped = blocked;
+            reject(Object.assign(new Error(blocked.reason), { reviewFailure: blocked }));
+          }, Math.max(0, deadlineAt - now()));
+        });
+        const result = await Promise.race([Promise.resolve().then(() => { assert(); return work(); }), timeout]);
+        assert();
+        return result;
+      } finally { if (timer != null) timers.clearTimeout(timer); }
+    }
+    const remember = entry => {
+      if (entry.result?.changedDocument === true || entry.result?.failure?.changedDocument === true) mutationStarted = true;
+      const ref = entry.trackedChange || { path: entry.operation?.path || '', key: 'snapshot-undo:' + (entry.operation?.path || ''), id: '' };
+      observations.set(ref.path + '\0' + (ref.key || ref.id || ''), { trackedChange: ref, result: entry.result });
+    };
+    const scoped = { ...deps, reviewGuard: check, reviewAwait: work => wait(work),
+      reviewDeadlineAt: deadlineAt,
+      createReviewApplied() { const list = []; appliedLists.add(list); return list; } };
+    for (const name of ['openFileByPath', 'setReviewingEnabled', 'verifyActiveEditorText']) {
+      if (typeof deps[name] === 'function') scoped[name] = (...args) => wait(() => deps[name](...args));
+    }
+    scoped.delay = ms => wait(() => deps.delay(Math.min(ms, Math.max(0, deadlineAt - now()))));
+    if (typeof deps.readActiveEditorText === 'function') scoped.readActiveEditorText = (...args) => { assert(); return deps.readActiveEditorText(...args); };
+    if (typeof deps.clickNode === 'function') scoped.clickNode = (...args) => { assert(); mutationStarted = true; return deps.clickNode(...args); };
+    for (const name of ['applyOperationsCore', 'applyOperationsWithNoTraceUndo']) {
+      if (typeof deps[name] !== 'function') continue;
+      scoped[name] = async (operations, options = {}) => {
+        assert();
+        const result = await deps[name](operations, { ...options, deadlineAt,
+          reviewGuard: check, reviewAwait: work => wait(work),
+          onOperationResult(entry) { remember(entry); options.onOperationResult?.(entry); } });
+        for (const entry of result.applied || []) remember(entry);
+        // Preserve a completed in-flight result even if cancellation just arrived.
+        return result;
+      };
+    }
+    if (typeof deps.confirmReviewWriteback === 'function') scoped.confirmReviewWriteback = async (original, result) => {
+      for (const entry of result.applied || []) remember(entry);
+      return deps.confirmReviewWriteback({ ...original, deadlineAt, reviewGuard: check, reviewAwait: work => wait(work) }, result);
+    };
+    async function run(work) {
+      try { assert(); return await work(scoped, params); }
+      catch (error) {
+        if (!error?.reviewFailure) throw error;
+        for (const list of appliedLists) for (const entry of list) remember(entry);
+        const applied = [...observations.values()].filter(entry => entry.result?.ok !== false);
+        const path = deps.getActiveFilePath?.() || '';
+        const changedDocument = mutationStarted || applied.some(entry => entry.result?.changedDocument !== false);
+        const blocked = { ...error.reviewFailure, changedDocument,
+          failure: { ...error.reviewFailure.failure, changedDocument,
+            evidence: { ...error.reviewFailure.failure?.evidence, writeStarted: changedDocument } } };
+        return { ok: false, applied, skipped: [{ trackedChange: { path }, result: blocked }] };
+      }
+    }
+    return Object.freeze({ run, check, assert, wait, params, scoped });
+  }
+  return Object.freeze({ create, cancelOwner });
+});