codex-overleaf-link 2.3.5 → 2.4.0

package/extension/src/content/otWarmMirror.js

@@ -1,6 +1,5 @@
 (function initCodexOverleafOtWarmMirror() {
   'use strict';
-
   // Experimental OT warm-mirror glue carved out of contentRuntime.js (v1.4.9
   // structural-debt phase 5): the per-project enable toggle flow, the
   // poll/flush timers and patch queue, mirror prefetch, warm-start
@@ -50,7 +49,9 @@
     } = deps;
 
   let currentOtStatus = 'off';
+  let otTogglePending = false;
   let otSyncRequestId = 0;
+  let otStartRetryCount = 0;
   let otWarmMirrorProjectId = '';
   let lastExperimentalOtProjectId = '';
   let otWarmMirrorState = {
@@ -61,7 +62,10 @@
     patchQueue: [],
     lastStatus: 'off',
     lastPatchAt: 0,
-    lastErrorCode: ''
+    lastErrorCode: '',
+    failureActive: false,
+    lastFailure: null,
+    suspended: false
   };
   let mirrorPrefetchState = {
     inFlight: null,
@@ -159,14 +163,14 @@
   }
 
   async function handleExperimentalOtToggleClick(event) {
-    // The handler is bound to the visible checkbox: by the time click fires,
-    // pre-click activation has ALREADY flipped .checked — that flipped value
-    // is the user's intended target. preventDefault then rolls the visual
-    // state back (synchronously, when dispatch completes), and the confirm
-    // flow applies the target only after approval.
+    // Capture the pre-activated target, then let cancelled click dispatch
+    // restore the old checkbox value before projecting the approved state.
     const clicked = event?.currentTarget || event?.target;
     const targetEnabled = clicked && typeof clicked.checked === 'boolean' ? clicked.checked : undefined;
+    const projectId = getCurrentProjectId();
     event.preventDefault();
+    await new Promise(resolve => window.setTimeout(resolve, 0));
+    if (projectId !== getCurrentProjectId()) return;
     await toggleExperimentalOtCheckbox(targetEnabled);
   }
 
@@ -180,9 +184,12 @@
 
   async function toggleExperimentalOtCheckbox(targetEnabled) {
     const checkbox = getPanel()?.querySelector('[data-experimental-ot]');
-    if (!checkbox) {
+    if (!checkbox || otTogglePending) {
       return;
     }
+    const projectId = getCurrentProjectId();
+    otTogglePending = true;
+    try {
     // Explicit target from the click interceptor wins; the keyboard/legacy
     // path (no argument, un-flipped checkbox) falls back to inversion.
     const nextEnabled = typeof targetEnabled === 'boolean' ? targetEnabled : !checkbox.checked;
@@ -200,11 +207,15 @@
     } else {
       closeDiagnosticsMenu();
     }
+    if (projectId !== getCurrentProjectId() || checkbox !== getPanel()?.querySelector('[data-experimental-ot]')) return;
     checkbox.checked = nextEnabled;
     handleExperimentalOtToggleChange({ currentTarget: checkbox });
     if (nextEnabled) {
       showPluginToast(tr('experimentalOtEnabledToast'), { status: 'info' });
     }
+    } finally {
+      otTogglePending = false;
+    }
   }
 
   function handleExperimentalOtToggleChange(event) {
@@ -213,7 +224,9 @@
       return;
     }
     const projectId = getCurrentProjectId();
+    otWarmMirrorState.failureActive = false;
     lastExperimentalOtProjectId = projectId;
+    otStartRetryCount = 0;
     setExperimentalOtEnabledForProject(projectId, checkbox.checked);
     updateExperimentalOtToggleControl(checkbox.checked);
     // Per-card saved feedback, same contract as every other settings card.
@@ -230,7 +243,7 @@
     updateOtStatusDisplay(checkbox.checked ? (currentOtStatus === 'off' ? 'starting' : currentOtStatus) : 'off');
     syncOtWarmMirrorController().catch(error => {
       updateOtStatusDisplay('unavailable');
-      appendPlainLog(tx(`Experimental OT warm mirror unavailable: ${error.message}`, `实验性 OT 预热镜像不可用：${error.message}`));
+      appendPlainLog(tx(`OT warm mirror unavailable: ${error.message}`, `OT 预热镜像不可用：${error.message}`));
     });
     saveStateSoon();
   }
