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

package/public/js/index.js

@@ -90,6 +90,8 @@
 
   /** localStorage key for persisting the active tab */
   const TAB_STORAGE_KEY = 'pair-review-active-tab';
+  const BULK_ANALYSIS_TAB_STORAGE_KEY = 'pair-review-bulk-analysis-tab';
+  const BULK_ANALYSIS_INSTRUCTIONS_STORAGE_KEY = 'pair-review-bulk-analysis-instructions';
 
   /**
    * Format a relative time string from a date
@@ -133,6 +135,10 @@
     return div.innerHTML;
   }
 
+  // encodeBase64Utf8 / getRepoStorageKey live in public/js/utils/storage-keys.js
+  // (window.encodeBase64Utf8 / window.getRepoStorageKey), shared with pr.js so the
+  // per-repo keys this page writes stay byte-identical to those the PR page reads.
+
   const LOCAL_REVIEW_PATH_URL_ERROR = 'Local reviews require a filesystem path, not a URL. Pass GitHub or Graphite URLs as PR review inputs instead.';
 
   function isUrlLikeLocalReviewPath(value) {
@@ -1377,6 +1383,9 @@
         window.__pairReview.chatProvider = config.chat_provider || 'pi';
         const chatProviders = config.chat_providers || [];
         window.__pairReview.chatProviders = chatProviders;
+        window.__pairReview.defaultProvider = config.default_provider || 'claude';
+        window.__pairReview.defaultModel = config.default_model || 'opus';
+        window.__pairReview.hasGithubToken = Boolean(config.has_github_token);
         window.__pairReview.enableGraphite = config.enable_graphite === true;
         window.__pairReview.chatSpinner = config.chat_spinner || 'dots';
         window.__pairReview.chatEnterToSend = config.chat_enter_to_send !== false;
@@ -1404,6 +1413,7 @@
 
   /** Currently active SelectionMode instance (only one tab at a time) */
   var activeSelection = null;
