@in-the-loop-labs/pair-review 1.6.2 → 2.0.1

package/public/js/pr.js

@@ -13,19 +13,6 @@ const STALE_TIMEOUT = 2000;
 
 class PRManager {
   // Forward static constants from modules for backward compatibility
-  static get CATEGORY_EMOJI_MAP() {
-    return window.SuggestionManager?.CATEGORY_EMOJI_MAP || {
-      'bug': '\u{1F41B}',
-      'performance': '\u{26A1}',
-      'design': '\u{1F4D0}',
-      'code-style': '\u{1F9F9}',
-      'improvement': '\u{1F4A1}',
-      'praise': '\u{2B50}',
-      'security': '\u{1F512}',
-      'suggestion': '\u{1F4AC}'
-    };
-  }
-
   static get FOLD_UP_ICON() {
     return window.HunkParser?.FOLD_UP_ICON || '';
   }
@@ -131,14 +118,23 @@ class PRManager {
     this.collapsedFiles = new Set();
     // File viewed state - tracks which files are marked as viewed
     this.viewedFiles = new Set();
+    // Context files - pinned non-diff file ranges
+    this.contextFiles = [];
     // Canonical file order - sorted file paths for consistent ordering across components
     this.canonicalFileOrder = new Map();
+    // Raw per-file patch text for chat context enrichment
+    this.filePatches = new Map();
     // Analysis history manager - for switching between analysis runs
     this.analysisHistoryManager = null;
     // Currently selected analysis run ID (null = latest)
     this.selectedRunId = null;
     // Keyboard shortcuts manager
     this.keyboardShortcuts = null;
+    // Unique client ID for self-echo suppression on SSE review events.
+    // Sent as X-Client-Id header on mutation requests; the server echoes
+    // it back in the SSE broadcast so this tab can skip its own events.
+    this._clientId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+    this._installFetchInterceptor();
 
     // Initialize modules
     this.lineTracker = new window.LineTracker();
@@ -184,6 +180,48 @@ class PRManager {
     }
   }
 
+  /**
+   * Install a global fetch interceptor that adds X-Client-Id to all
+   * mutation requests (POST/PUT/DELETE) targeting the review API.
+   * This is the SINGLE SOURCE of X-Client-Id injection — no individual
+   * fetch call site should manually set this header.
+   * This ensures that even direct fetch() calls (e.g. from page.evaluate
+   * in tests, or any code that bypasses PRManager methods) carry the
+   * client ID so the server can tag the SSE broadcast for self-echo
+   * suppression.
+   */
+  _installFetchInterceptor() {
+    if (window._prFetchIntercepted) return;
+    window._prFetchIntercepted = true;
+
+    const originalFetch = window.fetch;
+    const prManager = this;
+
+    window.fetch = function(input, init) {
+      const url = typeof input === 'string' ? input : input?.url || '';
+      const method = (init?.method || 'GET').toUpperCase();
+
+      // Only intercept mutations to the reviews API
+      if ((method === 'POST' || method === 'PUT' || method === 'DELETE') &&
+          url.includes('/api/reviews/') && prManager._clientId) {
+        init = init || {};
+        // Merge X-Client-Id into existing headers
+        if (init.headers instanceof Headers) {
+          if (!init.headers.has('X-Client-Id')) {
+            init.headers.set('X-Client-Id', prManager._clientId);
+          }
+        } else if (typeof init.headers === 'object' && init.headers !== null) {
+          if (!init.headers['X-Client-Id']) {
+            init.headers['X-Client-Id'] = prManager._clientId;
+          }
+        } else {
+          init.headers = { 'X-Client-Id': prManager._clientId };
+        }
+      }
+      return originalFetch.call(this, input, init);
+    };
+  }
+
   /**
    * Set up event handlers
    */
@@ -408,8 +446,8 @@ class PRManager {
       // Check if AI analysis is currently running
       await this.checkRunningAnalysis();
 
-      // Listen for externally-imported analysis results via SSE
-      this.startExternalResultsListener();
+      // Listen for review mutation events via multiplexed SSE
+      this._initReviewEventListeners();
 
     } catch (error) {
       console.error('Error loading PR:', error);
@@ -420,39 +458,112 @@ class PRManager {
   }
 
   /**
-   * Listen for externally-imported analysis results via SSE.
-   * When POST /api/analysis-results stores new suggestions for this review,
-   * it broadcasts on `review-${reviewId}`. This listener picks that up
-   * and refreshes suggestions automatically.
+   * Listen for review-scoped CustomEvents dispatched by ChatPanel's
+   * multiplexed SSE connection. Replaces the old per-review EventSource.
    */
-  startExternalResultsListener() {
-    if (this._externalResultsSource) return;
-    const reviewId = this.currentPR?.id;
-    if (!reviewId) return;
+  _initReviewEventListeners() {
+    if (this._reviewEventsBound) return;
+    this._reviewEventsBound = true;
 
-    this._externalResultsSource = new EventSource(
-      `/api/pr/review-${reviewId}/ai-suggestions/status`
-    );
+    // Eagerly connect chat SSE so review events flow even before chat opens
+    window.chatPanel?._ensureGlobalSSE();
 
-    this._externalResultsSource.onmessage = (event) => {
-      try {
-        const data = JSON.parse(event.data);
-        if (data.type === 'progress' && data.status === 'completed' && data.source === 'external') {
-          console.log('External analysis results detected, refreshing suggestions');
-          if (this.analysisHistoryManager) {
-            this.analysisHistoryManager.refresh({ switchToNew: true })
-              .then(() => this.loadAISuggestions());
-          } else {
-            this.loadAISuggestions();
-          }
-        }
-      } catch (e) { /* ignore parse errors */ }
+    // Late-bind reviewId to ChatPanel if it was auto-opened by PanelGroup
+    // before prManager was ready (DOMContentLoaded race condition)
+    if (this.currentPR?.id) {
+      window.chatPanel?._lateBindReview(this.currentPR.id).catch(err => console.warn('[ChatPanel] Late-bind failed:', err));
+    }
+
+    // Dirty flags for stale-tab recovery
+    this._dirtyComments = false;
+    this._dirtySuggestions = false;
+    this._dirtyAnalysis = false;
+    this._dirtyAnalysisStarted = false;
+    this._dirtyContextFiles = false;
+
+    // Simple debounce helper
+    const timers = {};
+    const debounced = (key, fn, ms = 300) => {
+      clearTimeout(timers[key]);
+      timers[key] = setTimeout(fn, ms);
     };
 
-    window.addEventListener('beforeunload', () => {
-      if (this._externalResultsSource) {
-        this._externalResultsSource.close();
-        this._externalResultsSource = null;
+    const reviewId = () => this.currentPR?.id;
+
+    document.addEventListener('review:comments_changed', (e) => {
+      if (e.detail?.reviewId !== reviewId()) return;
+      // Suppress self-echo: if this tab originated the mutation, skip reload
+      if (e.detail?.sourceClientId === this._clientId) return;
+      if (document.hidden) { this._dirtyComments = true; return; }
+      debounced('comments', () => this.loadUserComments());
+    });
+
+    document.addEventListener('review:suggestions_changed', (e) => {
+      if (e.detail?.reviewId !== reviewId()) return;
+      // Suppress self-echo for suggestion mutations too
+      if (e.detail?.sourceClientId === this._clientId) return;
+      if (document.hidden) { this._dirtySuggestions = true; return; }
+      debounced('suggestions', () => this.loadAISuggestions());
+    });
+
+    document.addEventListener('review:analysis_started', (e) => {
+      if (e.detail?.reviewId !== reviewId()) return;
+      if (document.hidden) { this._dirtyAnalysisStarted = true; return; }
+      debounced('analysisStarted', () => this.checkRunningAnalysis());
+    });
+
+    document.addEventListener('review:analysis_completed', (e) => {
+      if (e.detail?.reviewId !== reviewId()) return;
+      if (document.hidden) { this._dirtyAnalysis = true; return; }
+      debounced('analysis', () => {
+        if (this.analysisHistoryManager) {
+          this.analysisHistoryManager.refresh({ switchToNew: true })
+            .then(() => this.loadAISuggestions());
+        } else {
+          this.loadAISuggestions();
+        }
+      });
+    });
+
+    document.addEventListener('review:context_files_changed', (e) => {
+      if (e.detail?.reviewId !== reviewId()) return;
+      if (e.detail?.sourceClientId === this._clientId) return;
+      if (document.hidden) { this._dirtyContextFiles = true; return; }
+      debounced('contextFiles', () => this.loadContextFiles());
+    });
+
+    document.addEventListener('review:expand_hunk', async (e) => {
+      if (e.detail?.reviewId !== reviewId()) return;
+      const { file, line_start, line_end, side } = e.detail;
+      await this.ensureLinesVisible([{ file, line_start, line_end, side: side || 'right' }]);
+    });
+
+    document.addEventListener('visibilitychange', () => {
+      if (document.hidden) return;
+      if (this._dirtyComments) { this._dirtyComments = false; this.loadUserComments(); }
+      if (this._dirtyAnalysisStarted) {
+        this._dirtyAnalysisStarted = false;
+        // Skip if analysis already completed while hidden — the completed handler below will refresh everything
+        if (!this._dirtyAnalysis) {
+          this.checkRunningAnalysis();
+        }
+      }
+      if (this._dirtyAnalysis) {
+        this._dirtyAnalysis = false;
+        this._dirtySuggestions = false; // analysis refresh includes suggestion reload
+        if (this.analysisHistoryManager) {
+          this.analysisHistoryManager.refresh({ switchToNew: true })
+            .then(() => this.loadAISuggestions());
+        } else {
+          this.loadAISuggestions();
+        }
+      } else if (this._dirtySuggestions) {
+        this._dirtySuggestions = false;
+        this.loadAISuggestions();
+      }
+      if (this._dirtyContextFiles) {
+        this._dirtyContextFiles = false;
+        this.loadContextFiles();
       }
     });
   }
@@ -485,6 +596,7 @@ class PRManager {
 
         // Parse the unified diff to extract per-file patches
         const filePatchMap = this.parseUnifiedDiff(fullDiff);
+        this.filePatches = filePatchMap;
 
         // Merge patch data into file objects
         const filesWithPatches = files.map(file => ({
@@ -779,6 +891,10 @@ class PRManager {
     } else {
       diffContainer.innerHTML = '<div class="no-diff">No files changed</div>';
     }
+
+    // Load context files after diff is rendered
+    this.contextFiles = [];
+    this.loadContextFiles();
   }
 
   /**
@@ -855,6 +971,26 @@ class PRManager {
 
       // Store reference for updating icon state later
       fileCommentsZone.headerButton = fileCommentBtn;
+
+      // Add file chat button to header
+      const fileChatBtn = document.createElement('button');
+      fileChatBtn.className = 'file-header-chat-btn';
+      fileChatBtn.title = 'Chat about file';
+      fileChatBtn.dataset.file = file.file;
+      fileChatBtn.innerHTML = `
+        <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+          <path d="M1.75 1h8.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 10.25 10H7.061l-2.574 2.573A1.458 1.458 0 0 1 2 11.543V10h-.25A1.75 1.75 0 0 1 0 8.25v-5.5C0 1.784.784 1 1.75 1ZM1.5 2.75v5.5c0 .138.112.25.25.25h1a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h3.5a.25.25 0 0 0 .25-.25v-5.5a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13 2a.25.25 0 0 0-.25-.25h-.5a.75.75 0 0 1 0-1.5h.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 14.25 12H14v1.543a1.458 1.458 0 0 1-2.487 1.03L9.22 12.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.22 2.22v-2.19a.75.75 0 0 1 .75-.75h1a.25.25 0 0 0 .25-.25Z"/>
+        </svg>
+      `;
+      fileChatBtn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        if (window.chatPanel) {
+          window.chatPanel.open({
+            fileContext: { file: file.file }
+          });
+        }
+      });
+      header.appendChild(fileChatBtn);
     }
 
     // Create diff table
@@ -1077,6 +1213,30 @@ class PRManager {
           this.showCommentForm(row, lineNumber, file, diffPosition, null, side);
         }
       },
+      onChatButtonClick: (_e, row, lineNumber, file, lineData) => {
+        if (!window.chatPanel) return;
+        let startLine = lineNumber;
+        let endLine = null;
+
+        if (this.lineTracker.hasActiveSelection() &&
+            this.lineTracker.rangeSelectionStart.fileName === file) {
+          const range = this.lineTracker.getSelectionRange();
+          startLine = range.start;
+          endLine = range.end;
+          this.lineTracker.clearRangeSelection();
+        }
+
+        window.chatPanel.open({
+          commentContext: {
+            type: 'line',
+            body: null,
+            file: file || '',
+            line_start: startLine,
+            line_end: endLine || startLine,
+            source: 'user'
+          }
+        });
+      },
       onMouseOver: (_e, row, lineNumber, file) => {
         // Check if we have a potential drag start and convert it to an actual drag
         if (this.lineTracker.potentialDragStart && !this.lineTracker.isDraggingRange) {
@@ -1091,6 +1251,7 @@ class PRManager {
       onMouseUp: (_e, row, lineNumber, file) => {
         if (this.lineTracker.potentialDragStart) {
           const start = this.lineTracker.potentialDragStart;
+          const isChat = start.isChat;
           this.lineTracker.potentialDragStart = null;
 
           if (start.lineNumber !== lineNumber || start.fileName !== file) {
@@ -1100,6 +1261,24 @@ class PRManager {
               this.lineTracker.startDragSelection(start.row, start.lineNumber, start.fileName, start.side);
             }
             this.lineTracker.completeDragSelection(row, lineNumber, file);
+
+            // For chat drags, immediately open chat with the selected range
+            if (isChat && this.lineTracker.hasActiveSelection()) {
+              const range = this.lineTracker.getSelectionRange();
+              this.lineTracker.clearRangeSelection();
+              if (window.chatPanel) {
+                window.chatPanel.open({
+                  commentContext: {
+                    type: 'line',
+                    body: null,
+                    file: file || '',
+                    line_start: range.start,
+                    line_end: range.end,
+                    source: 'user'
+                  }
+                });
+              }
+            }
           }
         } else if (this.lineTracker.isDraggingRange) {
           this.lineTracker.completeDragSelection(row, lineNumber, file);
@@ -1249,11 +1428,11 @@ class PRManager {
    * @returns {Promise<{lines: string[]}|null>} File content with lines array, or null on error
    */
   async fetchFileContent(fileName) {
-    if (!this.currentPR) return null;
+    const reviewId = this.currentPR?.id;
+    if (!reviewId) return null;
 
-    const { owner, repo, number } = this.currentPR;
     const response = await fetch(
-      `/api/file-content-original/${encodeURIComponent(fileName)}?owner=${owner}&repo=${repo}&number=${number}`
+      `/api/reviews/${reviewId}/file-content/${encodeURIComponent(fileName)}`
     );
     const data = await response.json();
 
@@ -1706,6 +1885,40 @@ class PRManager {
     return true;
   }
 
+  /**
+   * Ensure that the given line ranges are visible in the diff view.
+   * For each item, checks if the target line rows exist in the DOM; if not,
+   * calls expandForSuggestion() to expand the gap containing those lines.
+   * @param {Array<{file: string, line_start: number, line_end: number, side: string}>} items
+   */
+  async ensureLinesVisible(items) {
+    for (const item of items) {
+      const { file, line_start, line_end, side } = item;
+      const resolvedSide = (side || 'right').toUpperCase();
+
+      const fileElement = this.findFileElement(file);
+      if (!fileElement) continue;
+
+      // Check if any line in the range is already visible
+      let anyLineVisible = false;
+      const lineRows = fileElement.querySelectorAll('tr');
+      for (let checkLine = line_start; checkLine <= (line_end || line_start); checkLine++) {
+        for (const row of lineRows) {
+          const lineNum = this.getLineNumber(row, resolvedSide);
+          if (lineNum === checkLine) {
+            anyLineVisible = true;
+            break;
+          }
+        }
+        if (anyLineVisible) break;
+      }
+
+      if (!anyLineVisible) {
+        await this.expandForSuggestion(file, line_start, line_end || line_start, resolvedSide);
+      }
+    }
+  }
+
   /**
    * Line range selection methods - delegate to LineTracker
    */
@@ -1791,7 +2004,7 @@ class PRManager {
       let currentText = bodyDiv.dataset.originalMarkdown || '';
 
       if (!currentText) {
-        const response = await fetch(`/api/user-comment/${commentId}`);
+        const response = await fetch(`/api/reviews/${this.currentPR.id}/comments/${commentId}`);
         if (response.ok) {
           const data = await response.json();
           currentText = data.body || bodyDiv.textContent.trim();
@@ -1894,7 +2107,7 @@ class PRManager {
         return;
       }
 
-      const response = await fetch(`/api/user-comment/${commentId}`, {
+      const response = await fetch(`/api/reviews/${this.currentPR.id}/comments/${commentId}`, {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ body: editedText })
@@ -1920,9 +2133,6 @@ class PRManager {
       if (editFormEl) editFormEl.remove();
       commentDiv.classList.remove('editing-mode');
 
-      const timestamp = commentDiv.querySelector('.user-comment-timestamp');
-      if (timestamp) timestamp.textContent = new Date().toLocaleString();
-
       // Notify AI Panel about the updated comment body
       if (window.aiPanel?.updateComment) {
         window.aiPanel.updateComment(commentId, { body: editedText });
@@ -1953,11 +2163,6 @@ class PRManager {
     bodyDiv.style.display = '';
     if (editForm) editForm.remove();
     commentDiv.classList.remove('editing-mode');
-
-    const timestamp = commentDiv.querySelector('.user-comment-timestamp');
-    if (timestamp && timestamp.textContent === 'Editing comment...') {
-      timestamp.textContent = 'Draft';
-    }
   }
 
   /**
@@ -1970,7 +2175,9 @@ class PRManager {
    */
   async deleteUserComment(commentId) {
     try {
-      const response = await fetch(`/api/user-comment/${commentId}`, { method: 'DELETE' });
+      const response = await fetch(`/api/reviews/${this.currentPR.id}/comments/${commentId}`, {
+        method: 'DELETE'
+      });
       if (!response.ok) throw new Error('Failed to delete comment');
 
       const apiResult = await response.json();
@@ -2029,7 +2236,9 @@ class PRManager {
    */
   async restoreUserComment(commentId) {
     try {
-      const response = await fetch(`/api/user-comment/${commentId}/restore`, { method: 'PUT' });
+      const response = await fetch(`/api/reviews/${this.currentPR.id}/comments/${commentId}/restore`, {
+        method: 'PUT'
+      });
       if (!response.ok) throw new Error('Failed to restore comment');
 
       // Reload comments to update both the diff view and AI panel
@@ -2091,7 +2300,7 @@ class PRManager {
     if (dialogResult !== 'confirm') return;
 
     try {
-      const response = await fetch(`/api/pr/${this.currentPR.owner}/${this.currentPR.repo}/${this.currentPR.number}/user-comments`, {
+      const response = await fetch(`/api/reviews/${this.currentPR.id}/comments`, {
         method: 'DELETE'
       });
 
@@ -2156,7 +2365,7 @@ class PRManager {
 
     try {
       const queryParam = includeDismissed ? '?includeDismissed=true' : '';
-      const response = await fetch(`/api/pr/${this.currentPR.owner}/${this.currentPR.repo}/${this.currentPR.number}/user-comments${queryParam}`);
+      const response = await fetch(`/api/reviews/${this.currentPR.id}/comments${queryParam}`);
       if (!response.ok) return;
 
       const data = await response.json();
@@ -2185,6 +2394,16 @@ class PRManager {
       // Clear existing comment rows before re-rendering
       document.querySelectorAll('.user-comment-row').forEach(row => row.remove());
 
+      // Before rendering, ensure all comment target lines are visible
+      // (expand hidden hunks so the line rows exist in the DOM)
+      const lineItems = lineLevelComments.map(c => ({
+        file: c.file,
+        line_start: c.line_start,
+        line_end: c.line_start,
+        side: c.side || 'RIGHT'
+      }));
+      await this.ensureLinesVisible(lineItems);
+
       // Display line-level comments inline with diff (only active comments reach here)
       lineLevelComments.forEach(comment => {
         const fileElement = this.findFileElement(comment.file);
@@ -2243,7 +2462,8 @@ class PRManager {
       // First, check if analysis has been run for this PR and get summary for the selected run
       let analysisHasRun = false;
       try {
-        let checkUrl = `/api/pr/${owner}/${repo}/${number}/has-ai-suggestions`;
+        const id = this.currentPR.id;
+        let checkUrl = `/api/reviews/${id}/suggestions/check`;
         if (filterRunId) {
           checkUrl += `?runId=${filterRunId}`;
         }
@@ -2270,7 +2490,7 @@ class PRManager {
         window.aiPanel.setAnalysisState(analysisHasRun ? 'complete' : 'unknown');
       }
 
-      let url = `/api/pr/${owner}/${repo}/${number}/ai-suggestions?levels=${filterLevel}`;
+      let url = `/api/reviews/${this.currentPR.id}/suggestions?levels=${filterLevel}`;
       if (filterRunId) {
         url += `&runId=${filterRunId}`;
       }
@@ -2313,10 +2533,6 @@ class PRManager {
     return this.suggestionManager.getFileAndLineInfo(suggestionDiv);
   }
 
-  async collapseAISuggestion(suggestionId, suggestionRow, collapsedText, status) {
-    return this.suggestionManager.collapseAISuggestion(suggestionId, suggestionRow, collapsedText, status);
-  }
-
   getCategoryEmoji(category) {
     return this.suggestionManager.getCategoryEmoji(category);
   }
@@ -2325,14 +2541,103 @@ class PRManager {
     return this.suggestionManager.formatAdoptedComment(text, category);
   }
 
-  async createUserCommentFromSuggestion(suggestionId, fileName, lineNumber, suggestionText, suggestionType, suggestionTitle, diffPosition, side) {
-    return this.suggestionManager.createUserCommentFromSuggestion(suggestionId, fileName, lineNumber, suggestionText, suggestionType, suggestionTitle, diffPosition, side);
-  }
-
   getTypeDescription(type) {
     return this.suggestionManager.getTypeDescription(type);
   }
 
+  /**
+   * Collapse a suggestion div in the UI after adoption.
+   * Handles adding collapsed class, updating text to 'Suggestion adopted',
+   * updating the restore button, and setting hiddenForAdoption flag.
+   * @param {HTMLElement} suggestionRow - The suggestion row element
+   * @param {number|string} suggestionId - Suggestion ID
+   */
+  collapseSuggestionForAdoption(suggestionRow, suggestionId) {
+    if (!suggestionRow) return;
+    const targetDiv = suggestionRow.querySelector(`[data-suggestion-id="${suggestionId}"]`);
+    if (!targetDiv) return;
+    targetDiv.classList.add('collapsed');
+    const collapsedContent = targetDiv.querySelector('.collapsed-text');
+    if (collapsedContent) collapsedContent.textContent = 'Suggestion adopted';
+    const restoreButton = targetDiv.querySelector('.btn-restore');
+    if (restoreButton) {
+      restoreButton.title = 'Show suggestion';
+      const btnText = restoreButton.querySelector('.btn-text');
+      if (btnText) btnText.textContent = 'Show';
+    }
+    targetDiv.dataset.hiddenForAdoption = 'true';
+  }
+
+  /**
+   * Shared helper for adoptAndEditSuggestion and adoptSuggestion.
+   * Performs the /adopt fetch, collapses the suggestion, formats the comment,
+   * and builds the newComment object. Returns { newComment, suggestionRow }
+   * or null on failure. Throws on errors so the caller can handle them.
+   */
+  async _adoptAndBuildComment(suggestionId, suggestionDiv) {
+    const { suggestionText, suggestionType, suggestionTitle } = this.extractSuggestionData(suggestionDiv);
+    const { suggestionRow, lineNumber, fileName, diffPosition, side, isFileLevel } = this.getFileAndLineInfo(suggestionDiv);
+
+    // File-level suggestions are handled by FileCommentManager; signal the caller
+    if (isFileLevel) {
+      return { isFileLevel: true, suggestionText, suggestionType, suggestionTitle, fileName, suggestionRow };
+    }
+
+    // Use the atomic /adopt endpoint which creates the user comment, sets parent_id
+    // linkage, and updates suggestion status to 'adopted' in a single request
+    const reviewId = this.currentPR?.id;
+    const adoptResponse = await fetch(`/api/reviews/${reviewId}/suggestions/${suggestionId}/adopt`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' }
+    });
+
+    if (!adoptResponse.ok) throw new Error('Failed to adopt suggestion');
+
+    const adoptResult = await adoptResponse.json();
+
+    // Collapse the suggestion in the UI
+    this.collapseSuggestionForAdoption(suggestionRow, suggestionId);
+
+    // Build comment data from the adopt response and suggestion metadata
+    const formattedText = this.formatAdoptedComment(suggestionText, suggestionType);
+    const newComment = {
+      id: adoptResult.userCommentId,
+      file: fileName,
+      line_start: parseInt(lineNumber),
+      body: formattedText,
+      type: suggestionType,
+      title: suggestionTitle,
+      parent_id: suggestionId,
+      diff_position: diffPosition ? parseInt(diffPosition) : null,
+      side: side || 'RIGHT',
+      created_at: new Date().toISOString()
+    };
+
+    return { isFileLevel: false, newComment, suggestionRow };
+  }
+
+  /**
+   * Notify panels and navigator after a successful adoption
+   */
+  _notifyAdoption(suggestionId, newComment) {
+    if (window.aiPanel?.addComment) {
+      window.aiPanel.addComment(newComment);
+    }
+
+    if (this.suggestionNavigator?.suggestions) {
+      const updatedSuggestions = this.suggestionNavigator.suggestions.map(s =>
+        s.id === suggestionId ? { ...s, status: 'adopted' } : s
+      );
+      this.suggestionNavigator.updateSuggestions(updatedSuggestions);
+    }
+
+    if (window.aiPanel) {
+      window.aiPanel.updateFindingStatus(suggestionId, 'adopted');
+    }
+
+    this.updateCommentCount();
+  }
+
   /**
    * Adopt an AI suggestion and open it in edit mode
    */
@@ -2341,54 +2646,27 @@ class PRManager {
       const suggestionDiv = document.querySelector(`[data-suggestion-id="${suggestionId}"]`);
       if (!suggestionDiv) throw new Error('Suggestion element not found');
 
-      const { suggestionText, suggestionType, suggestionTitle } = this.extractSuggestionData(suggestionDiv);
-      const { suggestionRow, lineNumber, fileName, diffPosition, side, isFileLevel } = this.getFileAndLineInfo(suggestionDiv);
+      const result = await this._adoptAndBuildComment(suggestionId, suggestionDiv);
 
-      // File-level suggestions use FileCommentManager for edit-and-adopt
-      if (isFileLevel) {
+      if (result.isFileLevel) {
         if (!this.fileCommentManager) throw new Error('FileCommentManager not initialized');
-        const zone = this.fileCommentManager.findZoneForFile(fileName);
-        if (!zone) throw new Error(`Could not find file comments zone for ${fileName}`);
+        const zone = this.fileCommentManager.findZoneForFile(result.fileName);
+        if (!zone) throw new Error(`Could not find file comments zone for ${result.fileName}`);
 
-        // Build suggestion object for FileCommentManager
         const suggestion = {
           id: suggestionId,
-          file: fileName,
-          body: suggestionText,
-          type: suggestionType,
-          title: suggestionTitle
+          file: result.fileName,
+          body: result.suggestionText,
+          type: result.suggestionType,
+          title: result.suggestionTitle
         };
 
-        // Use editAndAdoptAISuggestion which opens an edit form
         this.fileCommentManager.editAndAdoptAISuggestion(zone, suggestion);
         return;
       }
 
-      await this.collapseAISuggestion(suggestionId, suggestionRow, 'Suggestion adopted', 'adopted');
-
-      const newComment = await this.createUserCommentFromSuggestion(
-        suggestionId, fileName, lineNumber, suggestionText, suggestionType, suggestionTitle, diffPosition, side
-      );
-
-      this.displayUserCommentInEditMode(newComment, suggestionRow);
-
-      // Notify AI Panel about the new adopted comment
-      if (window.aiPanel?.addComment) {
-        window.aiPanel.addComment(newComment);
-      }
-
-      if (this.suggestionNavigator?.suggestions) {
-        const updatedSuggestions = this.suggestionNavigator.suggestions.map(s =>
-          s.id === suggestionId ? { ...s, status: 'adopted' } : s
-        );
-        this.suggestionNavigator.updateSuggestions(updatedSuggestions);
-      }
-
-      if (window.aiPanel) {
-        window.aiPanel.updateFindingStatus(suggestionId, 'adopted');
-      }
-
-      this.updateCommentCount();
+      this.displayUserCommentInEditMode(result.newComment, result.suggestionRow);
+      this._notifyAdoption(suggestionId, result.newComment);
     } catch (error) {
       console.error('Error adopting and editing suggestion:', error);
       alert(`Failed to adopt suggestion: ${error.message}`);
@@ -2403,53 +2681,27 @@ class PRManager {
       const suggestionDiv = document.querySelector(`[data-suggestion-id="${suggestionId}"]`);
       if (!suggestionDiv) throw new Error('Suggestion element not found');
 
-      const { suggestionText, suggestionType, suggestionTitle } = this.extractSuggestionData(suggestionDiv);
-      const { suggestionRow, lineNumber, fileName, diffPosition, side, isFileLevel } = this.getFileAndLineInfo(suggestionDiv);
+      const result = await this._adoptAndBuildComment(suggestionId, suggestionDiv);
 
-      // File-level suggestions use FileCommentManager for adoption
-      if (isFileLevel) {
+      if (result.isFileLevel) {
         if (!this.fileCommentManager) throw new Error('FileCommentManager not initialized');
-        const zone = this.fileCommentManager.findZoneForFile(fileName);
-        if (!zone) throw new Error(`Could not find file comments zone for ${fileName}`);
+        const zone = this.fileCommentManager.findZoneForFile(result.fileName);
+        if (!zone) throw new Error(`Could not find file comments zone for ${result.fileName}`);
 
-        // Build suggestion object for FileCommentManager
         const suggestion = {
           id: suggestionId,
-          file: fileName,
-          body: suggestionText,
-          type: suggestionType,
-          title: suggestionTitle
+          file: result.fileName,
+          body: result.suggestionText,
+          type: result.suggestionType,
+          title: result.suggestionTitle
         };
 
         await this.fileCommentManager.adoptAISuggestion(zone, suggestion);
         return;
       }
 
-      await this.collapseAISuggestion(suggestionId, suggestionRow, 'Suggestion adopted', 'adopted');
-
-      const newComment = await this.createUserCommentFromSuggestion(
-        suggestionId, fileName, lineNumber, suggestionText, suggestionType, suggestionTitle, diffPosition, side
-      );
-
-      this.displayUserComment(newComment, suggestionRow);
-
-      // Notify AI Panel about the new adopted comment
-      if (window.aiPanel?.addComment) {
-        window.aiPanel.addComment(newComment);
-      }
-
-      if (this.suggestionNavigator?.suggestions) {
-        const updatedSuggestions = this.suggestionNavigator.suggestions.map(s =>
-          s.id === suggestionId ? { ...s, status: 'adopted' } : s
-        );
-        this.suggestionNavigator.updateSuggestions(updatedSuggestions);
-      }
-
-      if (window.aiPanel) {
-        window.aiPanel.updateFindingStatus(suggestionId, 'adopted');
-      }
-
-      this.updateCommentCount();
+      this.displayUserComment(result.newComment, result.suggestionRow);
+      this._notifyAdoption(suggestionId, result.newComment);
     } catch (error) {
       console.error('Error adopting suggestion:', error);
       alert(`Failed to adopt suggestion: ${error.message}`);
@@ -2480,7 +2732,7 @@ class PRManager {
         return;
       }
 
-      const response = await fetch(`/api/ai-suggestion/${suggestionId}/status`, {
+      const response = await fetch(`/api/reviews/${this.currentPR.id}/suggestions/${suggestionId}/status`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ status: 'dismissed' })
@@ -2536,7 +2788,7 @@ class PRManager {
         return;
       }
 
-      const response = await fetch(`/api/ai-suggestion/${suggestionId}/status`, {
+      const response = await fetch(`/api/reviews/${this.currentPR.id}/suggestions/${suggestionId}/status`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ status: 'active' })
@@ -2815,15 +3067,10 @@ class PRManager {
         return;
       }
 
-      // Determine the correct API endpoint based on mode
+      // Use unified review comments API (works for both PR and local mode)
+      const reviewId = pr.id;
       let response;
-      if (window.PAIR_REVIEW_LOCAL_MODE && window.localManager?.reviewId) {
-        // Local mode - use local API endpoint
-        response = await fetch(`/api/local/${window.localManager.reviewId}/user-comments`);
-      } else {
-        // PR mode - use PR API endpoint
-        response = await fetch(`/api/pr/${pr.owner}/${pr.repo}/${pr.number}/user-comments`);
-      }
+      response = await fetch(`/api/reviews/${reviewId}/comments`);
 
       if (!response.ok) {
         throw new Error('Failed to load comments');
@@ -2924,6 +3171,11 @@ class PRManager {
         generated: file.generated || false,
         renamed: file.renamed || false,
         renamedFrom: file.renamedFrom || null,
+        contextFile: file.contextFile || false,
+        contextId: file.contextId || null,
+        label: file.label || null,
+        lineStart: file.lineStart || null,
+        lineEnd: file.lineEnd || null,
       });
     });
 
@@ -2938,6 +3190,9 @@ class PRManager {
     const fileListContainer = document.getElementById('file-list');
     if (!fileListContainer) return;
 
+    // Store diff-only files for merging with context files later
+    this.diffFiles = files.filter(f => !f.contextFile);
+
     // Update sidebar file count badge
     const fileCountEl = document.getElementById('sidebar-file-count');
     if (fileCountEl) {
@@ -3008,6 +3263,7 @@ class PRManager {
     item.dataset.status = file.status;
 
     if (file.generated) item.classList.add('generated');
+    if (file.contextFile) item.classList.add('context-file-item');
     if (file.renamed && file.renamedFrom) {
       item.title = `Renamed from: ${file.renamedFrom}`;
       const renameIcon = document.createElement('span');
@@ -3023,7 +3279,13 @@ class PRManager {
     const changes = document.createElement('span');
     changes.className = 'file-changes';
 
-    if (file.binary) {
+    if (file.contextFile) {
+      const badge = document.createElement('span');
+      badge.className = 'context-badge';
+      badge.textContent = 'CONTEXT';
+      if (file.label) badge.title = file.label;
+      changes.appendChild(badge);
+    } else if (file.binary) {
       changes.textContent = 'BIN';
     } else {
       if (file.additions > 0) {
@@ -3045,7 +3307,11 @@ class PRManager {
 
     item.addEventListener('click', (e) => {
       e.preventDefault();
-      this.scrollToFile(file.fullPath);
+      if (file.contextFile) {
+        this.scrollToContextFile(file.fullPath, file.lineStart, file.contextId);
+      } else {
+        this.scrollToFile(file.fullPath);
+      }
       this.setActiveFileItem(file.fullPath);
     });
 
@@ -3377,8 +3643,9 @@ class PRManager {
     if (!this.currentPR) return;
 
     try {
-      const { owner, repo, number } = this.currentPR;
-      const response = await fetch(`/api/pr/${owner}/${repo}/${number}/analysis-status`);
+      const reviewId = this.currentPR.id;
+      if (!reviewId) return;
+      const response = await fetch(`/api/reviews/${reviewId}/analyses/status`);
 
       if (!response.ok) {
         console.warn('Could not check analysis status:', response.statusText);
@@ -3664,7 +3931,7 @@ class PRManager {
       // Determine endpoint and body based on whether this is a council analysis
       let analyzeUrl, analyzeBody;
       if (config.isCouncil) {
-        analyzeUrl = `/api/analyze/council/${owner}/${repo}/${number}`;
+        analyzeUrl = `/api/pr/${owner}/${repo}/${number}/analyses/council`;
         analyzeBody = {
           councilId: config.councilId || undefined,
           councilConfig: config.councilConfig || undefined,
@@ -3672,7 +3939,7 @@ class PRManager {
           customInstructions: config.customInstructions || null
         };
       } else {
-        analyzeUrl = `/api/analyze/${owner}/${repo}/${number}`;
+        analyzeUrl = `/api/pr/${owner}/${repo}/${number}/analyses`;
         analyzeBody = {
           provider: config.provider || 'claude',
           model: config.model || 'opus',
@@ -3839,6 +4106,589 @@ class PRManager {
       }
     }
   }
+
+  // ─── Context Files ──────────────────────────────────────────────
+
+  /**
+   * Load context files for the current review and render them in the diff panel.
+   * Called after renderDiff() and on SSE context_files_changed events.
+   */
+  async loadContextFiles() {
+    const reviewId = this.currentPR?.id;
+    if (!reviewId) return;
+
+    try {
+      const response = await fetch(`/api/reviews/${reviewId}/context-files`);
+      if (!response.ok) return;
+
+      const data = await response.json();
+      const newFiles = data.contextFiles || [];
+
+      const oldIds = new Set((this.contextFiles || []).map(f => f.id));
+      const newIds = new Set(newFiles.map(f => f.id));
+
+      // Remove only deleted context files (handles both standalone and merged wrappers)
+      for (const old of this.contextFiles || []) {
+        if (!newIds.has(old.id)) {
+          const el = document.querySelector(`[data-context-id="${old.id}"]`);
+          if (!el) continue;
+          if (el.classList.contains('context-file')) {
+            // Standalone wrapper (legacy) — remove entirely
+            el.remove();
+          } else {
+            // Chunk tbody within a merged wrapper
+            const wrapper = el.closest('.context-file');
+            // Also remove adjacent separator tbody if present
+            const prevSib = el.previousElementSibling;
+            const nextSib = el.nextElementSibling;
+            if (prevSib && prevSib.classList.contains('context-chunk-separator')) {
+              prevSib.remove();
+            } else if (nextSib && nextSib.classList.contains('context-chunk-separator')) {
+              nextSib.remove();
+            }
+            el.remove();
+            // If no more chunks remain, remove the wrapper too
+            if (wrapper && !wrapper.querySelector('.context-chunk')) {
+              wrapper.remove();
+            }
+          }
+        }
+      }
+
+      // Add only new context files
+      let newFilesRendered = false;
+      for (const cf of newFiles) {
+        if (!oldIds.has(cf.id)) {
+          await this.renderContextFile(cf);
+          newFilesRendered = true;
+        }
+      }
+
+      this.contextFiles = newFiles;
+
+      // Rebuild sidebar with context files interleaved in natural path order
+      this.rebuildFileListWithContext();
+
+      // Re-anchor comments after new context files are rendered so that
+      // comments targeting lines in these files find their DOM targets.
+      // loadUserComments() is idempotent (clears existing comment rows first).
+      if (newFilesRendered) {
+        const includeDismissed = window.aiPanel?.showDismissedComments || false;
+        await this.loadUserComments(includeDismissed);
+      }
+    } catch (error) {
+      console.error('Error loading context files:', error);
+    }
+  }
+
+  /**
+   * Rebuild the sidebar file list with context files interleaved in natural path order.
+   * Merges stored diff files with current context files and re-renders the sidebar.
+   * Delegates to the shared FileListMerger module for the merge/sort logic.
+   */
+  rebuildFileListWithContext() {
+    const { mergeFileListWithContext } = window.FileListMerger || {};
+    if (!mergeFileListWithContext) {
+      console.warn('FileListMerger not loaded - cannot rebuild file list with context');
+      return;
+    }
+    const merged = mergeFileListWithContext(this.diffFiles, this.contextFiles);
+    this.updateFileList(merged);
+  }
+
+  /**
+   * Build a context chunk tbody with line rows for a context file range.
+   * @param {Object} data - { lines: string[] } from fetchFileContent
+   * @param {Object} contextFile - { id, file, line_start, line_end }
+   * @returns {HTMLElement} tbody element with class context-chunk
+   * @private
+   */
+  _buildContextChunkTbody(data, contextFile) {
+    const tbody = document.createElement('tbody');
+    tbody.className = 'd2h-diff-tbody context-chunk';
+    tbody.dataset.contextId = contextFile.id;
+    tbody.dataset.lineStart = contextFile.line_start;
+
+    // Chunk header row with range label and per-chunk dismiss button
+    const headerRow = document.createElement('tr');
+    headerRow.className = 'context-chunk-header';
+    const lineNumTd = document.createElement('td');
+    lineNumTd.className = 'd2h-code-linenumber';
+    headerRow.appendChild(lineNumTd);
+    const contentTd = document.createElement('td');
+    contentTd.className = 'd2h-code-side-line';
+    contentTd.colSpan = 3;
+    const rangeLabel = document.createElement('span');
+    rangeLabel.className = 'context-range-label';
+    const lineEnd = Math.min(contextFile.line_end, data.lines.length);
+    rangeLabel.textContent = `Lines ${contextFile.line_start}\u2013${lineEnd}`;
+    contentTd.appendChild(rangeLabel);
+    const chunkDismiss = document.createElement('button');
+    chunkDismiss.className = 'context-chunk-dismiss';
+    chunkDismiss.title = 'Remove this range';
+    chunkDismiss.innerHTML = '\u00d7';
+    chunkDismiss.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.removeContextFile(contextFile.id);
+    });
+    contentTd.appendChild(chunkDismiss);
+    headerRow.appendChild(contentTd);
+    tbody.appendChild(headerRow);
+
+    const lineStart = contextFile.line_start;
+    const clampedEnd = Math.min(contextFile.line_end, data.lines.length);
+
+    // Add expand-up gap row if there are lines above the context range
+    if (lineStart > 1) {
+      const gapAboveSize = lineStart - 1;
+      const gapAbove = window.HunkParser.createGapRowElement(
+        contextFile.file,
+        1,              // startLine (old coords)
+        lineStart - 1,  // endLine (old coords)
+        gapAboveSize,
+        'above',
+        this.expandGapContext.bind(this),
+        1               // startLineNew (same as old for context files — no diff offset)
+      );
+      tbody.appendChild(gapAbove);
+    }
+
+    for (let i = lineStart; i <= clampedEnd; i++) {
+      const lineData = {
+        type: 'context',
+        oldNumber: i,
+        newNumber: i,
+        content: ' ' + (data.lines[i - 1] || '')
+      };
+      this.renderDiffLine(tbody, lineData, contextFile.file, null);
+    }
+
+    // Add expand-down gap row if there are lines below the context range
+    const totalLines = data.lines.length;
+    if (clampedEnd < totalLines) {
+      const gapBelowSize = totalLines - clampedEnd;
+      const gapBelow = window.HunkParser.createGapRowElement(
+        contextFile.file,
+        clampedEnd + 1, // startLine (old coords)
+        totalLines,     // endLine (old coords)
+        gapBelowSize,
+        'below',
+        this.expandGapContext.bind(this),
+        clampedEnd + 1  // startLineNew (same as old)
+      );
+      tbody.appendChild(gapBelow);
+    }
+
+    return tbody;
+  }
+
+  /**
+   * Insert a chunk tbody into an existing table in sorted position by line_start.
+   * Adds a visual separator tbody between non-contiguous ranges.
+   * @param {HTMLElement} table - the d2h-diff-table
+   * @param {HTMLElement} newTbody - the context-chunk tbody to insert
+   * @private
+   */
+  _insertChunkSorted(table, newTbody) {
+    const newStart = parseInt(newTbody.dataset.lineStart, 10);
+    const existingChunks = [...table.querySelectorAll('tbody.context-chunk')];
+
+    // Find insertion point
+    let insertBeforeChunk = null;
+    for (const chunk of existingChunks) {
+      const chunkStart = parseInt(chunk.dataset.lineStart, 10);
+      if (chunkStart > newStart) {
+        insertBeforeChunk = chunk;
+        break;
+      }
+    }
+
+    // Determine the element to insert before (including any separator before it)
+    if (insertBeforeChunk) {
+      const prevSibling = insertBeforeChunk.previousElementSibling;
+      const hasSepBefore = prevSibling && prevSibling.classList.contains('context-chunk-separator');
+      if (hasSepBefore) {
+        table.insertBefore(newTbody, prevSibling);
+        const sep = this._createChunkSeparator();
+        table.insertBefore(sep, newTbody);
+      } else {
+        table.insertBefore(newTbody, insertBeforeChunk);
+        const sep = this._createChunkSeparator();
+        table.insertBefore(sep, insertBeforeChunk);
+      }
+    } else {
+      // Append after the last chunk — add separator before if there are existing chunks
+      if (existingChunks.length > 0) {
+        const sep = this._createChunkSeparator();
+        table.appendChild(sep);
+      }
+      table.appendChild(newTbody);
+    }
+  }
+
+  /**
+   * Create a visual separator tbody between context chunks.
+   * @returns {HTMLElement} tbody with a single separator row
+   * @private
+   */
+  _createChunkSeparator() {
+    const sep = document.createElement('tbody');
+    sep.className = 'context-chunk-separator';
+    const row = document.createElement('tr');
+    row.className = 'context-chunk-separator-row';
+    const td = document.createElement('td');
+    td.colSpan = 4;
+    td.className = 'd2h-code-side-line context-chunk-separator-cell';
+    row.appendChild(td);
+    sep.appendChild(row);
+    return sep;
+  }
+
+  /**
+   * Render a single context file range in the diff panel.
+   * Merges ranges for the same file into a single wrapper with multiple chunk tbodies.
+   * @param {Object} contextFile - { id, review_id, file, line_start, line_end, label }
+   */
+  async renderContextFile(contextFile) {
+    const diffContainer = document.getElementById('diff-container');
+    if (!diffContainer) return;
+
+    // Fetch file content
+    const data = await this.fetchFileContent(contextFile.file);
+    if (!data || !data.lines) return;
+
+    // Check if a wrapper already exists for this file
+    const existing = diffContainer.querySelector(
+      `.d2h-file-wrapper.context-file[data-file-name="${CSS.escape(contextFile.file)}"]`
+    );
+
+    if (existing) {
+      // Merge into existing wrapper — add a new chunk tbody
+      const table = existing.querySelector('.d2h-diff-table');
+      if (!table) return;
+      const newTbody = this._buildContextChunkTbody(data, contextFile);
+      this._insertChunkSorted(table, newTbody);
+      return;
+    }
+
+    // No existing wrapper — create a new one
+    const wrapper = document.createElement('div');
+    wrapper.className = 'd2h-file-wrapper context-file';
+    wrapper.dataset.fileName = contextFile.file;
+
+    // Build file header — matches regular diff headers (chevron, viewed, comment btn, chat btn)
+    const header = document.createElement('div');
+    header.className = 'd2h-file-header context-file-header';
+
+    // Chevron toggle for expand/collapse
+    const chevronBtn = document.createElement('button');
+    chevronBtn.className = 'file-collapse-toggle';
+    chevronBtn.title = 'Collapse file';
+    chevronBtn.innerHTML = window.DiffRenderer.CHEVRON_DOWN_ICON;
+    chevronBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.toggleFileCollapse(contextFile.file);
+    });
+    header.appendChild(chevronBtn);
+
+    const fileName = document.createElement('span');
+    fileName.className = 'd2h-file-name';
+    fileName.textContent = contextFile.file;
+    header.appendChild(fileName);
+
+    const contextLabel = document.createElement('span');
+    contextLabel.className = 'context-badge';
+    contextLabel.textContent = 'CONTEXT';
+    if (contextFile.label) contextLabel.title = contextFile.label;
+    header.appendChild(contextLabel);
+
+    // Viewed checkbox (right-aligned group start)
+    const viewedLabel = document.createElement('label');
+    viewedLabel.className = 'file-viewed-label';
+    viewedLabel.title = 'Mark file as viewed';
+    const viewedCheckbox = document.createElement('input');
+    viewedCheckbox.type = 'checkbox';
+    viewedCheckbox.className = 'file-viewed-checkbox';
+    viewedCheckbox.checked = this.viewedFiles.has(contextFile.file);
+    viewedCheckbox.addEventListener('change', (e) => {
+      e.stopPropagation();
+      this.toggleFileViewed(contextFile.file, viewedCheckbox.checked);
+    });
+    viewedLabel.appendChild(viewedCheckbox);
+    viewedLabel.appendChild(document.createTextNode('Viewed'));
+    header.appendChild(viewedLabel);
+
+    // File comment button
+    if (this.fileCommentManager) {
+      const fileCommentsZone = this.fileCommentManager.createFileCommentsZone(contextFile.file);
+      wrapper._fileCommentsZone = fileCommentsZone;
+
+      const fileCommentBtn = document.createElement('button');
+      fileCommentBtn.className = 'file-header-comment-btn';
+      fileCommentBtn.title = 'Add file comment';
+      fileCommentBtn.dataset.file = contextFile.file;
+      fileCommentBtn.innerHTML = `
+        <svg class="comment-icon-outline" width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+          <path d="M1 2.75C1 1.784 1.784 1 2.75 1h10.5c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 13.25 12H9.06l-2.573 2.573A1.458 1.458 0 0 1 4 13.543V12H2.75A1.75 1.75 0 0 1 1 10.25Zm1.5 0v7.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h4.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25H2.75a.25.25 0 0 0-.25.25Z"/>
+        </svg>
+        <svg class="comment-icon-filled" width="16" height="16" viewBox="0 0 16 16" fill="currentColor" style="display:none">
+          <path d="M1 2.75C1 1.784 1.784 1 2.75 1h10.5c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 13.25 12H9.06l-2.573 2.573A1.458 1.458 0 0 1 4 13.543V12H2.75A1.75 1.75 0 0 1 1 10.25v-7.5Z"/>
+        </svg>
+      `;
+      fileCommentBtn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this.fileCommentManager.showCommentForm(fileCommentsZone, contextFile.file);
+      });
+      header.appendChild(fileCommentBtn);
+      fileCommentsZone.headerButton = fileCommentBtn;
+    }
+
+    // Chat/discussion button
+    const fileChatBtn = document.createElement('button');
+    fileChatBtn.className = 'file-header-chat-btn';
+    fileChatBtn.title = 'Chat about file';
+    fileChatBtn.dataset.file = contextFile.file;
+    fileChatBtn.innerHTML = `
+      <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+        <path d="M1.75 1h8.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 10.25 10H7.061l-2.574 2.573A1.458 1.458 0 0 1 2 11.543V10h-.25A1.75 1.75 0 0 1 0 8.25v-5.5C0 1.784.784 1 1.75 1ZM1.5 2.75v5.5c0 .138.112.25.25.25h1a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h3.5a.25.25 0 0 0 .25-.25v-5.5a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13 2a.25.25 0 0 0-.25-.25h-.5a.75.75 0 0 1 0-1.5h.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 14.25 12H14v1.543a1.458 1.458 0 0 1-2.487 1.03L9.22 12.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.22 2.22v-2.19a.75.75 0 0 1 .75-.75h1a.25.25 0 0 0 .25-.25Z"/>
+      </svg>
+    `;
+    fileChatBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      if (window.chatPanel) {
+        window.chatPanel.open({ fileContext: { file: contextFile.file } });
+      }
+    });
+    header.appendChild(fileChatBtn);
+
+    // Dismiss button — removes ALL context ranges for this file
+    const dismissBtn = document.createElement('button');
+    dismissBtn.className = 'context-file-dismiss';
+    dismissBtn.title = 'Remove context file';
+    dismissBtn.innerHTML = `<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"/></svg>`;
+    dismissBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      // Remove all context ranges for this file
+      const fileWrapper = e.target.closest('.context-file');
+      if (!fileWrapper) return;
+      const chunkIds = [...fileWrapper.querySelectorAll('tbody.context-chunk[data-context-id]')]
+        .map(tb => tb.dataset.contextId);
+      if (chunkIds.length === 0) return;
+      // Remove all ranges — fire sequentially to avoid race conditions
+      const removeAll = async () => {
+        for (const cid of chunkIds) {
+          await this.removeContextFile(cid);
+        }
+      };
+      removeAll();
+    });
+    header.appendChild(dismissBtn);
+
+    // Click anywhere on header to toggle collapse (except interactive controls)
+    header.addEventListener('click', (e) => {
+      if (e.target.closest('.file-viewed-label') || e.target.closest('.file-collapse-toggle') ||
+          e.target.closest('.file-header-comment-btn') || e.target.closest('.file-header-chat-btn') ||
+          e.target.closest('.context-file-dismiss')) {
+        return;
+      }
+      this.toggleFileCollapse(contextFile.file);
+    });
+
+    wrapper.appendChild(header);
+
+    // Insert file comments zone between header and diff content
+    if (wrapper._fileCommentsZone) {
+      wrapper.appendChild(wrapper._fileCommentsZone);
+    }
+
+    // Build code table with the first chunk
+    const table = document.createElement('table');
+    table.className = 'd2h-diff-table';
+    const tbody = this._buildContextChunkTbody(data, contextFile);
+    table.appendChild(tbody);
+    wrapper.appendChild(table);
+
+    // Insert in sorted path order among existing file wrappers
+    const allWrappers = [...diffContainer.querySelectorAll('.d2h-file-wrapper')];
+    const insertBefore = allWrappers.find(w => w.dataset.fileName > contextFile.file);
+    if (insertBefore) {
+      diffContainer.insertBefore(wrapper, insertBefore);
+    } else {
+      diffContainer.appendChild(wrapper);
+    }
+  }
+
+  /**
+   * Remove a context file by ID.
+   * @param {number} contextFileId
+   */
+  async removeContextFile(contextFileId) {
+    const reviewId = this.currentPR?.id;
+    if (!reviewId) return;
+
+    try {
+      const resp = await fetch(`/api/reviews/${reviewId}/context-files/${contextFileId}`, {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' }
+      });
+      if (!resp.ok) {
+        console.error('Failed to remove context file:', resp.status);
+        return;
+      }
+      // Refresh immediately — SSE self-echo is suppressed by the client ID filter
+      await this.loadContextFiles();
+    } catch (error) {
+      console.error('Error removing context file:', error);
+    }
+  }
+
+  /**
+   * Scroll to a context file (or diff file) in the diff panel.
+   * @param {string} file - File path
+   * @param {number} [lineStart] - Optional line number to highlight
+   */
+  scrollToContextFile(file, lineStart, contextId) {
+    // Use contextId to find a specific chunk tbody within a merged wrapper,
+    // or fall back to a standalone wrapper or the file-level wrapper.
+    let target;
+    if (contextId) {
+      // First try finding a specific chunk tbody (merged wrapper case)
+      const chunk = document.querySelector(`.context-chunk[data-context-id="${CSS.escape(contextId)}"]`);
+      if (chunk) {
+        target = chunk;
+      } else {
+        // Fallback: legacy standalone wrapper with data-context-id on the wrapper itself
+        target = document.querySelector(`.d2h-file-wrapper.context-file[data-context-id="${CSS.escape(contextId)}"]`);
+      }
+    }
+    if (!target) {
+      target = document.querySelector(`.d2h-file-wrapper.context-file[data-file-name="${CSS.escape(file)}"]`);
+    }
+    if (!target) return;
+
+    target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
+    if (lineStart) {
+      // Search for the line row within the wrapper (not just the target chunk)
+      const wrapper = target.closest('.d2h-file-wrapper') || target;
+      // Brief delay to let scroll settle, then highlight the target line
+      setTimeout(() => {
+        const row = wrapper.querySelector(`tr[data-line-number="${lineStart}"]`);
+        if (row) {
+          row.classList.remove('chat-line-highlight');
+          void row.offsetWidth;
+          row.classList.add('chat-line-highlight');
+          row.addEventListener('animationend', () => {
+            row.classList.remove('chat-line-highlight');
+          }, { once: true });
+        }
+      }, 400);
+    }
+  }
+
+  async ensureContextFile(file, lineStart = null, lineEnd = null) {
+    // 1. Guard: no review loaded
+    if (!this.currentPR?.id) return null;
+
+    // 2. Check diff files
+    if (this.diffFiles?.some(f => f.file === file)) {
+      return { type: 'diff' };
+    }
+
+    // 3. Compute line range values up front (used by both existing-check and POST)
+    let lineStartVal, lineEndVal;
+    if (lineStart == null && lineEnd == null) {
+      lineStartVal = 1;
+      lineEndVal = 100;
+    } else if (lineEnd == null) {
+      lineStartVal = lineStart;
+      lineEndVal = lineStart + 49;
+    } else {
+      lineStartVal = lineStart;
+      lineEndVal = Math.min(lineEnd, lineStart + 499);
+    }
+
+    // 4. Check existing context files — expand range if needed
+    const existingEntries = this.contextFiles?.filter(cf => cf.file === file) || [];
+    if (existingEntries.length > 0 && lineStart != null) {
+      const covering = existingEntries.find(cf =>
+        cf.line_start <= lineStartVal && cf.line_end >= lineEndVal
+      );
+      if (covering) {
+        return { type: 'context', contextFile: covering };
+      }
+
+      const overlapping = existingEntries.find(cf =>
+        cf.line_start <= lineEndVal && cf.line_end >= lineStartVal
+      );
+      if (overlapping) {
+        const newStart = Math.min(overlapping.line_start, lineStartVal);
+        let newEnd = Math.max(overlapping.line_end, lineEndVal);
+        if (newEnd - newStart + 1 > 500) {
+          newEnd = newStart + 499;
+        }
+        const reviewId = this.currentPR.id;
+        try {
+          const resp = await fetch(`/api/reviews/${reviewId}/context-files/${overlapping.id}`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ line_start: newStart, line_end: newEnd })
+          });
+          if (resp.ok) {
+            // Evict stale entries for this file so loadContextFiles sees
+            // them as new IDs and triggers a fresh render.
+            const staleFile = overlapping.file;
+            this.contextFiles = (this.contextFiles || []).filter(cf => cf.file !== staleFile);
+            // Remove the file wrapper from the DOM so chunks are re-created
+            const staleWrapper = document.querySelector(
+              `.d2h-file-wrapper.context-file[data-file-name="${CSS.escape(staleFile)}"]`
+            );
+            if (staleWrapper) staleWrapper.remove();
+
+            await this.loadContextFiles();
+            const updated = this.contextFiles?.find(cf => cf.id === overlapping.id);
+            return { type: 'context', contextFile: updated || overlapping, expanded: true };
+          }
+        } catch (err) {
+          console.error('Error expanding context file range:', err);
+        }
+      }
+    } else if (existingEntries.length > 0) {
+      return { type: 'context', contextFile: existingEntries[0] };
+    }
+
+    // 5. POST to add context file
+    const reviewId = this.currentPR.id;
+    try {
+      const resp = await fetch(`/api/reviews/${reviewId}/context-files`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file, line_start: lineStartVal, line_end: lineEndVal })
+      });
+
+      if (resp.status === 201) {
+        // 6. Reload context files to render
+        await this.loadContextFiles();
+        const added = this.contextFiles?.find(cf => cf.file === file);
+        return { type: 'context', contextFile: added || null };
+      }
+
+      if (resp.status === 400) {
+        const data = await resp.json().catch(() => ({}));
+        if (data.error?.includes('already part of the diff')) {
+          return { type: 'diff' };
+        }
+      }
+
+      // 7. Other errors
+      console.error('Failed to add context file:', resp.status);
+      return null;
+    } catch (err) {
+      console.error('Error adding context file:', err);
+      return null;
+    }
+  }
+
 }
 
 // Initialize PR manager when DOM is loaded (browser environment only)