@@ -252,6 +265,7 @@
     otWarmMirrorProjectId = projectId;
     ensureOtWarmMirrorStateProject(projectId);
     if (enabled) {
+      otWarmMirrorState.suspended = false;
       const pause = otWarmMirrorController?.shouldPauseOtWarmMirror?.({ running: Boolean(getCurrentRunView()) }) || { pause: false };
       if (pause.pause) {
         clearOtEventPolling({ clearPatchQueue: true });
@@ -263,9 +277,12 @@
     } else {
       clearOtEventPolling({ clearPatchQueue: true });
     }
-    const response = enabled
-      ? await callPageBridge('startOtObserver', { projectId })
-      : await callPageBridge('stopOtObserver', {});
+    let response;
+    try {
+      response = enabled ? await callPageBridge('startOtObserver', { projectId }) : await callPageBridge('stopOtObserver', {});
+    } catch (error) {
+      response = { ok: false, error: otWarmMirrorController.normalizeFailureCode(error?.code || error?.message, 'ot_bridge_unavailable') };
+    }
     if (!isCurrentOtSync(requestId, projectId) || getCurrentProjectId() !== projectId) {
       if (enabled) {
         await handleStaleOtStartResponse(projectId, requestId);
@@ -282,7 +299,7 @@
     }
     const status = readOtBridgeStatus(response);
     if (!isSuccessfulOtBridgeResponse(response) || status === 'unavailable') {
-      handleFailedOtStart(projectId, requestId);
+      await handleFailedOtStart(projectId, requestId, response);
       return response;
     }
     const pauseAfterStart = otWarmMirrorController?.shouldPauseOtWarmMirror?.({ running: Boolean(getCurrentRunView()) }) || { pause: false };
@@ -290,7 +307,10 @@
       await pauseOtWarmMirror(pauseAfterStart.reason || 'paused');
       return response;
     }
+    if (status === 'starting') recordOtFailure('missing_active_path', 'start');
+    else otWarmMirrorState.failureActive = false;
     updateOtStatusDisplay(status);
+    otStartRetryCount = 0;
     scheduleOtEventPolling(projectId, { immediate: true });
     return response;
   }
@@ -314,25 +334,43 @@
     }
   }
 
