codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/shared/sharedSessionBridge.js

@@ -0,0 +1,311 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory(require('./sharedSessionTransfer'));
+  else root.CodexOverleafModuleRegistry.define('SharedSessionBridge', ['SharedSessionTransfer'], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : this, function (Transfer) {
+  'use strict';
+  const MESSAGE = 'codex-overleaf/shared-sessions-v1';
+  const LOCK_PORT = 'codex-overleaf/shared-session-lock-v1';
+  const CHANGE_KEY = 'codex-overleaf-shared-sessions-changed-v1';
+  const BASE = Symbol('shared-session-base');
+  const failure = (code, message) => Object.assign(new Error(message), { code });
+  const clone = value => value == null ? value : JSON.parse(JSON.stringify(value));
+  const clean = record => {
+    const result = clone(record);
+    if (result) delete result.sharedRevision;
+    return result;
+  };
+
+  function createBridge(environment = globalThis) {
+    const chromeApi = environment.chrome;
+    const clientId = environment.crypto?.randomUUID?.() || 'page-' + Date.now() + '-' + Math.random();
+    const migrations = new Map(), baselines = new Map(), heldLocks = new Map();
+    let legacy, wrapped;
+    function enabled() {
+      return Boolean(chromeApi?.runtime?.sendMessage && chromeApi?.runtime?.connect
+        && environment.location?.protocol === 'https:'
+        && ['overleaf.com', 'www.overleaf.com', 'cn.overleaf.com'].includes(environment.location?.hostname)
+        && /^\/project(?:\/|$)/.test(environment.location?.pathname || ''));
+    }
+    function capture(projectId = '', accountScopeId) {
+      const current = environment.codexOverleafDeriveAccountScopeId?.();
+      if (!current || (accountScopeId && current !== accountScopeId))
+        throw failure('account_scope_unavailable', 'A stable matching Overleaf account is required for shared history.');
+      return { accountScopeId: current, projectId };
+    }
+    function assertScope(value) { capture(value.projectId, value.accountScopeId); }
+    const cacheKey = (value, id) => value.accountScopeId + ':' + id;
+    const lockKey = (kind, value) => kind === 'review' ? 'review:' + JSON.stringify([value.accountScopeId, value.projectId, value.runId]) : kind === 'preferences' ? 'preferences' : 'state:' + value.accountScopeId;
+    async function request(method, value, args = {}) {
+      assertScope(value);
+      const lock = heldLocks.get(lockKey('state', value));
+      if (lock?.lost) throw failure('storage_lock_lost', 'The background storage connection was lost.');
+      const response = await chromeApi.runtime.sendMessage({
+        ...args, type: MESSAGE, method, scope: value, clientId, lockToken: lock?.token || ''
+      });
+      assertScope(value);
+      if (!response?.ok)
+        throw failure(response?.error?.code || 'shared_store_unavailable',
+          response?.error?.message || 'Shared history is unavailable. Reload the extension and this page.');
+      return response.result;
+    }
+
+    // Live ports own the locks. Worker/page termination releases them without
+    // allowing a stale client to silently fall back to an origin-local lock.
+    async function acquire(kind, value, work, onLost) {
+      assertScope(value);
+      const key = lockKey(kind, value), port = chromeApi.runtime.connect({ name: LOCK_PORT });
+      let timer, heartbeat, released = false, lock = null, rejectGrant;
+      const granted = new Promise((resolve, reject) => {
+        rejectGrant = reject;
+        port.onMessage.addListener(message => {
+          if (message?.type === 'busy') { reject(failure('review_busy', 'Another page is reviewing this run. Wait for it to finish.')); return; }
+          if (message?.type !== 'granted' || lock || released) return;
+          clearTimeout(timer);
+          lock = { token: message.token, deadlineAt: message.deadlineAt, lost: false };
+          heldLocks.set(key, lock);
+          resolve();
+        });
+        port.onDisconnect.addListener(() => {
+          // Read lastError to consume the runtime's disconnected-port warning.
+          void chromeApi.runtime.lastError;
+          if (lock) { lock.lost = true; if (!released) onLost?.(lock.token); }
+          if (!released) reject(failure('storage_lock_lost', 'The shared history lock disconnected.'));
+        });
+        timer = environment.setTimeout(() => reject(failure('storage_lock_timeout',
+          'Another page is saving history. Retry after it finishes.')), 20000);
+      });
+      try {
+        heartbeat = environment.setInterval(() => {
+          try { port.postMessage({ type: 'ping' }); }
+          catch (_error) {
+            if (lock) lock.lost = true;
+            rejectGrant(failure('storage_lock_lost', 'The shared history lock disconnected.'));
+          }
+        }, 15000);
+        port.postMessage({ type: 'acquire', kind, scope: value });
+        await granted;
+        assertScope(value);
+        const assertOwner = () => { assertScope(value); if (lock.lost) throw failure('storage_lock_lost', 'The shared review owner disconnected.'); };
+        assertOwner.token = lock.token;
+        assertOwner.markDispatched = async () => {
+          assertOwner();
+          const lease = await request('review-dispatched', value, { runId: value.runId, reviewToken: lock.token });
+          assertOwner(); assertOwner.deadlineAt = lease.deadlineAt; return lease.deadlineAt;
+        };
+        const result = await work(assertOwner);
+        assertScope(value);
+        if (lock.lost) throw failure('storage_lock_lost', 'The shared history lock was lost before completion.');
+        return result;
+      } finally {
+        released = true;
+        if (kind === 'review' && lock && !lock.lost) {
+          await new Promise(resolve => {
+            const done = message => { if (message?.type === 'released') { port.onMessage.removeListener(done); environment.clearTimeout(releaseTimer); resolve(); } };
+            const releaseTimer = environment.setTimeout(resolve, 2000);
+            port.onMessage.addListener(done);
+            try { port.postMessage({ type: 'release-review', token: lock.token }); } catch (_) { resolve(); }
+          });
+        }
+        environment.clearTimeout(timer);
+        environment.clearInterval(heartbeat);
+        if (heldLocks.get(key) === lock) heldLocks.delete(key);
+        port.disconnect();
+      }
+    }
+    async function migrate(value) {
+      const account = value.accountScopeId;
+      if (!migrations.has(account)) {
+        const pending = (async () => {
+          const status = await request('migration-status', value);
+          if (status.complete) return;
+          if (!legacy) throw failure('shared_store_unavailable', 'Legacy history storage is not ready.');
+          // Read the original site DB once. Only explicitly owned records may
+          // cross origins. Unknown-account rows remain untouched for recovery.
+          const records = (await legacy.getAllSessions())
+            .filter(record => record?.accountScopeId === account && record.projectId && record.id);
+          await acquire('state', value, async () => {
+            for (const record of records) {
+              const recordScope = capture(record.projectId, account);
+              await request('import', recordScope, {
+                record: legacy.buildSessionRecord(record, { preserveRunActionPayload: true })
+              });
+            }
+            await request('migration-complete', value);
+          });
+        })();
+        migrations.set(account, pending);
+        pending.catch(() => { if (migrations.get(account) === pending) migrations.delete(account); });
+      }
+      await migrations.get(account);
+      assertScope(value);
+    }
+    async function withLock(kind, input, work) {
+      const value = capture(input.projectId, input.accountScopeId);
+      await migrate(value); // Before acquiring either lock: no migration/lock cycle.
+      return acquire(kind, value, work);
+    }
+    async function withWrite(value, work) {
+      await migrate(value);
+      const held = heldLocks.get(lockKey('state', value));
+      if (held) {
+        if (held.lost) throw failure('storage_lock_lost', 'The shared history lock was lost.');
+        return work();
+      }
+      return acquire('state', value, work);
+    }
+    function tag(record, value, adopt) {
+      if (!record) return record;
+      const base = clean(record);
+      if (adopt) baselines.set(cacheKey(value, record.id), base);
+      Object.defineProperty(record, BASE, { value: base, enumerable: true });
+      return record;
+    }
+    async function list(projectId = '', adopt = true) {
+      const value = capture(projectId);
+      await migrate(value);
+      const result = []; let after = '';
+      do {
+        const page = await request('list', value, { after });
+        for (const record of page.records) {
+          result.push(tag(record, value, adopt && !heldLocks.has(lockKey('state', value))));
+        }
+        after = page.next;
+      } while (after);
+      return result;
+    }
+    function adopt(records) {
+      const value = capture();
+      for (const record of records) {
+        if (record.accountScopeId === value.accountScopeId)
+          baselines.set(cacheKey(value, record.id), clean(record));
+      }
+    }
+    function hasLocalChanges(session) {
+      const base = baselines.get(cacheKey(capture(), session.id));
+      return Boolean(base && (session.updatedAt !== base.updatedAt || session.task !== base.task));
+    }
+    function wasStored(id) { return baselines.has(cacheKey(capture(), id)); }
+    async function put(records, options = {}) {
+      if (!records.length) return [];
+      const value = capture(records[0].projectId, records[0].accountScopeId);
+      if (records.some(record => record.projectId !== value.projectId || record.accountScopeId !== value.accountScopeId))
+        throw failure('shared_store_scope_mismatch', 'A session batch must belong to one account and project.');
+      return withWrite(value, async () => {
+        const entries = records.map(record => ({
+          record: clean(record),
+          base: record[BASE] || baselines.get(cacheKey(value, record.id)) || null
+        }));
+        const transfer = await Transfer.encode(entries);
+        const written = await request(transfer.method, value, { ...transfer.payload, reviewRunIds: options.reviewRunIds || [] });
+        // Keep the caller's submitted view as its merge baseline. A merged
+        // remote change has not necessarily been applied to the visible UI.
+        for (const entry of entries) baselines.set(cacheKey(value, entry.record.id), clean(entry.record));
+        return written;
+      });
+    }
+    async function get(id) {
+      const value = capture();
+      await migrate(value);
+      const record = await request('get', value, { id });
+      return tag(record, value, !heldLocks.has(lockKey('state', value)));
+    }
+    async function erase(method, projectId = '', id, accountScopeId) {
+      const value = capture(projectId, accountScopeId);
+      return withWrite(value, () => request(method, value, { id }));
+    }
+    function decorate(api) {
+      legacy = api;
+      wrapped = { ...api };
+      const route = (name, shared) => {
+        wrapped[name] = function (...args) {
+          return enabled() ? shared(...args) : api[name](...args);
+        };
+      };
+      route('buildSessionRecord', (input, options) => {
+        const record = api.buildSessionRecord(input, options);
+        const base = input[BASE] || baselines.get(cacheKey({ accountScopeId: record.accountScopeId }, record.id));
+        if (base) Object.defineProperty(record, BASE, { value: clone(base), enumerable: true });
+        return record;
+      });
+      route('getAllSessions', () => list());
+      route('getRecord', (store, id) => store === 'sessions' ? get(id) : api.getRecord(store, id));
+      route('getAllByIndex', async (store, index, value) => {
+        if (store !== 'sessions') return api.getAllByIndex(store, index, value);
+        const records = await list(index === 'projectId' ? value : '');
+        return records.filter(record => record[index] === value);
+      });
+      route('claimSessionsForAccount', async (projectId, accountScopeId, deleted = []) => {
+        capture(projectId, accountScopeId);
+        return (await list(projectId)).filter(record => !deleted.includes(record.id));
+      });
+      route('putRecord', async (store, record) =>
+        store === 'sessions' ? (await put([record]))[0] : api.putRecord(store, record));
+      route('putRecords', (store, records, options) =>
+        store === 'sessions' ? put(records, options) : api.putRecords(store, records));
+      route('deleteRecord', (store, id, expectedScope) =>
+        store === 'sessions' ? erase('delete', expectedScope?.projectId || '', id, expectedScope?.accountScopeId)
+          : api.deleteRecord(store, id));
+      route('deleteByIndex', async (store, index, value) => {
+        if (store !== 'sessions') return api.deleteByIndex(store, index, value);
+        if (index === 'projectId') return erase('clear-project', value);
+        for (const record of (await list()).filter(record => record[index] === value))
+          await erase('delete', record.projectId, record.id);
+      });
+      route('clearStore', store =>
+        store === 'sessions' ? erase('clear-account') : api.clearStore(store));
+      route('clearAllStores', async () => {
+        const value = capture();
+        await erase('clear-account');
+        // Preserve other accounts' legacy backups. Auxiliary stores remain
+        // site-local and retain their existing explicit clear-all semantics.
+        for (const record of await api.getAllSessions()) {
+          if (record.accountScopeId === value.accountScopeId) await api.deleteRecord('sessions', record.id);
+        }
+        await api.clearAuxiliaryStores();
+        baselines.clear();
+      });
+      route('listRecentProjectsAcrossAccount', async options => {
+        if (!options?.accountScopeId) return [];
+        capture('', options.accountScopeId);
+        return api.filterRecentProjectsAcrossAccount(await list(), options);
+      });
+      Object.assign(wrapped, {
+        sharedSessionsEnabled: enabled,
+        withSharedReviewLock: async (input, work) => {
+          const value = { ...capture(input.projectId, input.accountScopeId), runId: input.runId };
+          return acquire('review', value, work, input.onLost);
+        },
+        hasSharedReviewOwner: input => request('review-owner', capture(input.projectId, input.accountScopeId), { runId: input.runId }),
+        withSharedLock: withLock,
+        readSharedProjectSnapshot: projectId => list(projectId, false),
+        adoptSharedSessionBaseline: adopt,
+        hasUnpersistedSharedSession: hasLocalChanges,
+        wasSharedSessionStored: wasStored
+      });
+      return wrapped;
+    }
+    function subscribe(listener) {
+      if (!enabled() || !chromeApi.storage?.onChanged) return () => {};
+      const onChange = (changes, area) => {
+        const change = changes[CHANGE_KEY]?.newValue;
+        if (area !== 'local' || !change || change.clientId === clientId) return;
+        const account = environment.codexOverleafDeriveAccountScopeId?.();
+        if (account && change.accountScopeId === account) listener(change);
+      };
+      chromeApi.storage.onChanged.addListener(onChange);
+      return () => chromeApi.storage.onChanged.removeListener(onChange);
+    }
+    return { enabled, decorate, withLock, subscribe,
+      async readMeta(input) {
+        const value = capture(input.projectId, input.accountScopeId);
+        await migrate(value);
+        return request('meta-read', value);
+      },
+      async writeMeta(input, meta) {
+        const value = capture(input.projectId, input.accountScopeId);
+        return request('meta-write', value, { meta });
+      }
+    };
+  }
+  return { createBridge, ...createBridge() };
+});