+  var bulkAnalysisConfigModal = null;
 
   /**
    * SelectionMode manages checkbox-based selection for a single tab's table.
@@ -1877,6 +1887,40 @@
     });
   }
 
+  /**
+   * Read selected collection rows as PR descriptors.
+   * @param {Set} selectedIds - PR URLs (data-pr-url values)
+   * @param {string} tbodyId - tbody element ID
+   * @returns {Array<{owner: string, repo: string, number: string, prUrl: string}>}
+   */
+  function getSelectedCollectionRows(selectedIds, tbodyId) {
+    var tbody = document.getElementById(tbodyId);
+    if (!tbody) return [];
+
+    var rows = [];
+    var trs = tbody.querySelectorAll('tr[data-pr-url]');
+    for (var i = 0; i < trs.length; i++) {
+      var tr = trs[i];
+      var prUrl = tr.dataset.prUrl;
+      if (!selectedIds.has(prUrl)) continue;
+      if (tr.dataset.owner && tr.dataset.repo && tr.dataset.number) {
+        rows.push({
+          owner: tr.dataset.owner,
+          repo: tr.dataset.repo,
+          number: tr.dataset.number,
+          prUrl: prUrl
+        });
+      }
+    }
+    return rows;
+  }
+
+  function buildReviewUrlsFromRows(rows, query) {
+    return rows.map(function (row) {
+      return '/pr/' + encodeURIComponent(row.owner) + '/' + encodeURIComponent(row.repo) + '/' + row.number + (query || '');
+    });
+  }
+
   /**
    * Build pair-review URLs from selected collection rows.
    * @param {Set} selectedIds - PR URLs (data-pr-url values)
@@ -1885,20 +1929,116 @@
    * @returns {string[]} array of pair-review URLs
    */
   function buildReviewUrls(selectedIds, tbodyId, query) {
-    var tbody = document.getElementById(tbodyId);
-    if (!tbody) return [];
-    var urls = [];
-    selectedIds.forEach(function (prUrl) {
-      var row = tbody.querySelector('tr[data-pr-url="' + CSS.escape(prUrl) + '"]');
-      if (!row) return;
-      var owner = row.dataset.owner;
-      var repo = row.dataset.repo;
-      var number = row.dataset.number;
-      if (owner && repo && number) {
-        urls.push('/pr/' + encodeURIComponent(owner) + '/' + encodeURIComponent(repo) + '/' + number + (query || ''));
+    return buildReviewUrlsFromRows(getSelectedCollectionRows(selectedIds, tbodyId), query);
+  }
+
+  function getCommonRepository(rows) {
+    if (rows.length === 0) return null;
+    var first = rows[0];
+    var firstKey = (first.owner + '/' + first.repo).toLowerCase();
+    for (var i = 1; i < rows.length; i++) {
+      if ((rows[i].owner + '/' + rows[i].repo).toLowerCase() !== firstKey) {
+        return null;
       }
+    }
+    return { owner: first.owner, repo: first.repo };
+  }
+
+  async function fetchBulkRepoSettings(commonRepo) {
+    if (!commonRepo) return null;
+    try {
+      var response = await fetch('/api/repos/' + encodeURIComponent(commonRepo.owner) + '/' + encodeURIComponent(commonRepo.repo) + '/settings');
+      if (!response.ok) return null;
+      return await response.json();
+    } catch (error) {
+      console.warn('Failed to fetch repo settings for bulk analysis:', error);
+      return null;
+    }
+  }
+
+  function getBulkAnalysisStorageKeys(commonRepo) {
+    if (!commonRepo) {
+      return {
+        tab: BULK_ANALYSIS_TAB_STORAGE_KEY,
+        instructions: BULK_ANALYSIS_INSTRUCTIONS_STORAGE_KEY
+      };
+    }
+    return {
+      tab: window.getRepoStorageKey('pair-review-tab', commonRepo.owner, commonRepo.repo),
+      instructions: window.getRepoStorageKey('pair-review-instructions', commonRepo.owner, commonRepo.repo)
+    };
+  }
+
+  // Cache the /api/providers metadata so the bulk modal can resolve a coherent
+  // provider/model pair before showing (mirrors PRManager._getProvidersInfo).
+  function getBulkProvidersInfo() {
+    window.__pairReview = window.__pairReview || {};
+    if (!window.__pairReview._providersInfoPromise) {
+      window.__pairReview._providersInfoPromise = fetch('/api/providers')
+        .then(function (r) { return r.ok ? r.json() : {}; })
+        .then(function (d) { return Array.isArray(d.providers) ? d.providers : []; })
+        .catch(function () { return []; });
+    }
+    return window.__pairReview._providersInfoPromise;
+  }
+
+  async function showBulkAnalysisConfig(rows) {
+    if (!window.AnalysisConfigModal) return null;
+
+    if (!bulkAnalysisConfigModal) {
+      bulkAnalysisConfigModal = new window.AnalysisConfigModal();
+    }
+
+    var commonRepo = getCommonRepository(rows);
+    var storageKeys = getBulkAnalysisStorageKeys(commonRepo);
+    var repoSettings = await fetchBulkRepoSettings(commonRepo);
+    var rememberedTab = localStorage.getItem(storageKeys.tab);
+    var lastInstructions = localStorage.getItem(storageKeys.instructions) || '';
+
+    bulkAnalysisConfigModal.onTabChange = function (tabId) {
+      localStorage.setItem(storageKeys.tab, tabId);
+    };
+
+    var providersInfo = await getBulkProvidersInfo();
+    var resolvedPair = window.resolveProviderModelPair([
+      { provider: repoSettings?.default_provider, model: repoSettings?.default_model },
+      { provider: window.__pairReview?.defaultProvider, model: window.__pairReview?.defaultModel }
+    ], providersInfo);
+
+    var config = await bulkAnalysisConfigModal.show({
+      currentModel: resolvedPair.model,
+      currentProvider: resolvedPair.provider,
+      defaultTab: rememberedTab || repoSettings?.default_tab || 'single',
+      repoInstructions: commonRepo ? (repoSettings?.default_instructions || '') : '',
+      lastInstructions: lastInstructions,
+      defaultCouncilId: commonRepo ? (repoSettings?.default_council_id || null) : null,
+      hasPr: true,
+      hasGithubToken: window.__pairReview?.hasGithubToken !== false
+    });
+
+    if (!config) return null;
+
+    var submittedInstructions = config.customInstructions || '';
+    if (submittedInstructions) {
+      localStorage.setItem(storageKeys.instructions, submittedInstructions);
+    } else {
+      localStorage.removeItem(storageKeys.instructions);
+    }
+
+    return config;
+  }
+
+  async function storeBulkAnalysisConfig(config) {
+    var response = await fetch('/api/bulk-analysis-configs', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ analysisConfig: config })
     });
-    return urls;
+    var data = await response.json().catch(function () { return {}; });
+    if (!response.ok || !data.id) {
+      throw new Error(data.error || 'Failed to save analysis settings');
+    }
+    return data.id;
   }
 
   /**
@@ -1924,10 +2064,29 @@
     bulkOpenUrls(urls);
   }
 
-  function handleBulkAnalyze(selectedIds, selectionInstance) {
-    var urls = buildReviewUrls(selectedIds, selectionInstance.config.tbodyId, '?analyze=true');
-    selectionInstance.exit();
-    bulkOpenUrls(urls);
+  async function handleBulkAnalyze(selectedIds, selectionInstance) {
+    var rows = getSelectedCollectionRows(selectedIds, selectionInstance.config.tbodyId);
+    if (rows.length === 0) return;
+
+    if (!window.AnalysisConfigModal) {
+      selectionInstance.exit();
+      bulkOpenUrls(buildReviewUrlsFromRows(rows, '?analyze=true'));
+      return;
+    }
+
+    try {
+      var config = await showBulkAnalysisConfig(rows);
+      if (!config) return;
+
+      var configId = await storeBulkAnalysisConfig(config);
+      var query = '?analyze=true&analysisConfigId=' + encodeURIComponent(configId);
+      var urls = buildReviewUrlsFromRows(rows, query);
+      selectionInstance.exit();
+      bulkOpenUrls(urls);
+    } catch (error) {
+      console.error('Bulk analyze error:', error);
+      if (window.toast) window.toast.error('Failed to start bulk analysis: ' + error.message);
+    }
   }
 
   // ─── Event Delegation ───────────────────────────────────────────────────────

package/public/js/local.js

@@ -75,11 +75,12 @@ class LocalManager {
       try {
         // Fetch repo settings so we honour the repository's default provider/council
         const manager = window.prManager;
-        const [repoSettings, reviewSettings] = await Promise.all([
+        const [repoSettings, reviewSettings, appConfig] = await Promise.all([
           manager.fetchRepoSettings().catch(() => null),
-          manager.fetchLastReviewSettings().catch(() => ({ custom_instructions: '', last_council_id: null }))
+          manager.fetchLastReviewSettings().catch(() => ({ custom_instructions: '', last_council_id: null })),
+          manager._getAppConfig()
         ]);
-        const config = await manager._buildDefaultAnalysisConfig(repoSettings, reviewSettings);
+        const config = await manager._buildDefaultAnalysisConfig(repoSettings, reviewSettings, appConfig);
 
         await this.startLocalAnalysis(null, config);
       } finally {
@@ -268,11 +269,25 @@ class LocalManager {
           ? manager._stalenessPromise
           : self._fetchLocalStaleness();
         manager._stalenessPromise = null; // consume it
+        // Pass owner+repo to /api/config (when we have a remote) so
+        // has_github_token reflects the repo's actual auth — covers
+        // repo-scoped tokens, token_command, and alt-host bindings.
+        // Local sessions without a remote origin fall back to the
+        // global-only response (has_global_github_token), which the
+        // modal already treats as no-GitHub-auth for dedup purposes.
+        let configUrl = '/api/config';
+        const localRepo = self.localData?.repository;
+        if (typeof localRepo === 'string' && localRepo.includes('/')) {
+          const [lOwner, lRepo] = localRepo.split('/');
+          if (lOwner && lRepo) {
+            configUrl = `/api/config?owner=${encodeURIComponent(lOwner)}&repo=${encodeURIComponent(lRepo)}`;
+          }
+        }
         const [staleResult, repoSettings, reviewSettings, appConfig] = await Promise.all([
           staleCheckWithTimeout,
           manager.fetchRepoSettings().catch(() => null),
           manager.fetchLastReviewSettings().catch(() => ({ custom_instructions: '', last_council_id: null })),
-          fetch('/api/config').then(r => r.ok ? r.json() : {}).catch(() => ({}))
+          fetch(configUrl).then(r => r.ok ? r.json() : {}).catch(() => ({}))
         ]);
         console.debug(`[Analyze] parallel-fetch (stale+settings): ${Math.round(performance.now() - _tParallel0)}ms`);
 
@@ -310,9 +325,14 @@ class LocalManager {
 
         const lastCouncilId = reviewSettings.last_council_id;
 
-        // Determine model and provider (priority: repo default > defaults)
-        const currentModel = repoSettings?.default_model || 'opus';
-        const currentProvider = repoSettings?.default_provider || 'claude';
+        // Resolve provider and model as a MATCHED pair so the council/advanced tabs
+        // are never seeded with a cross-provider model (e.g. gemini + opus), which
+        // would blank the model <select> and be rejected by the backend.
+        const providersInfo = await manager._getProvidersInfo();
+        const { provider: currentProvider, model: currentModel } = window.resolveProviderModelPair([
+          { provider: repoSettings?.default_provider, model: repoSettings?.default_model },
+          { provider: appConfig.default_provider, model: appConfig.default_model }
+        ], providersInfo);
 
         // Determine default tab (priority: localStorage > repo settings > 'single')
         const tabStorageKey = `pair-review-tab:local-${reviewId}`;
@@ -340,7 +360,14 @@ class LocalManager {
           lastCouncilId,
           defaultCouncilId: repoSettings?.default_council_id || null,
           hasPr: false,
-          hasGithubToken: Boolean(appConfig.has_github_token)
+          // Prefer the repo-aware field when present (we passed owner+repo
+          // to /api/config). For local sessions without a remote origin
+          // we fall back to the global capability — there is no repo
+          // binding to honour, so the global token is the only token a
+          // dedup operation could use anyway.
+          hasGithubToken: Boolean(
+            appConfig.has_github_token ?? appConfig.has_global_github_token
+          )
         });
 
         if (!config) {
@@ -1046,6 +1073,29 @@ class LocalManager {
       // Update header with local info
       this.updateLocalHeader(reviewData);
 
+      // Apply per-repo header link customisation (Phase 7: alt-host support).
+      // Only render the external link when the local review is associated
+      // with a `repos` entry — i.e. the stored repository looks like
+      // `owner/repo`. Local sessions without a remote origin skip this
+      // entirely; built-in GitHub/Graphite links don't appear in Local
+      // mode's header today so suppression has no visible effect there
+      // either, but we still call through so any external link is
+      // inserted into the icon group.
+      if (window.RepoLinks && typeof reviewData.repository === 'string'
+          && reviewData.repository.includes('/')) {
+        const [linkOwner, linkRepo] = reviewData.repository.split('/');
+        window.RepoLinks.fetchAndApplyRepoLinks(linkOwner, linkRepo, {
+          owner: linkOwner,
+          repo: linkRepo,
+          // {number} is intentionally omitted for Local mode — templates
+          // that require it will fail substitution and the link will be
+          // dropped. Local reviews are not associated with a PR number.
+          branch: reviewData.branch,
+          base_branch: reviewData.baseBranch,
+          head_sha: reviewData.localHeadSha,
+        });
+      }
+
       // Fetch and display diff
       await this.loadLocalDiff();
 
@@ -1404,6 +1454,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 +1521,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'
         });

package/public/js/modules/cancel-background-job.js

@@ -0,0 +1,183 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared frontend helpers for cancelling in-flight background jobs
+ * (tour and summaries). Both flows share the same dialog -> POST ->
+ * reset-button-state shape, so the per-artifact wrappers stay thin.
+ *
+ * Backend contract (see src/routes/reviews.js handleJobCancel):
+ *   POST /api/reviews/:reviewId/jobs/:jobKey/cancel
+ *   200 -> { cancelled: true, count: N }
+ *   404 -> { cancelled: false }   (nothing in flight)
+ *   400 -> invalid jobKey
+ *
+ * Local-mode parity: the local route at
+ *   POST /api/local/:reviewId/jobs/:jobKey/cancel
+ * is a thin wrapper. Both modes share the `reviews` table, so we can
+ * use ONE endpoint here. Local mode is detected via document.body.dataset
+ * to keep this module independent of PRManager internals.
+ */
+
+(function () {
+  'use strict';
+
+  /**
+   * POST the cancel request for a single (reviewId, jobKey) pair.
+   * Returns a Promise resolving to the parsed JSON response.
+   *
+   * @param {number|string} reviewId
+   * @param {string} jobKey - bare prefix (`tour` | `summaries`) or full
+   *   suffix (`summaries:<digest>`); the backend treats bare prefixes as
+   *   "cancel all matching".
+   * @returns {Promise<{ok: boolean, status: number, body: any}>}
+   */
+  async function postCancel(reviewId, jobKey) {
+    if (!reviewId) {
+      return { ok: false, status: 0, body: { error: 'missing reviewId' } };
+    }
+    // Both modes share the /api/reviews/... endpoint thanks to the
+    // shared reviews table. No need to branch on local-vs-PR mode here.
+    const url = `/api/reviews/${reviewId}/jobs/${encodeURIComponent(jobKey)}/cancel`;
+    try {
+      const resp = await fetch(url, { method: 'POST' });
+      let body = null;
+      try {
+        body = await resp.json();
+      } catch {
+        body = null;
+      }
+      return { ok: resp.ok, status: resp.status, body };
+    } catch (err) {
+      // Network or unexpected fetch error — log and surface as failure.
+      // We deliberately do not toast here so callers can decide the UX.
+      // eslint-disable-next-line no-console
+      console.warn(`[cancel-background-job] POST ${url} failed:`, err);
+      return { ok: false, status: 0, body: { error: err && err.message } };
+    }
+  }
+
+  /**
+   * Open the shared ConfirmDialog with cancel-job copy, then on confirm
+   * POST the cancel and invoke the caller's `onCancelled` callback so it
+   * can sync UI state (button class toggles, in-memory `_generating`
+   * flags, etc.).
+   *
+   * The caller's `onCancelled` runs only when the backend confirms the
+   * cancel reached a terminal state: 200 (cancelled) or 404 (already gone).
+   * For any other HTTP status (400 validation, 500 server error, etc.) or
+   * a network failure, we toast an error and leave the active state intact
+   * so the pulse stays visible and the user can retry the cancel click.
+   *
+   * @param {Object} opts
+   * @param {number|string} opts.reviewId
+   * @param {string} opts.jobKey  - `tour` or `summaries`
+   * @param {string} opts.title   - Dialog title (e.g. "Tour is still generating")
+   * @param {string} opts.message - Dialog body
+   * @param {string} opts.confirmText - Confirm button label (e.g. "Cancel Tour")
+   * @param {Function} opts.onCancelled - Called after a confirmed cancel.
+   * @returns {Promise<void>}
+   */
+  async function showCancelJobDialog(opts) {
+    const { reviewId, jobKey, title, message, confirmText, onCancelled } = opts || {};
+    const dialog = typeof window !== 'undefined' ? window.confirmDialog : null;
+    if (!dialog || typeof dialog.show !== 'function') {
+      // ConfirmDialog hasn't initialized yet — bail silently. The button
+      // still works on its second click (after DOMContentLoaded fires).
+      return;
+    }
+    const result = await dialog.show({
+      title: title || 'Generation in progress',
+      message: message || 'Cancel this job?',
+      confirmText: confirmText || 'Cancel',
+      confirmClass: 'btn-danger',
+      cancelText: 'OK',
+    });
+    if (result !== 'confirm') return;
+
+    const { status, body } = await postCancel(reviewId, jobKey);
+    // ONLY 200 (cancelled) and 404 (already gone) are UI-clearing outcomes.
+    // Anything else (400, 500, 503, network failure with status=0) means
+    // the job may still be running — keep the pulse, toast an error, and
+    // let the user re-click to retry.
+    if (status !== 200 && status !== 404) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[cancel-background-job] cancel failed for ${jobKey} (status ${status}):`,
+        body
+      );
+      if (typeof window !== 'undefined' && window.toast?.error) {
+        const detail = body && body.error ? `: ${body.error}` : '';
+        const msg = status === 0
+          ? 'Failed to cancel — check connection'
+          : `Failed to cancel (HTTP ${status})${detail}`;
+        window.toast.error(msg);
+      }
+      return;
+    }
+    // 200 or 404 — terminal. Reset UI state.
+    if (typeof onCancelled === 'function') {
+      try {
+        onCancelled({ cancelled: status === 200 && body && body.cancelled, status });
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn('[cancel-background-job] onCancelled handler threw:', err);
+      }
+    }
+  }
+
+  // ---- Per-artifact wrappers (thin convenience layer) --------------------
+
+  /**
+   * Open the "Cancel Tour" confirm dialog.
+   * @param {Object} opts
+   * @param {number|string} opts.reviewId
+   * @param {Function} opts.onCancelled
+   * @returns {Promise<void>}
+   */
+  function showCancelTourDialog(opts) {
+    return showCancelJobDialog({
+      reviewId: opts.reviewId,
+      jobKey: 'tour',
+      title: 'Tour is still being generated',
+      message:
+        'A guided tour is still being generated for this review. ' +
+        'Cancelling will stop the upstream AI call.',
+      confirmText: 'Cancel Tour',
+      onCancelled: opts.onCancelled,
+    });
+  }
+
+  /**
+   * Open the "Cancel Summaries" confirm dialog.
+   * @param {Object} opts
+   * @param {number|string} opts.reviewId
+   * @param {Function} opts.onCancelled
+   * @returns {Promise<void>}
+   */
+  function showCancelSummariesDialog(opts) {
+    return showCancelJobDialog({
+      reviewId: opts.reviewId,
+      jobKey: 'summaries',
+      title: 'Summaries are still being generated',
+      message:
+        'Hunk summaries are still being generated for this review. ' +
+        'Cancelling will stop the upstream AI call. Summaries already ' +
+        'persisted will remain.',
+      confirmText: 'Cancel Summaries',
+      onCancelled: opts.onCancelled,
+    });
+  }
+
+  const api = {
+    postCancel,
+    showCancelJobDialog,
+    showCancelTourDialog,
+    showCancelSummariesDialog,
+  };
+
+  if (typeof window !== 'undefined') {
+    window.CancelBackgroundJob = api;
+  }
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = api;
+  }
+})();

package/public/js/modules/hunk-summary-renderer.js

@@ -0,0 +1,116 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * HunkSummaryRenderer - Renders inline natural-language hunk summaries.
+ *
+ * A summary is a short natural-language description of a non-trivial hunk,
+ * generated by a background AI job. Renderer responsibilities:
+ *   - Insert a styled annotation row immediately above the hunk's first code row
+ *   - Keep the mounted-row map in sync so re-renders update text in place
+ *   - Remove an annotation when its underlying hunk goes away (file re-render)
+ *
+ * Visibility is controlled outside the renderer via CSS classes:
+ *   - body.summaries-hidden                    — review-level toggle
+ *   - .d2h-file-wrapper.summaries-hidden-file  — per-file toggle
+ *
+ * Trivial / model-skipped / model-malformed rows are filtered out by the
+ * caller; this renderer only handles rows with non-empty `summary_text`.
+ */
+
+class HunkSummaryRenderer {
+  /**
+   * @param {Object} prManager - PRManager instance (kept for future callbacks).
+   */
+  constructor(prManager) {
+    this.prManager = prManager;
+    // Map<contentHash, HTMLTableRowElement> — annotation rows currently mounted
+    this._mounted = new Map();
+  }
+
+  /**
+   * Render a summary inline, immediately above its hunk anchor row.
+   * Idempotent: if a summary for the same hash is already mounted, replace
+   * its text rather than stack a duplicate.
+   *
+   * @param {HTMLTableRowElement} anchorRow - The first code-line `<tr>` of
+   *   the target hunk (carries `data-hunk-start="${contentHash}"`).
+   * @param {Object} summary - Summary object: { content_hash, summary_text }.
+   * @param {Object} [_opts] - Reserved for future per-render options.
+   * @returns {HTMLTableRowElement|null}
+   */
+  renderInline(anchorRow, summary, _opts) {
+    if (!anchorRow || !summary || !summary.summary_text) return null;
+    const contentHash = summary.content_hash;
+    if (!contentHash) return null;
+
+    const existing = this._mounted.get(contentHash);
+    if (existing && existing.isConnected) {
+      const textEl = existing.querySelector('.hunk-summary-text');
+      if (textEl) textEl.textContent = summary.summary_text;
+      return existing;
+    }
+
+    const row = document.createElement('tr');
+    row.className = 'hunk-summary-row';
+    row.dataset.contentHash = contentHash;
+
+    const cell = document.createElement('td');
+    cell.colSpan = 2;
+    cell.className = 'hunk-summary-cell';
+
+    const annotation = document.createElement('div');
+    annotation.className = 'hunk-summary-annotation';
+
+    const icon = document.createElement('span');
+    icon.className = 'hunk-summary-icon';
+    icon.setAttribute('aria-hidden', 'true');
+    icon.innerHTML = '<svg viewBox="0 0 16 16" width="14" height="14" fill="currentColor">' +
+      '<path d="M0 3.75C0 2.784.784 2 1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0 1 14.25 14H1.75A1.75 1.75 0 0 1 0 12.25Zm1.75-.25a.25.25 0 0 0-.25.25v8.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25ZM3.5 6.25a.75.75 0 0 1 .75-.75h7a.75.75 0 0 1 0 1.5h-7a.75.75 0 0 1-.75-.75Zm.75 2.25h4a.75.75 0 0 1 0 1.5h-4a.75.75 0 0 1 0-1.5Z"/>' +
+      '</svg>';
+
+    const text = document.createElement('span');
+    text.className = 'hunk-summary-text';
+    text.textContent = summary.summary_text;
+
+    annotation.appendChild(icon);
+    annotation.appendChild(text);
+    cell.appendChild(annotation);
+    row.appendChild(cell);
+
+    // Insert IMMEDIATELY ABOVE the hunk's first code line so a reader
+    // scrolling down sees the description before the change itself.
+    anchorRow.parentNode.insertBefore(row, anchorRow);
+    this._mounted.set(contentHash, row);
+    return row;
+  }
+
+  /**
+   * Remove a mounted annotation by its content hash.
+   * @param {string} contentHash
+   * @returns {boolean} true if a row was found and removed
+   */
+  removeByHash(contentHash) {
+    const row = this._mounted.get(contentHash);
+    if (!row) return false;
+    if (row.isConnected) row.remove();
+    this._mounted.delete(contentHash);
+    return true;
+  }
+
+  /**
+   * Clear all mounted annotations (e.g. before re-rendering the diff).
+   */
+  reset() {
+    for (const row of this._mounted.values()) {
+      if (row.isConnected) row.remove();
+    }
+    this._mounted.clear();
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.HunkSummaryRenderer = HunkSummaryRenderer;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { HunkSummaryRenderer };
+}