-  function handleFailedOtStart(projectId, requestId) {
+  async function handleFailedOtStart(projectId, requestId, response) {
     if (!isCurrentOtSync(requestId, projectId) || getCurrentProjectId() !== projectId) {
       return;
     }
     clearOtEventPolling({ clearPatchQueue: true });
-    setExperimentalOtEnabledForProject(projectId, false);
-    const experimentalOtCheckbox = getPanel()?.querySelector('[data-experimental-ot]');
-    if (experimentalOtCheckbox) {
-      experimentalOtCheckbox.checked = false;
-    }
+    recordOtFailure(readOtBridgeErrorCode(response, 'ot_start_failed'), 'start');
+    otWarmMirrorState.suspended = true;
+    // Observer availability is transient; only an explicit user action may
+    // change the persisted opt-in. A cold editor/bridge must not turn OT off
+    // permanently. failureActive/suspended already prohibit cache reuse.
+    updateExperimentalOtToggleControl(isExperimentalOtEnabledForProject(projectId));
     updateOtStatusDisplay('unavailable');
-    saveStateSoon();
+    try { await callPageBridge('stopOtObserver', { projectId }); } catch (_error) { /* preserve the original failure */ }
+    scheduleOtStartRetry(projectId, requestId);
+  }
+
+  function scheduleOtStartRetry(projectId, requestId) {
+    const retryDelays = [1000, 3000, 6000];
+    const canRetry = () => isCurrentOtSync(requestId, projectId) && getCurrentProjectId() === projectId
+      && isExperimentalOtEnabledForProject(projectId) && !getCurrentRunView();
+    if (!canRetry() || otStartRetryCount >= retryDelays.length) return;
+    // Use the existing owned timer so disabling OT, changing projects and
+    // starting a new observation all cancel pending retries normally.
+    const delayMs = retryDelays[otStartRetryCount++];
+    otWarmMirrorState.pollTimer = window.setTimeout(() => {
+      otWarmMirrorState.pollTimer = null;
+      if (!canRetry()) return;
+      syncOtWarmMirrorController().catch(() => {
+        if (getCurrentProjectId() === projectId && isExperimentalOtEnabledForProject(projectId)) {
+          updateOtStatusDisplay('unavailable');
+        }
+      });
+    }, delayMs);
   }
 
   function readOtBridgeStatus(response) {
-    if (!response || response.ok === false) {
-      return 'unavailable';
-    }
-    return response.getState() || response.status || response.result?.getState() || response.result?.status || 'unavailable';
+    return otWarmMirrorController.readOtBridgeStatus(response);
   }
 
   function ensureOtWarmMirrorStateProject(projectId) {
@@ -341,8 +379,12 @@
     }
     clearOtEventPolling({ clearPatchQueue: true });
     otWarmMirrorState.projectId = projectId;
+    otStartRetryCount = 0;
     otWarmMirrorState.lastPatchAt = 0;
     otWarmMirrorState.lastErrorCode = '';
+    otWarmMirrorState.failureActive = false;
+    otWarmMirrorState.lastFailure = null;
+    otWarmMirrorState.suspended = false;
     otWarmMirrorState.lastStatus = currentOtStatus;
   }
 
@@ -386,7 +428,8 @@
       && otWarmMirrorController?.buildPatchFilesRequest
       && isExperimentalOtEnabledForProject(projectId)
       && otWarmMirrorProjectId === projectId
-      && getCurrentProjectId() === projectId);
+      && getCurrentProjectId() === projectId
+      && !otWarmMirrorState.suspended);
   }
 
   async function pollOtEvents(projectId = otWarmMirrorState.projectId || getCurrentProjectId()) {
@@ -409,11 +452,13 @@
         return { ok: false, skipped: true, reason: 'project_changed' };
       }
       if (!isSuccessfulOtBridgeResponse(statusResponse)) {
-        otWarmMirrorState.lastErrorCode = readOtBridgeErrorCode(statusResponse, 'get_ot_status_failed');
+        recordOtFailure(readOtBridgeErrorCode(statusResponse, 'get_ot_status_failed'), 'observe');
         updateOtStatusDisplay('unavailable');
         return statusResponse;
       }
       const status = readOtBridgeStatus(statusResponse);
+      if (status === 'observing' && otWarmMirrorState.lastFailure?.phase === 'start') Object.assign(otWarmMirrorState, { failureActive: false, lastErrorCode: '', lastFailure: null });
+      if (['unavailable', 'inconsistent'].includes(status)) recordOtFailure(readOtBridgeErrorCode(statusResponse, 'ot_observer_unavailable'), 'observe');
       if (status) {
         updateOtStatusDisplay(status);
       }
@@ -423,7 +468,7 @@
         return { ok: false, skipped: true, reason: 'project_changed' };
       }
       if (!isSuccessfulOtBridgeResponse(drainResponse)) {
-        otWarmMirrorState.lastErrorCode = readOtBridgeErrorCode(drainResponse, 'drain_ot_events_failed');
+        recordOtFailure(readOtBridgeErrorCode(drainResponse, 'drain_ot_events_failed'), 'observe');
         updateOtStatusDisplay('unavailable');
         return drainResponse;
       }