package/extension/src/shared/sharedSessionTransfer.js

@@ -0,0 +1,140 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafModuleRegistry.define('SharedSessionTransfer', [], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : window, function () {
+  'use strict';
+  const MAX_WIRE_BYTES = 24 * 1024 * 1024;
+  // The old UTF-16 estimate admitted up to 3 UTF-8 bytes per code unit.
+  // Retain that finite Unicode window without enlarging ordinary ASCII writes.
+  const MAX_RECORD_BYTES = MAX_WIRE_BYTES * 3 / 2;
+  const MAX_RESPONSE_BYTES = MAX_RECORD_BYTES;
+  const MAX_DECODED_BYTES = 2 * MAX_RECORD_BYTES + 64 * 1024;
+  const error = (code, message) => Object.assign(new Error(message), { code });
+  const tooLarge = () => error('shared_session_too_large', 'The session batch exceeds the bounded shared storage transfer limit.');
+  const invalid = () => error('shared_session_transfer_invalid', 'The shared history transfer is invalid or incomplete.');
+  const byteLength = text => new TextEncoder().encode(text).byteLength;
+
+  function serialize(value, limit) {
+    // Count a lower bound during serialization, before a large aggregate string
+    // can be produced. The final UTF-8 check also includes commas and escaping.
+    let lowerBound = 0;
+    const text = JSON.stringify(value, function (key, item) {
+      if (key && !Array.isArray(this)) lowerBound += byteLength(JSON.stringify(key)) + 1;
+      if (typeof item === 'string') {
+        if (item.length > limit) throw tooLarge();
+        lowerBound += byteLength(JSON.stringify(item));
+      } else if (item === null) lowerBound += 4;
+      else if (typeof item === 'number') lowerBound += Number.isFinite(item) ? String(item).length : 4;
+      else if (typeof item === 'boolean') lowerBound += String(item).length;
+      else if (item && typeof item === 'object') lowerBound += 2;
+      if (lowerBound > limit) throw tooLarge();
+      return item;
+    });
+    if (typeof text !== 'string') throw invalid();
+    const bytes = byteLength(text);
+    if (bytes > limit) throw tooLarge();
+    return { text, bytes };
+  }
+
+  function validateRecord(record) {
+    const value = serialize(record, MAX_RECORD_BYTES);
+    if (value.bytes > MAX_WIRE_BYTES && value.text.length * 2 > MAX_WIRE_BYTES) throw tooLarge();
+  }
+
+  function validateResponse(records) { serialize(records, MAX_RESPONSE_BYTES); }
+
+  function validateEntries(entries) {
+    if (!Array.isArray(entries)) throw invalid();
+    for (const entry of entries) {
+      if (!entry || !entry.record || typeof entry.record !== 'object' || Array.isArray(entry.record)) throw invalid();
+      validateRecord(entry.record);
+      if (entry.base != null) {
+        if (typeof entry.base !== 'object' || Array.isArray(entry.base)) throw invalid();
+        // A previously stored merged baseline may be larger than new records;
+        // allow a bounded old base so a smaller candidate can repair it.
+        serialize(entry.base, MAX_DECODED_BYTES);
+      }
+    }
+  }
+
+  async function readLimited(stream, limit) {
+    const reader = stream.getReader(), chunks = [];
+    let length = 0;
+    try {
+      while (true) {
+        const result = await reader.read();
+        if (result.done) break;
+        length += result.value.byteLength;
+        if (length > limit) { await reader.cancel().catch(() => {}); throw tooLarge(); }
+        chunks.push(result.value);
+      }
+    } finally { reader.releaseLock(); }
+    const output = new Uint8Array(length); let offset = 0;
+    for (const chunk of chunks) { output.set(chunk, offset); offset += chunk.byteLength; }
+    return output;
+  }
+
+  function toBase64(bytes) {
+    let text = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(text);
+  }
+  function fromBase64(value) {
+    if (typeof value !== 'string' || !value.length || value.length % 4
+      || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) throw invalid();
+    const text = atob(value);
+    const bytes = new Uint8Array(text.length);
+    for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i);
+    return bytes;
+  }
+
+  async function encode(entries, environment = globalThis) {
+    validateEntries(entries);
+    const raw = serialize(entries, MAX_DECODED_BYTES);
+    if (raw.bytes <= MAX_WIRE_BYTES || (raw.bytes <= MAX_RECORD_BYTES && raw.text.length * 2 <= MAX_WIRE_BYTES)) {
+      return { method: 'put', payload: { entries } };
+    }
+    if (typeof environment.CompressionStream !== 'function') {
+      throw error('shared_session_compression_unavailable',
+        'Lossless transfer compression is unavailable. History remains in memory; retry with a supported browser.');
+    }
+    const input = new Blob([raw.text]).stream();
+    const packed = await readLimited(input.pipeThrough(new environment.CompressionStream('gzip')),
+      Math.floor((MAX_WIRE_BYTES - 1024) * 3 / 4));
+    const payload = { encoding: 'gzip-base64', version: 1, decodedBytes: raw.bytes, data: toBase64(packed) };
+    serialize(payload, MAX_WIRE_BYTES);
+    // A distinct method makes an older worker reject rather than acknowledge
+    // an absent `entries` array as a successful empty write.
+    return { method: 'put-compressed', payload };
+  }
+
+  async function decode(message, environment = globalThis) {
+    if (message.method !== 'put-compressed') {
+      const entries = message.method === 'import' ? [{ record: message.record }] : message.entries || [];
+      const raw = serialize(entries, MAX_RECORD_BYTES);
+      if (raw.bytes > MAX_WIRE_BYTES && raw.text.length * 2 > MAX_WIRE_BYTES) throw tooLarge();
+      validateEntries(entries); return entries;
+    }
+    const payload = { encoding: message.encoding, version: message.version, decodedBytes: message.decodedBytes, data: message.data };
+    serialize(payload, MAX_WIRE_BYTES);
+    if (message.entries != null || payload.encoding !== 'gzip-base64' || payload.version !== 1
+      || !Number.isSafeInteger(payload.decodedBytes) || payload.decodedBytes < 1 || payload.decodedBytes > MAX_DECODED_BYTES) throw invalid();
+    if (typeof environment.DecompressionStream !== 'function') throw error('shared_session_compression_unavailable',
+      'Lossless transfer decompression is unavailable. Reload the extension and retry.');
+    let bytes;
+    try {
+      bytes = await readLimited(new Blob([fromBase64(payload.data)]).stream()
+        .pipeThrough(new environment.DecompressionStream('gzip')), MAX_DECODED_BYTES);
+    } catch (failure) {
+      if (['shared_session_too_large', 'shared_session_transfer_invalid'].includes(failure?.code)) throw failure;
+      throw invalid();
+    }
+    if (bytes.byteLength !== payload.decodedBytes) throw invalid();
+    let entries;
+    try { entries = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+    catch (_error) { throw invalid(); }
+    validateEntries(entries);
+    return entries;
+  }
+  return { MAX_WIRE_BYTES, MAX_RECORD_BYTES, MAX_RESPONSE_BYTES, MAX_DECODED_BYTES, byteLength, validateRecord, validateResponse, encode, decode };
+});

