codex-overleaf-link 2.3.6 → 2.4.1

package/extension/src/content/contentRuntime.js

@@ -51,8 +51,7 @@
     'codex.providers.delete',
     'task.run',
     'mirror.sync',
-    'mirror.patchFiles',
-    'mirror.confirmWriteback',
+    'mirror.patchFiles', 'mirror.confirmWriteback', 'mirror.invalidate',
     'mirror.scanSensitive',
     'codex.history.clearPlugin',
     'skills.list',
@@ -583,6 +582,7 @@
     RUN_SNAPSHOT_ZIP_TIMEOUT_MS,
     getState: () => state,
     getCurrentRunView: () => currentRunView,
+    appendRunRecordEvent,
     onMirrorRefreshSettled: runSettlementPersistence.settleMirrorRefresh
   });
   const {
@@ -790,6 +790,7 @@
     },
     saveState,
     saveStateSoon,
+    onProjectFilesReady: refreshHistoricalProjectReferences,
     updateActiveSession,
     callPageBridge,
     getCurrentProjectId,
@@ -1776,9 +1777,7 @@
     return contextTrayController.setContextStatus(text);
   }
 
-  function resetContextProject() {
-    return contextTrayController.resetContextProject();
-  }
+  function resetContextProject() { return contextTrayController.resetContextProject(); }
 
   async function runTask(options = {}) {
     // Barrier on a still-flying background mirror refresh from the previous
@@ -2485,14 +2484,15 @@
       setRunning(false);
       nativeChannel.clearActiveRequest();
       stopRunElapsedTick();
-      if (isExperimentalOtEnabled()) {
-        await resumeOtWarmMirror('run-settled');
-      }
       await flushQueuedSaveState().catch(() => {});
       currentRunView = null;
       runCancellationRequested = false;
       runCancellationController = null;
       activeTurnControl.release(settlement.requestId);
+      if (isExperimentalOtEnabled()) {
+        try { await resumeOtWarmMirror('run-settled'); }
+        catch (_error) { updateOtStatusDisplay('unavailable'); }
+      }
       if (settlement.requestId) {
         activeTurnControl.acknowledge(settlement.requestId).catch(() => {});
       }
@@ -5570,6 +5570,7 @@
           title: session.title || '',
           titleSource: session.titleSource || 'auto',
           focusFiles: session.focusFiles || [],
+          projectReferenceFiles: session.projectReferenceFiles || [],
           codexThreadId: session.codexThreadId || '',
           createdAt: session.createdAt,
           updatedAt: session.updatedAt,
@@ -5665,7 +5666,7 @@
       const urlProjectId = getCurrentProjectId();
       const projectId = projectIdOverride || urlProjectId;
       if (!projectId) {
-        return;
+        if (options?.reviewRunIds?.length) throw new Error('Review persistence lost its project.'); return;
       }
       // Read currentRunView through a defensive accessor so historical test
       // harnesses that inline `saveState` without re-declaring the module-
@@ -5677,7 +5678,7 @@
           'Skipped saveState: run is in flight on a different project than the current URL; settlement owns persistence.',
           '已跳过 saveState：本次运行所属项目与当前 URL 不一致，写回由 settlement 负责。'
         ));
-        return;
+        if (options?.reviewRunIds?.length) throw new Error('Review persistence project changed.'); return;
       }
       const compactState = prepareStateForStorage(state, { onAggressive: notifyAggressiveCompactionOnce });
       compactState.autoRecompile = state.autoRecompile;
@@ -5698,7 +5699,7 @@
         state: stateSnapshot,
         compactState: compactStateSnapshot,
         projectId,
-        deletedSessionIds: options?.deletedSessionIds,
+        deletedSessionIds: options?.deletedSessionIds, reviewRunIds: options?.reviewRunIds,
         Migration,
         StorageDb,
         SessionPersistence: Modules.SessionPersistence,