@@ -433,7 +478,8 @@
       }
       return drainResponse;
     } catch (error) {
-      otWarmMirrorState.lastErrorCode = error?.code || error?.message || 'ot_poll_failed';
+      if (!canPollOtWarmMirror(projectId)) return { ok: false, skipped: true, reason: 'project_changed' };
+      recordOtFailure(error?.code || error?.message || 'ot_poll_failed', 'observe');
       updateOtStatusDisplay('unavailable');
       return { ok: false, error };
     } finally {
@@ -444,25 +490,16 @@
   }
 
   function readOtBridgeEvents(response) {
-    if (Array.isArray(response)) {
-      return response;
-    }
-    if (Array.isArray(response?.events)) {
-      return response.events;
-    }
-    if (Array.isArray(response?.result?.events)) {
-      return response.result.events;
-    }
-    return [];
+    return otWarmMirrorController.readOtBridgeEvents(response);
   }
-
   function readOtBridgeErrorCode(response, fallback) {
-    const value = response?.lastErrorCode
-      || response?.reason
-      || response?.error?.code
-      || response?.error
-      || fallback;
-    return typeof value === 'string' ? value : fallback;
+    return otWarmMirrorController.readOtBridgeErrorCode(response, fallback);
+  }
+  function recordOtFailure(code, phase) {
+    code = otWarmMirrorController.normalizeFailureCode(code);
+    otWarmMirrorState.lastErrorCode = code;
+    otWarmMirrorState.failureActive = true;
+    otWarmMirrorState.lastFailure = { code, phase, at: Date.now() };
   }
 
   function queueOtPatchEvents(events, projectId = getCurrentProjectId()) {
@@ -470,7 +507,16 @@
       return;
     }
     ensureOtWarmMirrorStateProject(projectId);
-    otWarmMirrorState.patchQueue.push(...events);
+    const queued = otWarmMirrorController.queuePatchEvents(otWarmMirrorState.patchQueue, events);
+    if (!queued.ok) {
+      recordOtFailure(queued.reason, 'queue');
+      clearOtEventPolling({ clearPatchQueue: true });
+      otWarmMirrorState.suspended = true;
+      updateOtStatusDisplay('inconsistent');
+      void callPageBridge('stopOtObserver', { projectId }).catch(() => {});
+      return;
+    }
+    otWarmMirrorState.patchQueue = queued.queue;
     scheduleOtPatchFlush(projectId);
   }
 
@@ -510,11 +556,18 @@
       return { ok: false, skipped: true, reason: pause.reason || 'paused' };
     }
 
-    const maxBatch = Math.max(1, Number(otWarmMirrorController?.OT_MAX_PATCH_BATCH) || 25);
-    const batch = otWarmMirrorState.patchQueue.splice(0, maxBatch);
+    let batch = otWarmMirrorController.takePatchBatch(otWarmMirrorState.patchQueue);
     if (!batch.length) {
       return { ok: true, skipped: true, reason: 'empty_batch' };
     }
+    const fresh = otWarmMirrorController.queuePatchEvents([], batch);
+    if (!fresh.ok) {
+      recordOtFailure(fresh.reason, 'queue');
+      clearOtEventPolling({ clearPatchQueue: true });
+      updateOtStatusDisplay('inconsistent');
+      return { ok: false, skipped: true, reason: fresh.reason };
+    }
+    batch = fresh.queue;
 
     otWarmMirrorState.flushing = true;
     try {
@@ -530,46 +583,37 @@
       }
 
       const response = await sendBackgroundNative(request);
+      if (!canPollOtWarmMirror(projectId)) return { ok: false, skipped: true, reason: 'project_changed' };
       if (!response?.ok) {
-        otWarmMirrorState.lastErrorCode = response?.error?.code || response?.error?.message || 'mirror_patch_failed';
+        recordOtFailure(response?.error?.code || 'mirror_patch_failed', 'flush');
         updateOtStatusDisplay('inconsistent');
         return response;
       }
 