package/extension/src/shared/staleGuard.js

@@ -17,7 +17,9 @@
       if (typeof file?.path === 'string') {
         const path = normalizePath(file.path);
         if (path) {
-          lookup.set(path, normalizeText(file.content));
+          // Patch offsets refer to this exact UTF-16 string. Normalize only
+          // for comparisons, never discard the source coordinate system.
+          lookup.set(path, String(file.content ?? ''));
         }
       }
     }
@@ -40,13 +42,7 @@
       };
     }
 
-    const baseContent = baseFileLookup.get(filePath);
-    if (!baseContent || baseContent.trim().length === 0) {
-      if (typeof console !== 'undefined') {
-        console.warn('[codex-overleaf] staleGuard: base empty for', filePath, '→ skipping check');
-      }
-      return { ok: true };
-    }
+    const baseContent = normalizeText(baseFileLookup.get(filePath));
     const current = normalizeText(currentContent);
     if (current !== baseContent) {
       if (typeof console !== 'undefined') {
@@ -55,7 +51,7 @@
           'base[0..80]:', JSON.stringify(baseContent.slice(0, 80)),
           'current[0..80]:', JSON.stringify(current.slice(0, 80)));
       }
-      const patchRangeFreshness = checkPatchRangeFreshness(operation, current);
+      const patchRangeFreshness = checkPatchRangeFreshness(operation, currentContent, baseFileLookup);
       if (patchRangeFreshness) {
         return patchRangeFreshness;
       }