@@ -5726,7 +5727,7 @@
           persistScopedState
         );
         if (!committed.ok && (
-          options?.queueMutation
+          options?.reviewRunIds?.length || options?.queueMutation
           || options?.queueMutations?.length
           || committed.reason !== 'stale_view'
         )) {
@@ -5738,12 +5739,12 @@
     } catch (error) {
       if (
         error?.code === 'account_scope_unavailable' &&
-        !options?.queueMutation &&
+        !options?.reviewRunIds?.length && !options?.queueMutation &&
         !(Array.isArray(options?.queueMutations) && options.queueMutations.length)
       ) {
         return;
       }
-      if (options?.queueMutation || options?.queueMutations?.length) {
+      if (options?.reviewRunIds?.length || options?.queueMutation || options?.queueMutations?.length) {
         throw error;
       }
       let fallbackError = null;
@@ -5868,6 +5869,7 @@
           // here (e.g. fallback chrome.storage.local.set rethrew).
           emitStorageQuotaFailure(error, null);
         }
+        if (persistenceOptions?.reviewRunIds?.length) throw error;
         appendPlainLog(tx(`Failed to save session state: ${formatStateSaveError(error)}`, `保存会话状态失败：${formatStateSaveError(error)}`));
       })
       .finally(() => {
@@ -5922,6 +5924,7 @@
       ...(current || {}),
       ...incoming,
       queueMutation: undefined,
+      reviewRunIds: Array.from(new Set([...(current?.reviewRunIds || []), ...(incoming?.reviewRunIds || [])])),
       queueMutations,
       deletedSessionIds: Array.from(new Set([
         ...(current?.deletedSessionIds || []),
@@ -5977,15 +5980,7 @@
   }
 
   function getRenderedModelEntries() {
-    return Array.from(panel?.querySelector('[data-model]')?.options || []).map(option => ({
-      id: option.value,
-      label: option.textContent,
-      reasoningEfforts: (option.dataset.reasoningEfforts || '').split(',').filter(Boolean),
-      defaultReasoningEffort: option.dataset.defaultReasoningEffort || '',
-      reasoningPresentation: option.dataset.reasoningPresentation || '',
-      speedTiers: (option.dataset.speedTiers || 'standard').split(',').filter(Boolean),
-      defaultSpeedTier: option.dataset.defaultSpeedTier || 'standard'
-    }));
+    return Modules.ModelPickerSupport.getRenderedModelEntries(panel);
   }
 
   async function selectMode(mode) {
@@ -6123,6 +6118,7 @@
     applySessionLabel();
     renderSessionList();
     renderRunHistory(options);
+    getTrackedChangeCaptureController().schedule();
     renderContextSelection();
     renderContextSummary();
     // v1.8.0 C4: refresh recovery — small attachments persisted in state are
@@ -6212,7 +6208,7 @@
       undoExpectedFiles: [],
       undoStatus: '',
       queueItemId,
-      nativeRequestId: '',
+      nativeRequestId: '', codexThreadId: '',
       codexTurnId: '',
       nativeEventSeq: 0,
       executionSnapshot: executionSnapshot
@@ -6379,7 +6375,7 @@
     currentRunView.activeTurn = { threadId, turnId };
     const record = findRunRecord(currentRunView.recordId, currentRunView.sessionId);
     if (record) {
-      record.codexTurnId = turnId;
+      record.codexThreadId = threadId; record.codexTurnId = turnId;
       record.nativeEventSeq = Math.max(Number(record.nativeEventSeq || 0), Number(journalSeq || 0));
     }
     if (threadId) {
@@ -6753,6 +6749,13 @@
     return files;
   }
 
+  function refreshHistoricalProjectReferences(project) {
+    if (!project?.id || String(project.id) !== getCurrentProjectId()) return;
+    state = updateActiveSession(state, { projectReferenceFiles: captureProjectReferenceFiles(project) });
+    saveStateSoon();
+    if (!currentRunView && !trackedChangeInFlight.size) renderRunHistory({ preserveScroll: true });
+  }
+
   function persistCurrentProjectReferenceFiles(project) {
     const projectFiles = captureProjectReferenceFiles(project);
     if (currentRunView) {
@@ -6884,6 +6887,7 @@
         runProjectId: getRunProjectIdForWriteback(run)
       });
       const undoApplied = isUndoResultEffectivelyApplied(run, result);
+      writebackOrchestrator.invalidateMirrorAfterUndo(runId, getRunProjectIdForWriteback(run), result);
       appendUndoReviewingPolicyEvent(runId, result.reviewingPolicy);
       appendRunRecordEvent(runId, {
         title: tr('undoResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 }),
@@ -6945,48 +6949,54 @@
       detail: { [tr('detailWillUndo')]: trackedUndo ? formatTrackedChangeFiles(run.undoTrackedChanges) : formatTrackedUndoFiles(run) }
     });
 
-    let result;
     try {
-      result = await callPageBridge('rejectTrackedChanges', {
+      const trackedUndoPostFilesAtDispatch = buildTrackedUndoPostFiles(run);
+      const result = await callPageBridge('rejectTrackedChanges', {
         trackedChanges: run.undoTrackedChanges || [],
         expectedFiles: run.undoExpectedFiles || [],
-        postFiles: buildTrackedUndoPostFiles(run),
+        postFiles: trackedUndoPostFilesAtDispatch,
+        untrackedUndo: run.executionSnapshot
+          ? run.executionSnapshot.requireReviewing === false && ['submitted', 'legacy-captured'].includes(run.executionSnapshot.source)
+          : getTrackedChangeCaptureController().hasLegacyUntrackedCheckpoint(run),
         // Welcome-panel + write-guard:
         // bind the reject to the run's original project. If the user has
         // navigated away the page-side guard refuses with
         // `aborted_project_changed` and the document is left untouched.
         runProjectId: getRunProjectIdForWriteback(run)
       });
+      writebackOrchestrator.invalidateMirrorAfterUndo(runId, getRunProjectIdForWriteback(run), result);
+      appendRunRecordEvent(runId, {
+        title: trackedUndo
+          ? tr('undoTrackedResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 })
+          : tr('undoNativeResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 }),
+        status: result.skipped?.length ? 'failed' : 'completed',
+        detail: {
+          [trackedUndo ? tr('detailRejected') : tr('detailUndone')]: (result.applied || []).map(item => ({
+            [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
+            [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key
+          })),
+          [tr('detailSkipped')]: (result.skipped || []).map(item => ({
+            [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
+            [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key || '',
+            [tr('detailReason')]: formatBridgeResultReason(item.result, item.trackedChange?.path)
+          }))
+        }
+      });
+      if (lifecycleReject) {
+        WritebackSettlement.attachUndoNotVerifiedFailure(run, result, {
+          buildFailure: buildContentFailure,
+          postFiles: trackedUndoPostFilesAtDispatch
+        });
+        await applyTrackedChangeSettlement(runId, 'reject', result);
+        return;
+      }
+      applyLegacyUndoSettlement(runId, result.skipped?.length ? 'partial' : 'applied', result);
     } finally {
       if (lifecycleReject) {
         trackedChangeInFlight.delete(runId);
+        refreshRunCardControls(runId);
       }
     }
-    appendRunRecordEvent(runId, {
-      title: trackedUndo
-        ? tr('undoTrackedResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 })
-        : tr('undoNativeResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 }),
-      status: result.skipped?.length ? 'failed' : 'completed',
-      detail: {
-        [trackedUndo ? tr('detailRejected') : tr('detailUndone')]: (result.applied || []).map(item => ({
-          [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
-          [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key
-        })),
-        [tr('detailSkipped')]: (result.skipped || []).map(item => ({
-          [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
-          [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key || '',
-          [tr('detailReason')]: formatBridgeResultReason(item.result, item.trackedChange?.path)
-        }))
-      }
-    });
-    if (lifecycleReject) {
-      WritebackSettlement.attachUndoNotVerifiedFailure(run, result, {
-        buildFailure: buildContentFailure
-      });
-      applyTrackedChangeSettlement(runId, 'reject', result);
-      return;
-    }
-    applyLegacyUndoSettlement(runId, result.skipped?.length ? 'partial' : 'applied', result);
   }
 
   async function acceptRun(runId) {
@@ -7016,50 +7026,50 @@
       detail: { [tr('detailAccepted')]: formatTrackedChangeFiles(run.undoTrackedChanges) }
     });
 
-    let result;
     try {
-      result = await callPageBridge('acceptTrackedChanges', {
+      const result = await callPageBridge('acceptTrackedChanges', {
         trackedChanges: run.undoTrackedChanges || [],
         expectedFiles: run.undoExpectedFiles || [],
         postFiles: buildTrackedUndoPostFiles(run),
         appliedOperations: Array.isArray(run.appliedOperations) ? run.appliedOperations : [],
         runProjectId: getRunProjectIdForWriteback(run)
       });
-    } finally {
-      trackedChangeInFlight.delete(runId);
-    }
-    appendAcceptDiagnosticEvents(runId, Array.isArray(result.diagnostics) ? result.diagnostics : []);
-    appendRunRecordEvent(runId, {
-      title: tr('runAcceptTrackedResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 }),
-      status: result.skipped?.length ? 'failed' : 'completed',
-      detail: {
-        [tr('detailAccepted')]: (result.applied || []).map(item => ({
-          [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
-          [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key
-        })),
-        [tr('detailSkipped')]: (result.skipped || []).map(item => ({
-          [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
-          [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key || '',
-          [tr('detailReason')]: formatBridgeResultReason(item.result, item.trackedChange?.path)
-        }))
-      }
-    });
-    if (result.ok === false) {
+      appendAcceptDiagnosticEvents(runId, Array.isArray(result.diagnostics) ? result.diagnostics : []);
       appendRunRecordEvent(runId, {
-        title: tr('runAcceptTrackedFailed'),
-        status: 'failed',
+        title: tr('runAcceptTrackedResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 }),
+        status: result.skipped?.length ? 'failed' : 'completed',
         detail: {
-          [tr('detailReason')]: tr('runAcceptTrackedFailedReason')
+          [tr('detailAccepted')]: (result.applied || []).map(item => ({
+            [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
+            [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key
+          })),
+          [tr('detailSkipped')]: (result.skipped || []).map(item => ({
+            [tr('detailFile')]: item.trackedChange?.path || tr('unknownFile'),
+            [tr('detailRecord')]: item.trackedChange?.label || item.trackedChange?.id || item.trackedChange?.key || '',
+            [tr('detailReason')]: formatBridgeResultReason(item.result, item.trackedChange?.path)
+          }))
         }
       });
-      if (!WritebackSettlement.isSuccessfulTrackedChangeSettlement(result)) {
-        refreshRunCardControls(runId);
+      if (result.ok === false) {
+        appendRunRecordEvent(runId, {
+          title: tr('runAcceptTrackedFailed'),
+          status: 'failed',
+          detail: {
+            [tr('detailReason')]: tr('runAcceptTrackedFailedReason')
+          }
+        });
+        if (!WritebackSettlement.isSuccessfulTrackedChangeSettlement(result)) {
+          refreshRunCardControls(runId);
+        }
       }
+      WritebackSettlement.attachAcceptNotVerifiedFailure(run, result, {
+        buildFailure: buildContentFailure
+      });
+      await applyTrackedChangeSettlement(runId, 'accept', result);
+    } finally {
+      trackedChangeInFlight.delete(runId);
+      refreshRunCardControls(runId);
     }
-    WritebackSettlement.attachAcceptNotVerifiedFailure(run, result, {
-      buildFailure: buildContentFailure
-    });
-    applyTrackedChangeSettlement(runId, 'accept', result);
   }
 
   function getRunProjectIdForWriteback(run) {
@@ -7103,7 +7113,7 @@
     );
   }
 
-  function applyTrackedChangeSettlement(runId, kind, result) {
+  async function applyTrackedChangeSettlement(runId, kind, result) {
     const run = findRunRecord(runId);
     const settlement = WritebackSettlement.settleTrackedChangeLifecycle({
       kind,
@@ -7112,12 +7122,12 @@
       failureReasons: FailureReasons
     });
     if (settlement.decision === 'blocked') {
-      refreshRunCardControls(runId);
       return;
     }
-    Object.assign(run, WritebackSettlement.applySettlementTransition(run, settlement));
-    saveStateSoon();
-    refreshRunCardControls(runId);
+    await Modules.ScopedPersistenceCoordinator.applyReviewTransition({
+      getState: () => state, runId, transition: WritebackSettlement.applySettlementTransition(run, settlement),
+      persist: flushQueuedSaveState
+    });
   }
 
   function getRunUndoCount(run) {
@@ -7195,6 +7205,25 @@
     return WritebackSettlement.attachVerifiedContentToOperation(operation, result);
   }
 
+  let trackedChangeCaptureController = null;
+  function getTrackedChangeCaptureController() {
+    return trackedChangeCaptureController ||= Modules.TrackedChangeCaptureController.create({
+      getRuns: () => (state.sessions || []).flatMap(session => session.runs || []),
+      getProjectId: () => window.location.pathname.match(/^\/project\/([^/]+)/)?.[1] || '',
+      buildExpectedFilesAfterOperations, normalizeTrackedChanges: normalizeApplyTrackedChanges, callPageBridge,
+      persist: () => flushQueuedSaveState({ preserveRunActionPayload: true }),
+      refresh: run => refreshRunCardControls(run.id),
+      notify: (run, kind, detail) => appendRunRecordEvent(run.id, {
+        title: {
+          pending: tx('Files written; confirming tracked changes.', '文件已写入，正在确认留痕记录。'),
+          observed: tx('Tracked changes confirmed; Accept is available.', '留痕记录已确认，可以接受改动。'),
+          needs_review: tx('Tracked changes could not be safely attributed. Review them in Overleaf; Undo is preserved.', '留痕归属尚未确认，请在 Overleaf 审阅；原有撤销能力已保留。')
+        }[kind], status: 'info', detail
+      }),
+      onError: error => appendPlainLog(tx('Tracked-change confirmation unavailable: ', '留痕确认暂不可用：') + error.message)
+    });
+  }
+
   function recordUndoFromApply(project, applyResult) {
     const appliedEntries = getAppliedEntries(applyResult);
     if (!currentRunView?.recordId || !appliedEntries.length) {
@@ -7238,6 +7267,7 @@
       if (combinedTrackedChanges.length) {
         record.trackedChangeStatus = 'pending';
       }
+      getTrackedChangeCaptureController().record(record, applyResult?.trackedChangeCaptures);
       refreshRunCardControls(record.id);
       if (combinedTrackedChanges.length) {
         appendRunEvent({
@@ -7302,38 +7332,12 @@
     return WritebackSettlement.normalizeApplyTrackedChanges(changes);
   }
 
-  function selectExpectedFilesForTrackedUndo(
-    project,
-    operations = [],
-    trackedChanges = [],
-    previousExpectedFiles = []
-  ) {
-    return WritebackSettlement.selectExpectedFilesForTrackedUndo(
-      project,
-      operations,
-      trackedChanges,
-      previousExpectedFiles
-    );
+  function selectExpectedFilesForTrackedUndo(project, operations = [], trackedChanges = [], previousExpectedFiles = []) {
+    return WritebackSettlement.selectExpectedFilesForTrackedUndo(project, operations, trackedChanges, previousExpectedFiles);
   }
 
   function buildTrackedUndoPostFiles(run) {
-    const expectedFiles = Array.isArray(run?.undoExpectedFiles) ? run.undoExpectedFiles : [];
-    const appliedOperations = Array.isArray(run?.appliedOperations) ? run.appliedOperations : [];
-    if (!expectedFiles.length || !appliedOperations.length) {
-      return [];
-    }
-
-    const postFilesByPath = buildExpectedFilesAfterOperations(
-      { files: expectedFiles },
-      appliedOperations
-    );
-    const expectedPaths = new Set(expectedFiles.map(file => file?.path).filter(Boolean));
-    return Array.from(postFilesByPath.entries())
-      .filter(([path, content]) => expectedPaths.has(path) && typeof content === 'string')
-      .map(([path, content]) => ({
-        path,
-        content
-      }));
+    return getTrackedChangeCaptureController().buildPostFiles(run);
   }
 
   function hasTrackedEditorUndo(run) {

package/extension/src/content/contextTray.js

@@ -22,6 +22,7 @@
     setState = () => {},
     saveState = null,
     saveStateSoon = () => {},
+    onProjectFilesReady = () => {},
     updateActiveSession = defaultUpdateActiveSession,
     callPageBridge = () => Promise.resolve({ ok: false }),
     getCurrentProjectId = () => '',
@@ -201,6 +202,7 @@
         renderContextFiles(contextProject);
         if (isExactContextFileListProject(contextProject)) {
           setContextSyncState('exact-ready');
+          onProjectFilesReady(contextProject);
         } else if (contextSyncState !== 'partial') {
           setContextSyncState('exact-loading');
           void enhanceContextFilesFromExactSnapshot({ loadId: contextLoadId });
@@ -224,6 +226,7 @@
         contextProject = project;
         setContextSyncState(isExactContextFileListProject(project) ? 'exact-ready' : 'exact-loading');
         renderContextFiles(project);
+        if (isExactContextFileListProject(project)) onProjectFilesReady(project);
         if (!isExactContextFileListProject(project)) {
           void enhanceContextFilesFromExactSnapshot({
             force: Boolean(options.force),
@@ -292,6 +295,7 @@
         contextProject = project;
         setContextSyncState('exact-ready');
         renderContextFiles(project);
+        onProjectFilesReady(project);
       } catch (_error) {
         // The page file tree remains usable when the optional exact ZIP list is unavailable.
         if (loadId === contextLoadId) {

package/extension/src/content/diagnosticsController.js

@@ -641,6 +641,10 @@
         lines.push(`CodeMirror: docLength=${view.docLength || 0}; dispatch=${Boolean(view.hasDispatch)}; source=${view.source || 'unknown'}`);
       }
     }
+    const capture = probe?.trackedChangeCapture;
+    if (capture) lines.push(tx('Tracked ledger: ', '留痕记录：')
+      + 'source=' + capture.source + '; ready=' + capture.ready + '; count=' + capture.count
+      + '; doc=' + (capture.docId || 'none') + '; adapter=' + capture.adapter + '; reason=' + (capture.reason || 'none'));
     const projectDiagnostics = probe?.projectDiagnostics;
     if (projectDiagnostics) {
       lines.push(`Project records: ${projectDiagnostics.docRecordCount || 0}; roots=${(projectDiagnostics.internalRootKeys || []).slice(0, 6).join(', ') || 'none'}`);

package/extension/src/content/diagnosticsPanel.js

@@ -10,7 +10,8 @@
       container,
       callbacks: options.callbacks || {},
       i18n: options.i18n || {},
-      dismissInstalled: false
+      dismissInstalled: false,
+      cleanup: []
     };
 
     container.innerHTML = `
@@ -99,6 +100,11 @@
       instance.callbacks.onBeforeOpen?.();
     }
     popover.hidden = !open;
+    if (open) {
+      openFloating(instance, popover, 300);
+    } else {
+      hideFloating(popover);
+    }
     button.dataset.active = open ? 'true' : 'false';
     button.setAttribute('aria-expanded', open ? 'true' : 'false');
   }
@@ -110,7 +116,7 @@
     if (!popover || !button) {
       return;
     }
-    popover.hidden = true;
+    hideFloating(popover);
     button.dataset.active = 'false';
     button.setAttribute('aria-expanded', 'false');
   }
@@ -119,7 +125,7 @@
     const instance = target?._instance || target;
     const result = instance?.container?.querySelector('[data-diagnostics-result]');
     if (result) {
-      result.hidden = true;
+      hideFloating(result);
     }
   }
 
@@ -181,6 +187,73 @@
     details.open = false;
     details.hidden = !technicalText;
     technical.textContent = technicalText;
+    closeMenu(instance);
+    openFloating(instance, root, 560);
+  }
+
+  // Keep DOM ownership (theme, locale and callbacks), but render above clipping
+  // ancestors where the browser supports the top layer. Fixed positioning is
+  // the viewport-based fallback for browsers without the Popover API.
+  function openFloating(instance, element, preferredWidth) {
+    if (element.isConnected === false) return;
+    element.hidden = false;
+    if (typeof element.showPopover === 'function') {
+      element.setAttribute('popover', 'manual');
+      try {
+        if (!element.matches(':popover-open')) element.showPopover();
+      } catch (_error) {
+        element.removeAttribute('popover');
+      }
+    }
+    positionFloating(instance, element, preferredWidth);
+  }
+
+  function hideFloating(element) {
+    if (!element) return;
+    if (typeof element.hidePopover === 'function' && element.getAttribute('popover') === 'manual') {
+      try {
+        if (element.matches(':popover-open')) element.hidePopover();
+      } catch (_error) {
+        element.removeAttribute('popover');
+      }
+    }
+    element.hidden = true;
+  }
+
+  function positionFloating(instance, element, preferredWidth) {
+    if (!element || element.hidden) return;
+    const button = instance.container.querySelector('[data-diagnostics-menu]');
+    if (!button?.getBoundingClientRect || !element.getBoundingClientRect) return;
+    if (button.getClientRects && !button.getClientRects().length) {
+      closeMenu(instance);
+      closeResult(instance);
+      return;
+    }
+    const doc = instance.container.ownerDocument || document;
+    const view = doc.defaultView || window;
+    const viewport = view.visualViewport;
+    const width = viewport?.width || view.innerWidth || doc.documentElement?.clientWidth;
+    const height = viewport?.height || view.innerHeight || doc.documentElement?.clientHeight;
+    if (!(width > 0 && height > 0)) return;
+    const margin = 12;
+    const gap = 8;
+    const leftEdge = (viewport?.offsetLeft || 0) + margin;
+    const topEdge = (viewport?.offsetTop || 0) + margin;
+    const rightEdge = leftEdge + Math.max(0, width - margin * 2);
+    const bottomEdge = topEdge + Math.max(0, height - margin * 2);
+    element.style.width = `${Math.min(preferredWidth, Math.max(0, width - margin * 2))}px`;
+    element.style.maxHeight = `${Math.min(640, Math.max(0, height - margin * 2))}px`;
+    const anchor = button.getBoundingClientRect();
+    const bounds = element.getBoundingClientRect();
+    const below = Math.max(0, bottomEdge - anchor.bottom - gap);
+    const above = Math.max(0, anchor.top - topEdge - gap);
+    const desiredTop = bounds.height > below && above > below
+      ? anchor.top - gap - bounds.height
+      : anchor.bottom + gap;
+    element.style.left = `${Math.max(leftEdge, Math.min(anchor.right - bounds.width, rightEdge - bounds.width))}px`;
+    element.style.top = `${Math.max(topEdge, Math.min(desiredTop, bottomEdge - bounds.height))}px`;
+    element.style.right = 'auto';
+    element.style.bottom = 'auto';
   }
 
   function renderInstallCommand(instance, container, command) {
@@ -272,13 +345,60 @@
       return;
     }
     instance.dismissInstalled = true;
-    document.addEventListener('click', event => {
+    const doc = instance.container.ownerDocument || document;
+    const view = doc.defaultView || window;
+    const listen = (target, type, handler, options) => {
+      if (!target?.addEventListener) return;
+      target.addEventListener(type, handler, options);
+      instance.cleanup.push(() => target.removeEventListener(type, handler, options));
+    };
+    listen(doc, 'click', event => {
       const wrap = instance.container?.querySelector('.codex-diagnostics-wrap');
       if (!wrap || wrap.contains(event.target)) {
         return;
       }
       closeMenu(instance);
     }, true);
+    listen(doc, 'keydown', event => {
+      if (event.key !== 'Escape') return;
+      const menu = instance.container.querySelector('[data-diagnostics-popover]');
+      const result = instance.container.querySelector('[data-diagnostics-result]');
+      if (menu && !menu.hidden) closeMenu(instance);
+      else if (result && !result.hidden) closeResult(instance);
+      else return;
+      event.preventDefault();
+      event.stopPropagation();
+      instance.container.querySelector('[data-diagnostics-menu]')?.focus();
+    }, true);
+    let frame = null;
+    const reposition = () => {
+      frame = null;
+      positionFloating(instance, instance.container.querySelector('[data-diagnostics-popover]'), 300);
+      positionFloating(instance, instance.container.querySelector('[data-diagnostics-result]'), 560);
+    };
+    const schedule = () => {
+      if (frame !== null) return;
+      if (view.requestAnimationFrame) frame = view.requestAnimationFrame(reposition);
+      else reposition();
+    };
+    listen(view, 'resize', schedule);
+    listen(doc, 'scroll', schedule, true);
+    listen(view.visualViewport, 'resize', schedule);
+    listen(view.visualViewport, 'scroll', schedule);
+    if (typeof view.ResizeObserver === 'function') {
+      const observer = new view.ResizeObserver(schedule);
+      for (const node of [
+        instance.container.closest('#codex-overleaf-panel') || instance.container,
+        instance.container.querySelector('[data-diagnostics-popover]'),
+        instance.container.querySelector('[data-diagnostics-result]')
+      ]) {
+        if (node) observer.observe(node);
+      }
+      instance.cleanup.push(() => observer.disconnect());
+    }
+    instance.cleanup.push(() => {
+      if (frame !== null) view.cancelAnimationFrame?.(frame);
+    });
   }
 
   // Drive the trigger's health dot. `health` is one of ok / warn / fail /
@@ -450,6 +570,10 @@
   }
 
   function destroy(instance) {
+    closeMenu(instance);
+    closeResult(instance);
+    for (const cleanup of instance.cleanup || []) cleanup();
+    instance.cleanup = [];
     instance.container.textContent = '';
   }