-      const result = response.result || {};
-      const skippedFiles = Array.isArray(result?.skippedFiles) ? result.skippedFiles : [];
-      const skippedCount = Number.isFinite(Number(result?.skippedCount))
-        ? Number(result.skippedCount)
-        : skippedFiles.length;
-      if (skippedFiles.length || skippedCount > 0) {
-        otWarmMirrorState.lastErrorCode = 'mirror_patch_skipped';
-        updateOtStatusDisplay('inconsistent');
-        return response;
-      }
-      const appliedFiles = Array.isArray(result?.appliedFiles) ? result.appliedFiles : null;
-      const appliedCount = Number.isFinite(Number(result?.appliedCount))
-        ? Number(result.appliedCount)
-        : NaN;
-      if (!appliedFiles || !Number.isFinite(appliedCount) || appliedCount <= 0 || appliedFiles.length !== appliedCount) {
-        otWarmMirrorState.lastErrorCode = 'mirror_patch_invalid_result';
+      const receipt = otWarmMirrorController.validatePatchReceipt(batch, response.result);
+      if (!receipt.ok) {
+        recordOtFailure(receipt.reason, 'flush');
         updateOtStatusDisplay('inconsistent');
         return response;
       }
 
       otWarmMirrorState.lastPatchAt = Date.now();
       otWarmMirrorState.lastErrorCode = '';
-      if (canPollOtWarmMirror(projectId)) {
+      otWarmMirrorState.failureActive = false;
+      if (canPollOtWarmMirror(projectId) && !getCurrentRunView()) {
         updateOtStatusDisplay('observing');
       }
       return response;
     } catch (error) {
-      otWarmMirrorState.lastErrorCode = error?.code || error?.message || 'mirror_patch_failed';
+      if (!canPollOtWarmMirror(projectId)) return { ok: false, skipped: true, reason: 'project_changed' };
+      recordOtFailure(error?.code || 'mirror_patch_failed', 'flush');
       updateOtStatusDisplay('inconsistent');
       return { ok: false, error };
     } finally {
       otWarmMirrorState.flushing = false;
-      if (otWarmMirrorState.patchQueue.length && canPollOtWarmMirror(projectId) && !getCurrentRunView()) {
-        scheduleOtPatchFlush(projectId, { immediate: true });
+      const nextProjectId = otWarmMirrorState.projectId;
+      if (otWarmMirrorState.patchQueue.length && canPollOtWarmMirror(nextProjectId) && !getCurrentRunView()) {
+        scheduleOtPatchFlush(nextProjectId, { immediate: true });
       }
     }
   }
@@ -612,12 +656,13 @@
   }
 
   function updateOtStatusDisplay(status = currentOtStatus) {
-    const normalized = normalizeOtStatus(status);
+    const normalized = otWarmMirrorState.failureActive && status === 'observing' ? 'inconsistent' : normalizeOtStatus(status);
     currentOtStatus = normalized;
     otWarmMirrorState.lastStatus = normalized;
     const statusElement = getPanel()?.querySelector('[data-ot-status]');
     if (statusElement) {
-      const label = formatOtStatusLabel(normalized);
+      const label = formatOtStatusLabel(normalized) + (otWarmMirrorState.failureActive
+        ? ': ' + tr(otWarmMirrorController.getFailureMessageKey(otWarmMirrorState.lastErrorCode)) : '');
       statusElement.textContent = formatOtToggleStatusText(label);
       statusElement.dataset.otStatus = normalized;
       statusElement.title = formatOtToggleStatusText(label);
@@ -781,38 +826,24 @@
   }
 
   async function resolveWarmRunStart(taskContext = {}) {
+    const projectId = getCurrentProjectId();
     const focusFiles = taskContext.focusFiles || [];
     const mode = taskContext.mode || getState()?.mode;
     const mirrorStatus = await getMirrorFreshness();
+    if (getCurrentProjectId() !== projectId) return { useExistingMirror: false, reason: 'project_changed' };
     const otWarmStart = otWarmMirrorController.canUseOtWarmStart({
-      enabled: isExperimentalOtEnabled(),
+      enabled: isExperimentalOtEnabled() && !otWarmMirrorState.failureActive,
       focusFiles,
       mirrorStatus
     });
-    if (otWarmStart.ok) {
-      return {
-        useExistingMirror: true,
-        warmStart: true,
-        otWarmStart: true,
-        reason: 'ot_focus_fresh',
-        mirrorStatus,
-        focusFiles: otWarmStart.focusFiles,
-        project: {
-          capabilities: {
-            fullProjectSnapshot: false,
-            method: 'ot-warm-mirror'
-          },
-          files: []
-        }
-      };
-    }
-    if (!mirrorStatus?.exists || !isMirrorReusable(mirrorStatus)) {
+    if (!mirrorStatus?.exists || (!otWarmStart.ok && !isMirrorReusable(mirrorStatus))) {
       return { useExistingMirror: false, reason: 'mirror_not_fresh', mirrorStatus };
     }
 
     let overlayProject = null;
     try {
       overlayProject = await callPageBridge('getProjectSnapshot', {
+        projectId,
         force: true,
         maxAgeMs: 0,
         preferLightweight: true,
@@ -826,6 +857,7 @@
     } catch (error) {
       return { useExistingMirror: false, reason: 'overlay_probe_failed', mirrorStatus };
     }
+    if (getCurrentProjectId() !== projectId) return { useExistingMirror: false, reason: 'project_changed' };
     const fileOverlays = buildSnapshotFileOverlays(overlayProject, focusFiles);
     if (!fileOverlays.length) {
       return { useExistingMirror: false, reason: 'missing_current_overlay', mirrorStatus };
@@ -840,7 +872,9 @@
     return {
       useExistingMirror: true,
       warmStart: true,
-      reason: mode === 'ask' ? 'warm_whole_project_ask' : 'warm_whole_project',
+      otWarmStart: otWarmStart.ok,
+      focusFiles,
+      reason: otWarmStart.ok ? 'ot_focus_fresh' : mode === 'ask' ? 'warm_whole_project_ask' : 'warm_whole_project',
       mirrorStatus,
       fileOverlays,
       project: overlayProject
@@ -928,7 +962,7 @@
       return syncOtWarmMirrorController();
     }).catch(error => {
       updateOtStatusDisplay('unavailable');
-      appendPlainLog(tx(`Experimental OT warm mirror unavailable: ${error.message}`, `实验性 OT 预热镜像不可用：${error.message}`));
+      appendPlainLog(tx(`OT warm mirror unavailable: ${error.message}`, `OT 预热镜像不可用：${error.message}`));
     });
   }
 

package/extension/src/content/otWarmMirrorController.js

@@ -10,6 +10,12 @@
   const OT_POLL_INTERVAL_MS = 1000;
   const OT_PATCH_DEBOUNCE_MS = 500;
   const OT_MAX_PATCH_BATCH = 25;
+  const OT_FRESHNESS_MAX_AGE_MS = 30000;
+  const OT_MAX_FILE_BYTES = 1024 * 1024;
+  const OT_MAX_PENDING_EVENTS = 64;
+  const OT_MAX_PENDING_BYTES = 4 * 1024 * 1024;
+  const OT_MAX_BATCH_BYTES = 2 * 1024 * 1024;
+  const encoder = typeof TextEncoder === 'function' ? new TextEncoder() : null;
   const PAUSE_STATES = new Set(['running', 'writing', 'undoing', 'compiling']);
 
   function buildPatchFilesRequest({ projectId, events, nativeCompatibility } = {}) {
@@ -67,13 +73,14 @@
     return { pause: false };
   }
 
-  function canUseOtWarmStart({ enabled, focusFiles, mirrorStatus } = {}) {
+  function canUseOtWarmStart({ enabled, focusFiles, mirrorStatus, now = Date.now() } = {}) {
     if (!enabled) {
       return { ok: false, reason: 'disabled' };
     }
     if (!mirrorStatus || mirrorStatus.exists !== true) {
       return { ok: false, reason: 'mirror_missing' };
     }
+    if (mirrorStatus.dirty === true) return { ok: false, reason: 'mirror_dirty' };
 
     const normalizedFocusFiles = normalizePaths(focusFiles);
     if (!normalizedFocusFiles.length) {
@@ -85,6 +92,8 @@
       if (file?.state !== 'fresh') {
         continue;
       }
+      const age = now - Date.parse(file.observedAt ?? file.lastPatchAt ?? '');
+      if (!Number.isFinite(age) || age < 0 || age > OT_FRESHNESS_MAX_AGE_MS) continue;
       const filePath = normalizePath(file.path);
       if (filePath) {
         freshFiles.add(filePath);
@@ -102,6 +111,105 @@
     return { ok: false, reason: 'missing_ot_fresh_focus' };
   }
 
+  function textBytes(value) {
+    const text = String(value || '');
+    return encoder ? encoder.encode(text).byteLength : text.length * 3;
+  }
+
+  function patchBytes(event) { return textBytes(event.nextContent) + textBytes(event.path) + 512; }
+
+  function queuePatchEvents(queue, events, now = Date.now()) {
+    if (!Array.isArray(events) || events.length > OT_MAX_PENDING_EVENTS) return { ok: false, reason: 'ot_queue_limit' };
+    const next = Array.isArray(queue) ? queue.slice() : [];
+    let bytes = next.reduce((sum, event) => sum + patchBytes(event), 0);
+    if (next.length > OT_MAX_PENDING_EVENTS || bytes > OT_MAX_PENDING_BYTES) return { ok: false, reason: 'ot_queue_limit' };
+    for (const input of events) {
+      const path = normalizePath(input?.path);
+      const time = typeof input?.observedAt === 'number' ? input.observedAt : Date.parse(input?.observedAt || '');
+      if (!isSafeRelativePath(path) || path.length > 1024 || typeof input?.nextContent !== 'string' ||
+          typeof input.baseHash !== 'string' || !input.baseHash || input.baseHash.length > 128) {
+        return { ok: false, reason: 'ot_event_invalid' };
+      }
+      if (!Number.isFinite(time) || now - time < 0 || now - time > OT_FRESHNESS_MAX_AGE_MS) return { ok: false, reason: 'ot_event_expired' };
+      if (textBytes(input.nextContent) > OT_MAX_FILE_BYTES) return { ok: false, reason: 'ot_file_limit' };
+      const event = { path, baseHash: input.baseHash, nextContent: input.nextContent,
+        nextHash: typeof input.nextHash === 'string' && input.nextHash.length <= 128 ? input.nextHash : '',
+        observedAt: new Date(time).toISOString() };
+      if (isPrimitiveMetadata(input.observedVersion) && String(input.observedVersion).length <= 128) event.observedVersion = input.observedVersion;
+      const tail = next[next.length - 1];
+      if (tail?.path === path && tail.nextHash && tail.nextHash === event.baseHash) {
+        event.baseHash = tail.baseHash;
+        bytes -= patchBytes(next.pop());
+      }
+      if (event.nextHash !== event.baseHash) { next.push(event); bytes += patchBytes(event); }
+      if (next.length > OT_MAX_PENDING_EVENTS || bytes > OT_MAX_PENDING_BYTES) return { ok: false, reason: 'ot_queue_limit' };
+    }
+    return { ok: true, queue: next, bytes };
+  }
+
+  function takePatchBatch(queue) {
+    let bytes = 0;
+    let count = 0;
+    while (count < Math.min(queue.length, OT_MAX_PATCH_BATCH)) {
+      const size = patchBytes(queue[count]);
+      if (bytes + size > OT_MAX_BATCH_BYTES) break;
+      bytes += size;
+      count += 1;
+    }
+    return queue.splice(0, count);
+  }
+
+  function validatePatchReceipt(events, result = {}, now = Date.now()) {
+    if ((Array.isArray(result.skippedFiles) && result.skippedFiles.length) || Number(result.skippedCount || 0) > 0) {
+      return { ok: false, reason: 'mirror_patch_skipped' };
+    }
+    if (!events.length || Number(result.appliedCount) !== events.length || !Array.isArray(result.appliedFiles) ||
+        result.appliedFiles.length !== events.length || !result.appliedFiles.every((file, index) =>
+          normalizePath(file?.path) === events[index].path && (!events[index].nextHash || file.hash === events[index].nextHash))) {
+      return { ok: false, reason: 'mirror_patch_invalid_result' };
+    }
+    if (events.some(event => { const time = Date.parse(event.observedAt);
+      return !Number.isFinite(time) || time > now || now - time > OT_FRESHNESS_MAX_AGE_MS;
+    })) return { ok: false, reason: 'ot_event_expired' };
+    return { ok: true };
+  }
+
+  function readOtBridgeStatus(response) {
+    if (!response || response.ok === false) return 'unavailable';
+    return response.state || response.status || response.result?.state || response.result?.status || 'unavailable';
+  }
+
+  function readOtBridgeEvents(response) {
+    if (Array.isArray(response)) return response;
+    if (Array.isArray(response?.events)) return response.events;
+    if (Array.isArray(response?.result?.events)) return response.result.events;
+    return [];
+  }
+
+  function readOtBridgeErrorCode(response, fallback) {
+    const value = response?.lastErrorCode || response?.reason || response?.error?.code || response?.error || fallback;
+    return typeof value === 'string' ? value : fallback;
+  }
+
+  function normalizeFailureCode(value, fallback = 'ot_error') {
+    const code = typeof value === 'string' ? value : value?.code;
+    if (/^[a-z][a-z0-9_]{0,79}$/.test(code || '')) return code;
+    if (/page bridge|capability|bridge timed out/i.test(String(code || ''))) return 'ot_bridge_unavailable';
+    return fallback;
+  }
+
+  function getFailureMessageKey(value) {
+    const code = normalizeFailureCode(value);
+    if (/bridge|ot_status|ot_events/.test(code)) return 'otFailureBridge';
+    if (/missing_ot_text|observer_create|observer_unavailable/.test(code)) return 'otFailureObserver';
+    if (code === 'ot_file_limit') return 'otFailureFileLimit';
+    if (code === 'ot_queue_limit') return 'otFailureQueueLimit';
+    if (code === 'ot_event_expired') return 'otFailureExpired';
+    if (/editor|active_path|document/.test(code)) return 'otFailureEditor';
+    if (/mirror|hash|baseline/.test(code)) return 'otFailureMirror';
+    return 'otFailureGeneric';
+  }
+
   function normalizePath(value) {
     return String(value ?? '')
       .trim()
@@ -165,6 +273,19 @@
     OT_POLL_INTERVAL_MS,
     OT_PATCH_DEBOUNCE_MS,
     OT_MAX_PATCH_BATCH,
+    OT_FRESHNESS_MAX_AGE_MS,
+    OT_MAX_FILE_BYTES,
+    OT_MAX_PENDING_EVENTS,
+    OT_MAX_PENDING_BYTES,
+    OT_MAX_BATCH_BYTES,
+    queuePatchEvents,
+    takePatchBatch,
+    validatePatchReceipt,
+    normalizeFailureCode,
+    readOtBridgeStatus,
+    readOtBridgeEvents,
+    readOtBridgeErrorCode,
+    getFailureMessageKey,
     buildPatchFilesRequest,
     canUseOtWarmStart,
     normalizePath,

package/extension/src/content/pageBridgeClient.js

@@ -21,9 +21,11 @@
     ['src/page/overleafProjectSnapshot.js', 'codex-overleaf-project-snapshot-script'],
     ['src/page/pageBridgeCapability.js', 'codex-overleaf-page-bridge-capability-script'],
     ['src/page/treeOperations.js', 'codex-overleaf-tree-operations-script', true],
+    ['src/page/textFileCreator.js', 'codex-overleaf-text-file-creator-script', true],
     ['src/page/binaryAssetUploader.js', 'codex-overleaf-binary-asset-uploader-script', true],
     ['src/page/snapshotRouter.js', 'codex-overleaf-snapshot-router-script'],
     ['src/page/writeGuard.js', 'codex-overleaf-write-guard-script', true],
+    ['src/page/trackedChangeCapture.js', 'codex-overleaf-tracked-change-capture-script', true],
     ['src/page/trackedChangesLifecycle.js', 'codex-overleaf-tracked-changes-lifecycle-script', true],
     ['src/page/writebackRouter.js', 'codex-overleaf-writeback-router-script', true],
     ['src/pageBridge.js', 'codex-overleaf-page-bridge-script', true]