@@ -71,13 +67,17 @@
     return { ok: true };
   }
 
-  function checkPatchRangeFreshness(operation, currentContent) {
-    const patches = Array.isArray(operation?.patches) ? operation.patches : [];
+  function checkPatchRangeFreshness(operation, currentContent, baseFileLookup) {
+    const prepared = prepareOperationPatches(operation, currentContent, baseFileLookup);
+    if (!prepared.ok) {
+      return { ...prepared, code: 'stale_patch_range', reasonKey: 'stalePatchConflict' };
+    }
+    const patches = prepared.patches;
     if (!patches.length) {
       return null;
     }
 
-    const current = normalizeText(currentContent);
+    const current = String(currentContent ?? '');
     for (const rawPatch of patches) {
       const from = Number(rawPatch?.from);
       const to = Number(rawPatch?.to);
@@ -107,12 +107,116 @@
     };
   }
 
+  // Bridge the raw Native baseline to the editor's line-ending representation.
+  // Logical LF offsets are only an intermediate coordinate system: both the
+  // range check and the eventual editor dispatch use the same raw patches.
+  function prepareOperationPatches(operation, currentContent, baseFileLookup) {
+    const patches = Array.isArray(operation?.patches) ? operation.patches : [];
+    const current = String(currentContent ?? '');
+    const path = normalizePath(operation?.path);
+    const base = baseFileLookup?.get(path);
+    if (!patches.length || typeof base !== 'string' || base === current) {
+      return { ok: true, patches };
+    }
+    const baseMap = lineEndingMap(base);
+    const currentMap = lineEndingMap(current);
+    // With no CRLF on either side, retain the existing raw range semantics.
+    if (!baseMap.removed.length && !currentMap.removed.length) return { ok: true, patches };
+
+    const groups = [];
+    let previousTo = 0;
+    for (const patch of patches) {
+      const from = Number(patch?.from), to = Number(patch?.to);
+      if (!Number.isInteger(from) || !Number.isInteger(to) || from < previousTo || to < from || to > base.length) {
+        return patchMappingFailure('invalid_patch');
+      }
+      if (base.slice(from, to) !== String(patch.expected ?? '')) return patchMappingFailure('stale_patch');
+      previousTo = to;
+      // Expand only a split CRLF or a new pair formed across an edit edge.
+      // Other neighbouring newlines belong to the editor and stay untouched.
+      let start = from, end = to;
+      const insert = String(patch.insert ?? '');
+      if (base[from - 1] === '\r' && (base[from] === '\n' || insert.startsWith('\n') || (!insert && base[to] === '\n'))) start -= 1;
+      if (base[to] === '\n' && (base[to - 1] === '\r' || insert.endsWith('\r') || (!insert && base[from - 1] === '\r'))) end += 1;
+      const previous = groups[groups.length - 1];
+      if (previous && start <= previous.end) {
+        previous.end = Math.max(previous.end, end);
+        previous.patches.push({ ...patch, from, to });
+      } else groups.push({ start, end, patches: [{ ...patch, from, to }] });
+    }
+
+    const mapped = [], sourceChanges = [];
+    for (const group of groups) {
+      const logicalFrom = baseMap.toLogical(group.start), logicalTo = baseMap.toLogical(group.end);
+      if (logicalTo > currentMap.length) return patchMappingFailure('invalid_patch');
+      const from = currentMap.toRaw(logicalFrom), to = currentMap.toRaw(logicalTo);
+      const expected = current.slice(from, to);
+      if (normalizeText(expected) !== normalizeText(base.slice(group.start, group.end))) {
+        return patchMappingFailure('stale_patch');
+      }
+      let insert = base.slice(group.start, group.end);
+      for (const patch of group.patches.slice().sort((left, right) => right.from - left.from)) {
+        if (insert.slice(patch.from - group.start, patch.to - group.start) !== String(patch.expected ?? '')) {
+          return patchMappingFailure('stale_patch');
+        }
+        insert = insert.slice(0, patch.from - group.start) + String(patch.insert ?? '') + insert.slice(patch.to - group.start);
+      }
+      sourceChanges.push({ from: group.start, to: group.end, insert });
+      const sourceEnding = nearestLineEnding(base, group.start);
+      const editorEnding = nearestLineEnding(current, from);
+      if (sourceEnding && editorEnding && sourceEnding !== editorEnding) {
+        insert = normalizeText(insert).replace(/\n/g, editorEnding);
+      }
+      // Leave equal surrounding text out of the dispatch/Track range.
+      let prefix = 0, oldEnd = expected.length, newEnd = insert.length;
+      while (prefix < oldEnd && prefix < newEnd && expected[prefix] === insert[prefix]) prefix += 1;
+      while (oldEnd > prefix && newEnd > prefix && expected[oldEnd - 1] === insert[newEnd - 1]) { oldEnd -= 1; newEnd -= 1; }
+      mapped.push({ from: from + prefix, to: from + oldEnd, expected: expected.slice(prefix, oldEnd), insert: insert.slice(prefix, newEnd) });
+    }
+    // A later operation in the same batch still addresses the original
+    // representation, so advance its baseline separately from editor text.
+    let sourceContent = base;
+    for (const patch of sourceChanges.reverse()) {
+      sourceContent = sourceContent.slice(0, patch.from) + patch.insert + sourceContent.slice(patch.to);
+    }
+    return { ok: true, patches: mapped, sourceContent };
+  }
+
+  function patchMappingFailure(code) {
+    return { ok: false, code, reason: 'Codex 要修改的位置已经无法和当前 Overleaf 内容对齐，所以没有写入。请重新运行任务。' };
+  }
+
+  function lineEndingMap(text) {
+    const removed = [];
+    for (let index = 0; index < text.length - 1; index += 1) {
+      if (text[index] === '\r' && text[index + 1] === '\n') removed.push(index);
+    }
+    function countBefore(offset, logical) {
+      let low = 0, high = removed.length;
+      while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (removed[middle] - (logical ? middle : 0) < offset) low = middle + 1;
+        else high = middle;
+      }
+      return low;
+    }
+    return { removed, length: text.length - removed.length,
+      toLogical: offset => offset - countBefore(offset, false),
+      toRaw: offset => offset + countBefore(offset, true) };
+  }
+
+  function nearestLineEnding(text, offset) {
+    let newline = text.indexOf('\n', offset);
+    if (newline < 0) newline = text.lastIndexOf('\n', offset - 1);
+    return newline < 0 ? '' : text[newline - 1] === '\r' ? '\r\n' : '\n';
+  }
+
   function updateExpectedFileContent(baseFileLookup, filePath, content) {
     const path = normalizePath(filePath);
     if (!baseFileLookup || !path) {
       return;
     }
-    baseFileLookup.set(path, normalizeText(content));
+    baseFileLookup.set(path, String(content ?? ''));
   }
 
   function removeExpectedFile(baseFileLookup, filePath) {
@@ -152,6 +256,7 @@
   return {
     buildBaseFileLookup,
     checkOperationFreshness,
+    prepareOperationPatches,
     updateExpectedFileContent,
     removeExpectedFile,
     moveExpectedFile,