@in-the-loop-labs/pair-review 3.5.2 → 3.6.0

package/public/js/components/ChatPanel.js

@@ -1275,13 +1275,15 @@ class ChatPanel {
     // attached as tabs are created/restored.
     this._ensureSubscriptions();
 
-    // Recognise thread context (external systems) alongside suggestion / user
-    // comment / file when deciding whether to open with explicit context.
+    // Recognise thread context (external systems) and tour context alongside
+    // suggestion / user comment / file when deciding whether to open with
+    // explicit context.
     const hasExplicitContext = !!(
       options.suggestionContext ||
       options.commentContext ||
       options.threadContext ||
-      options.fileContext
+      options.fileContext ||
+      options.tourContext
     );
 
     // First-time open behaviour:
@@ -1355,6 +1357,15 @@ class ChatPanel {
       this._sendFileContextMessage(options.fileContext);
       this._contextSource = 'file';
       this._contextItemId = null;
+    } else if (options.tourContext) {
+      // If opening with tour-stop context, inject it as a context card.
+      // Awaited because tour stops on context files (outside the PR diff)
+      // need an async file-content fetch to populate the snippet.
+      await this._sendTourContextMessage(options.tourContext);
+      this._contextSource = 'tour';
+      this._contextItemId = options.tourContext.stopIndex != null
+        ? String(options.tourContext.stopIndex)
+        : null;
     }
 
     // Gate input when reviewId is not yet available (PanelGroup auto-restore race)
@@ -2789,6 +2800,155 @@ class ChatPanel {
     this._addFileContextCard(contextData, { removable: true });
   }
 
+  /**
+   * Store pending context and render a compact context card for a tour stop.
+   * Called when the user clicks "Chat about" on a tour-stop annotation.
+   * The context is NOT sent to the agent immediately — it is prepended to
+   * the next user message so the agent receives question + context together.
+   *
+   * Async because tour stops on context files (files NOT in the PR diff) need
+   * to fetch a code snippet via the file-content API so the agent receives a
+   * meaningful snippet — same shape as the diff-hunk enrichment used for stops
+   * inside the diff.
+   *
+   * @param {Object} ctx - Tour stop context
+   *   {stopIndex, totalStops, title, description, file, line_start, line_end, side}
+   * @returns {Promise<void>}
+   */
+  async _sendTourContextMessage(ctx) {
+    const tab = this._getActiveTab();
+    if (!tab) return;
+
+    // Remove empty state if present
+    const emptyState = this.messagesEl.querySelector('.chat-panel__empty');
+    if (emptyState) emptyState.remove();
+
+    const stopLabel = (typeof ctx.stopIndex === 'number' && typeof ctx.totalStops === 'number')
+      ? `Stop ${ctx.stopIndex + 1} of ${ctx.totalStops}`
+      : 'Tour stop';
+
+    // Store structured context data for DB persistence (session resumption).
+    const contextData = {
+      type: 'tour stop',
+      title: ctx.title || stopLabel,
+      file: ctx.file || null,
+      line_start: ctx.line_start || null,
+      line_end: ctx.line_end || null,
+      side: ctx.side || null,
+      body: ctx.description || null,
+      stopIndex: typeof ctx.stopIndex === 'number' ? ctx.stopIndex : null,
+      totalStops: typeof ctx.totalStops === 'number' ? ctx.totalStops : null
+    };
+    tab.pendingContextData.push(contextData);
+
+    // Build the plain-text context for the agent.
+    const lines = [`The user wants to discuss this tour stop (${stopLabel}):`];
+    if (contextData.title) {
+      lines.push(`- Title: ${contextData.title}`);
+    }
+    if (contextData.file) {
+      let fileLine = `- File: ${contextData.file}`;
+      if (contextData.line_start) {
+        fileLine += ` (line ${contextData.line_start}${contextData.line_end && contextData.line_end !== contextData.line_start ? '-' + contextData.line_end : ''})`;
+      }
+      lines.push(fileLine);
+    }
+    if (contextData.body) {
+      lines.push(`- Description: ${contextData.body}`);
+    }
+
+    // Enrich with code snippet.
+    //
+    // Primary path: pull from the in-memory PR diff via DiffContext. This is
+    // synchronous and matches the shape used by suggestion/comment context.
+    //
+    // Fallback path: tour-renderer.prepareStop auto-adds context files (files
+    // outside the PR diff) via prManager.ensureContextFile. Those files have
+    // no entry in filePatches, so the lookup misses — but the agent benefits
+    // most from a snippet in exactly that case (file isn't visible in the
+    // diff). Fetch the file content and slice [line_start-5, line_end+5].
+    //
+    // Both paths render as a fenced code block so the agent sees a consistent
+    // shape. A failed fetch logs a warning and falls through to no snippet.
+    const patch = window.prManager?.filePatches?.get(contextData.file);
+    let snippet = null;
+    if (patch && window.DiffContext && contextData.line_start) {
+      const hunk = window.DiffContext.extractHunkForLines(
+        patch,
+        contextData.line_start,
+        contextData.line_end || contextData.line_start,
+        contextData.side
+      );
+      if (hunk) {
+        snippet = `- Diff hunk:\n\`\`\`\n${hunk}\n\`\`\``;
+      }
+    } else if (!patch && contextData.file && contextData.line_start) {
+      const sliced = await this._fetchContextFileSnippet(
+        contextData.file,
+        contextData.line_start,
+        contextData.line_end || contextData.line_start
+      );
+      if (sliced) {
+        snippet = `- File snippet:\n\`\`\`\n${sliced}\n\`\`\``;
+      }
+    }
+    if (snippet) {
+      lines.push(snippet);
+    }
+
+    tab.pendingContext.push(lines.join('\n'));
+
+    // Render the compact context card in the UI (reuses suggestion card shape).
+    this._addContextCard(contextData, { removable: true });
+  }
+
+  /**
+   * Fetch a small slice of file content for tour stops on context files
+   * (files outside the PR diff). Returns the slice with line numbers prefixed
+   * so the agent can correlate with the stop's line range, or null on failure.
+   *
+   * @param {string} file - File path (will be URI-encoded)
+   * @param {number} lineStart - 1-based first line of the stop range
+   * @param {number} lineEnd   - 1-based last line of the stop range (inclusive)
+   * @param {number} [padding=5] - Extra lines to include on each side
+   * @returns {Promise<string|null>}
+   */
+  async _fetchContextFileSnippet(file, lineStart, lineEnd, padding = 5) {
+    const reviewId = this.reviewId || window.prManager?.currentPR?.id;
+    if (!reviewId || !file || !lineStart) return null;
+
+    try {
+      const resp = await fetch(
+        `/api/reviews/${reviewId}/file-content/${encodeURIComponent(file)}`
+      );
+      if (!resp || !resp.ok) {
+        console.warn(
+          '[ChatPanel] context-file snippet fetch failed',
+          { file, status: resp && resp.status }
+        );
+        return null;
+      }
+      const data = await resp.json();
+      const allLines = Array.isArray(data?.lines) ? data.lines : null;
+      if (!allLines || allLines.length === 0) return null;
+
+      // Clamp to file bounds; convert to 0-based slice indices.
+      const startIdx = Math.max(0, lineStart - 1 - padding);
+      const endIdx = Math.min(allLines.length, lineEnd + padding);
+      if (endIdx <= startIdx) return null;
+
+      const out = [];
+      const pad = String(endIdx).length;
+      for (let i = startIdx; i < endIdx; i++) {
+        out.push(`${String(i + 1).padStart(pad, ' ')}: ${allLines[i]}`);
+      }
+      return out.join('\n');
+    } catch (err) {
+      console.warn('[ChatPanel] context-file snippet fetch threw', { file, err });
+      return null;
+    }
+  }
+
   /**
    * Add an analysis run as context for the chat conversation.
    * Fetches run metadata from the backend and creates a removable context card

package/public/js/components/KeyboardShortcuts.js

@@ -299,45 +299,29 @@ class KeyboardShortcuts {
   }
 
   /**
-   * Check if a modal is currently open (excluding our help overlay)
+   * Check if a modal is currently open (excluding our help overlay).
+   * Delegates to the shared ModalDetection utility so the selector list
+   * and visibility check stay in sync with PRManager's tour handler.
    * @returns {boolean} True if a modal is open
    */
   isModalOpen() {
-    // Check for common modal patterns in the codebase
-    const modalSelectors = [
-      '.modal-overlay:not(#keyboard-shortcuts-help)',
-      '.review-modal-overlay',
-      '.preview-modal-overlay',
-      '.confirm-dialog-overlay',
-      '.analysis-config-overlay',
-      '.ai-summary-modal-overlay',
-      '[role="dialog"]:not(#keyboard-shortcuts-help)'
-    ];
-
-    for (const selector of modalSelectors) {
-      const modal = document.querySelector(selector);
-      if (modal && this.isElementVisible(modal)) {
-        return true;
-      }
+    if (window.ModalDetection && typeof window.ModalDetection.isModalOpen === 'function') {
+      return window.ModalDetection.isModalOpen();
     }
-
     return false;
   }
 
   /**
-   * Check if an element is visible
+   * Check if an element is visible. Delegates to the shared
+   * ModalDetection utility.
    * @param {HTMLElement} element - The element to check
    * @returns {boolean} True if element is visible
    */
   isElementVisible(element) {
-    if (!element) return false;
-
-    const style = window.getComputedStyle(element);
-    if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
-      return false;
+    if (window.ModalDetection && typeof window.ModalDetection.isElementVisible === 'function') {
+      return window.ModalDetection.isElementVisible(element);
     }
-
-    return true;
+    return Boolean(element);
   }
 
   /**

package/public/js/components/TourBar.js

@@ -0,0 +1,248 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * TourBar - Sticky top bar shown while a guided tour is active.
+ *
+ * Displays "Stop N of M" plus Prev/Next/Exit controls. On completion the
+ * Prev/Next/Exit chrome swaps for Restart/Close. The bar consumes callbacks
+ * from PRManager; it never reaches back into application state.
+ *
+ * Lifecycle:
+ *   const bar = new TourBar({ onPrev, onNext, onExit, onRestart });
+ *   bar.mount(parent);       // prepends to parent (defaults to document.body)
+ *   bar.setStops(stops);     // initial render
+ *   bar.setActiveIndex(0);   // pre-tour state
+ *   bar.setCompleted(true);  // toggles to Restart / Close chrome
+ *   bar.unmount();
+ *
+ * The bar uses `position: sticky` so it visually pins to the top of its
+ * scrolling parent. Pass the diff-view scroll container as `parent` so the
+ * bar spans the diff width (and not the file-tree sidebar).
+ *
+ * Testability: instantiable in jsdom; CommonJS export at the bottom.
+ */
+
+// Octicon SVG path data. `milestone` brands the bar overall; `location`
+// marks the per-stop navigation chrome (mirrors the inline stop marker).
+// Module-scoped names are prefixed so they don't collide with the same
+// constants in tour-renderer.js when both are loaded as plain <script> tags
+// into the shared global scope.
+const TOUR_BAR_MILESTONE_PATH = 'M7.75 0a.75.75 0 0 1 .75.75V3h3.634c.414 0 .814.144 1.13.406l2.501 2.071a1.75 1.75 0 0 1 0 2.696l-2.5 2.07a1.75 1.75 0 0 1-1.131.407H8.5v5.6a.75.75 0 0 1-1.5 0V10.65H3.75A1.75 1.75 0 0 1 2 8.9V4.75C2 3.784 2.784 3 3.75 3H7V.75A.75.75 0 0 1 7.75 0Zm-4 4.5a.25.25 0 0 0-.25.25V8.9c0 .138.112.25.25.25h8.384a.25.25 0 0 0 .16-.058l2.5-2.07a.25.25 0 0 0 0-.386l-2.5-2.07a.25.25 0 0 0-.16-.058H3.75Z';
+const TOUR_BAR_LOCATION_PATH = 'm12.596 11.596-3.535 3.536a1.5 1.5 0 0 1-2.122 0l-3.535-3.536a6.5 6.5 0 1 1 9.192-9.193 6.5 6.5 0 0 1 0 9.193Zm-1.06-8.132v-.001a5 5 0 1 0-7.072 7.072L8 14.07l3.536-3.534a5 5 0 0 0 0-7.072ZM8 9a2 2 0 1 1-.001-3.999A2 2 0 0 1 8 9Z';
+
+function tourBarSvgIcon(pathData) {
+  return `<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="${pathData}"/></svg>`;
+}
+
+class TourBar {
+  /**
+   * @param {Object} callbacks
+   * @param {Function} [callbacks.onPrev]    - Called when the user clicks Prev.
+   * @param {Function} [callbacks.onNext]    - Called when the user clicks Next.
+   * @param {Function} [callbacks.onExit]    - Called when the user clicks Exit.
+   * @param {Function} [callbacks.onRestart] - Called when the user clicks Restart (completion state).
+   */
+  constructor({ onPrev, onNext, onExit, onRestart } = {}) {
+    this._onPrev = onPrev || (() => {});
+    this._onNext = onNext || (() => {});
+    this._onExit = onExit || (() => {});
+    this._onRestart = onRestart || (() => {});
+
+    this._stops = [];
+    this._activeIndex = -1;
+    this._completed = false;
+
+    this._root = null;
+    this._progressEl = null;
+    this._navEl = null;
+    this._prevBtn = null;
+    this._nextBtn = null;
+    this._exitBtn = null;
+    this._restartBtn = null;
+    this._closeBtn = null;
+  }
+
+  /**
+   * Prepend the bar to `parent` (defaults to `document.body`). Idempotent.
+   * The bar's CSS uses `position: sticky`, so it pins to the top of the
+   * nearest scrollable ancestor — pass that scroll container as `parent`
+   * to scope the bar to a region rather than the viewport.
+   * @param {HTMLElement} [parent=document.body]
+   * @returns {TourBar}
+   */
+  mount(parent) {
+    if (this._root && this._root.isConnected) return this;
+    const target = parent || document.body;
+
+    const root = document.createElement('div');
+    root.className = 'tour-bar';
+    root.setAttribute('role', 'toolbar');
+    root.setAttribute('aria-label', 'Guided tour controls');
+
+    const brand = document.createElement('div');
+    brand.className = 'tour-bar__brand';
+    brand.innerHTML = `${tourBarSvgIcon(TOUR_BAR_MILESTONE_PATH)}<span>Tour</span>`;
+
+    const progress = document.createElement('div');
+    progress.className = 'tour-bar__progress';
+    progress.textContent = '';
+
+    const nav = document.createElement('div');
+    nav.className = 'tour-bar__nav';
+
+    // Prev / Next / Exit (default chrome)
+    const prevBtn = document.createElement('button');
+    prevBtn.type = 'button';
+    prevBtn.className = 'tour-bar__prev';
+    prevBtn.innerHTML = `${tourBarSvgIcon(TOUR_BAR_LOCATION_PATH)}<span>Prev</span>`;
+    prevBtn.addEventListener('click', () => this._onPrev());
+
+    const nextBtn = document.createElement('button');
+    nextBtn.type = 'button';
+    nextBtn.className = 'tour-bar__next';
+    nextBtn.innerHTML = `<span>Next</span>${tourBarSvgIcon(TOUR_BAR_LOCATION_PATH)}`;
+    nextBtn.addEventListener('click', () => this._onNext());
+
+    const exitBtn = document.createElement('button');
+    exitBtn.type = 'button';
+    exitBtn.className = 'tour-bar__exit';
+    exitBtn.textContent = 'Exit';
+    exitBtn.addEventListener('click', () => this._onExit());
+
+    // Completion chrome (created up front, toggled by setCompleted)
+    const restartBtn = document.createElement('button');
+    restartBtn.type = 'button';
+    restartBtn.className = 'tour-bar__restart';
+    restartBtn.textContent = 'Restart';
+    restartBtn.style.display = 'none';
+    restartBtn.addEventListener('click', () => this._onRestart());
+
+    const closeBtn = document.createElement('button');
+    closeBtn.type = 'button';
+    closeBtn.className = 'tour-bar__close';
+    closeBtn.textContent = 'Close';
+    closeBtn.style.display = 'none';
+    closeBtn.addEventListener('click', () => this._onExit());
+
+    nav.appendChild(prevBtn);
+    nav.appendChild(nextBtn);
+    nav.appendChild(exitBtn);
+    nav.appendChild(restartBtn);
+    nav.appendChild(closeBtn);
+
+    root.appendChild(brand);
+    root.appendChild(progress);
+    root.appendChild(nav);
+
+    // Prepend so the bar becomes the first child — it pins above the
+    // diff-toolbar (which sits at top:0 in the same scroll container).
+    target.prepend(root);
+
+    this._root = root;
+    this._progressEl = progress;
+    this._navEl = nav;
+    this._prevBtn = prevBtn;
+    this._nextBtn = nextBtn;
+    this._exitBtn = exitBtn;
+    this._restartBtn = restartBtn;
+    this._closeBtn = closeBtn;
+
+    // Initial paint reflects whatever state was set before mount.
+    this._render();
+    return this;
+  }
+
+  /**
+   * Remove the bar from the DOM. Safe to call repeatedly.
+   */
+  unmount() {
+    if (this._root && this._root.isConnected) {
+      this._root.remove();
+    }
+    this._root = null;
+    this._progressEl = null;
+    this._navEl = null;
+    this._prevBtn = null;
+    this._nextBtn = null;
+    this._exitBtn = null;
+    this._restartBtn = null;
+    this._closeBtn = null;
+  }
+
+  /**
+   * @param {Array<Object>} stops - The full ordered list of stops.
+   */
+  setStops(stops) {
+    this._stops = Array.isArray(stops) ? stops : [];
+    this._render();
+  }
+
+  /**
+   * @param {number} index - The currently-active stop (0-based) or -1 for none.
+   */
+  setActiveIndex(index) {
+    this._activeIndex = typeof index === 'number' ? index : -1;
+    this._render();
+  }
+
+  /**
+   * @param {boolean} isCompleted - Swap to Restart/Close chrome when true.
+   */
+  setCompleted(isCompleted) {
+    this._completed = isCompleted === true;
+    this._render();
+  }
+
+  // --- private ------------------------------------------------------------
+
+  _render() {
+    if (!this._root) return;
+    const total = this._stops.length;
+    const visibleIndex = this._activeIndex + 1; // 1-based for display
+
+    if (this._progressEl) {
+      if (total === 0) {
+        this._progressEl.textContent = '';
+      } else if (this._completed) {
+        this._progressEl.textContent = `Tour complete (${total} stop${total === 1 ? '' : 's'})`;
+      } else if (this._activeIndex < 0) {
+        this._progressEl.textContent = `${total} stop${total === 1 ? '' : 's'}`;
+      } else {
+        this._progressEl.textContent = `Stop ${visibleIndex} of ${total}`;
+      }
+    }
+
+    if (this._completed) {
+      if (this._prevBtn) this._prevBtn.style.display = 'none';
+      if (this._nextBtn) this._nextBtn.style.display = 'none';
+      if (this._exitBtn) this._exitBtn.style.display = 'none';
+      if (this._restartBtn) this._restartBtn.style.display = '';
+      if (this._closeBtn) this._closeBtn.style.display = '';
+    } else {
+      if (this._prevBtn) this._prevBtn.style.display = '';
+      if (this._nextBtn) this._nextBtn.style.display = '';
+      if (this._exitBtn) this._exitBtn.style.display = '';
+      if (this._restartBtn) this._restartBtn.style.display = 'none';
+      if (this._closeBtn) this._closeBtn.style.display = 'none';
+
+      // Disable Prev at first stop; disable Next at last (no auto-completion
+      // happens in the bar — the orchestrator advances past the end to set
+      // completed state).
+      if (this._prevBtn) {
+        this._prevBtn.disabled = this._activeIndex <= 0;
+      }
+      if (this._nextBtn) {
+        // Next remains enabled on the last stop so the user can advance
+        // into completion state.
+        this._nextBtn.disabled = total === 0;
+      }
+    }
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.TourBar = TourBar;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { TourBar };
+}

package/public/js/local.js

@@ -1404,6 +1404,9 @@ class LocalManager {
       const diffContent = data.diff || '';
       const stats = data.stats || {};
       const generatedFiles = new Set(data.generated_files || []);
+      // Server-computed per-file hunk hashes (computed from the canonical
+      // diff so they remain stable across whitespace-filtered renders).
+      const hunkHashesByFile = data.hunk_hashes_by_file || {};
 
       if (!diffContent) {
         const diffContainer = document.getElementById('diff-container');
@@ -1468,6 +1471,9 @@ class LocalManager {
           insertions: additions,
           deletions: deletions,
           generated: isGenerated,
+          // Pass through the server-computed canonical hunk hashes; renderPatch
+          // requires these to anchor persisted summaries (no client-side fallback).
+          hunk_hashes: hunkHashesByFile[fileName] || null,
           status: patch.includes('new file mode') ? 'added' :
                   patch.includes('deleted file mode') ? 'removed' : 'modified'
         });