npm - diffninja - Versions diffs - 0.3.1 → 0.4.0 - Mend

diffninja 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

package/README.md +65 -11
package/dist/executables.d.ts +18 -0
package/dist/executables.js +32 -0
package/dist/git.d.ts +26 -1
package/dist/git.js +56 -4
package/dist/languages/child-env.d.ts +11 -0
package/dist/languages/child-env.js +60 -0
package/dist/languages/grammar-lock.d.ts +569 -0
package/dist/languages/grammar-lock.js +574 -0
package/dist/languages/grammars.d.ts +69 -9
package/dist/languages/grammars.js +186 -119
package/dist/review/call-flow-html.d.ts +3 -1
package/dist/review/call-flow-html.js +13 -11
package/dist/review/change-facts.d.ts +21 -1
package/dist/review/change-facts.js +271 -49
package/dist/review/cli.js +13 -1
package/dist/review/connected-analysis.d.ts +4 -1
package/dist/review/connected-analysis.js +4 -2
package/dist/review/connected-html.d.ts +15 -4
package/dist/review/connected-html.js +342 -35
package/dist/review/connected.js +47 -14
package/dist/review/escape-html.d.ts +5 -1
package/dist/review/escape-html.js +7 -2
package/dist/review/explanation.d.ts +4 -0
package/dist/review/explanation.js +6 -1
package/dist/review/github.d.ts +56 -0
package/dist/review/github.js +234 -33
package/dist/review/grammars-command.d.ts +12 -0
package/dist/review/grammars-command.js +60 -0
package/dist/review/hidden-characters.d.ts +31 -0
package/dist/review/hidden-characters.js +113 -0
package/dist/review/history.js +7 -3
package/dist/review/html.d.ts +3 -2
package/dist/review/html.js +19 -18
package/dist/review/input.js +5 -2
package/dist/review/intent.d.ts +7 -0
package/dist/review/intent.js +25 -3
package/dist/review/markdown.js +11 -0
package/dist/review/mcp-cli.js +4 -1
package/dist/review/mcp.d.ts +7 -1
package/dist/review/mcp.js +145 -59
package/dist/review/pipeline.d.ts +2 -1
package/dist/review/pipeline.js +4 -3
package/dist/review/pr-input.d.ts +7 -0
package/dist/review/pr-input.js +25 -3
package/dist/review/process-html.d.ts +1 -5
package/dist/review/process-html.js +3 -12
package/dist/review/questions.js +11 -3
package/dist/review/reference-check.d.ts +5 -1
package/dist/review/reference-check.js +40 -16
package/dist/review/report-pages.d.ts +24 -9
package/dist/review/report-pages.js +111 -28
package/dist/review/result-budget.d.ts +28 -0
package/dist/review/result-budget.js +136 -0
package/dist/review/service.js +26 -2
package/dist/review/setup.d.ts +1 -1
package/dist/review/setup.js +9 -4
package/dist/review/types.d.ts +19 -5
package/dist/review/types.js +2 -1
package/dist/review/update-check.d.ts +35 -0
package/dist/review/update-check.js +76 -0
package/dist/run.js +11 -5
package/npm-shrinkwrap.json +3483 -0
package/package.json +3 -2

package/dist/review/connected-html.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { BRAND_MARK, BRAND_MARK_STYLES } from "./brand.js";
 import { PALETTE_STYLES } from "./palette.js";
 import { escapeHtml } from "./escape-html.js";
+import { HIDDEN_CHARACTER_FALLBACK_SOURCE, HIDDEN_CHARACTER_SOURCE } from "./hidden-characters.js";
 /**
  * The one page the connected session serves.
  *
@@ -8,17 +9,25 @@ import { escapeHtml } from "./escape-html.js";
  * draft to `/api/preview`, and posts the same payload to `/api/submit`. Every
  * string that comes from GitHub (paths, diff lines, the diff text itself, error
  * messages) reaches the DOM through `textContent`; nothing is interpolated into
- * markup or into the script. Style and script carry the session CSRF token as
- * their CSP nonce, so the server can serve a `default-src 'none'` policy with
- * no inline handlers and no inline styles.
+ * markup or into the script. Style and script carry a per-response nonce, so the
+ * server can serve a `default-src 'none'` policy with no inline handlers and no
+ * inline styles; the session's CSRF token is a different secret, and the whole
+ * page lives under the session's secret path prefix.
  *
  * Drafts live in `sessionStorage`, keyed per pull request and stamped with the
  * snapshot id. Restoring a draft revalidates every comment anchor against the
  * snapshot on screen: a comment whose line no longer exists in the new revision
  * is dropped, never silently carried over.
+ *
+ * A change is viewed only by the reader's click on its rail checkbox, never by
+ * scrolling. GitHub's Viewed mark is per file, so the page marks a file Viewed
+ * on GitHub (`POST api/viewed`) exactly when every hunk of it is viewed, and
+ * un-marks it when one is not. Progress inside a file stays in `sessionStorage`,
+ * keyed by snapshot id.
  */
-export function renderConnectedPage(csrf) {
-    const nonce = escapeHtml(csrf);
+export function renderConnectedPage(options) {
+    const { csrf, base } = options;
+    const nonce = escapeHtml(options.nonce);
     return [
         "<!doctype html>",
         '<html lang="en">',
@@ -36,6 +45,7 @@ export function renderConnectedPage(csrf) {
         `<p class="brand">${BRAND_MARK}<span>diffninja</span></p>`,
         '<h1 id="page-title">Pull request review</h1>',
         '<p id="page-meta" class="page-meta" hidden></p>',
+        '<p id="update-notice" class="update-notice" role="status" hidden></p>',
         '<section id="pr-goal" class="pr-goal" aria-labelledby="pr-goal-heading" hidden>',
         '<h2 id="pr-goal-heading" class="pr-goal-heading">Goal</h2>',
         '<p id="pr-goal-text" class="pr-goal-text"></p>',
@@ -83,7 +93,9 @@ export function renderConnectedPage(csrf) {
         '<header class="rail-head">',
         '<h2 id="analysis-heading">Reading order</h2>',
         '<p id="analysis-sub" class="rail-sub"></p>',
-        '<p id="rail-progress" class="rail-progress" hidden><span id="rail-at"></span><span class="rail-keys"><kbd>j</kbd> <kbd>k</kbd> next and previous</span></p>',
+        '<p id="rail-progress" class="rail-progress" hidden><span id="rail-at"></span><span class="rail-keys"><kbd>j</kbd> <kbd>k</kbd> next and previous</span><span id="rail-viewed-count" class="rail-viewed-count"></span></p>',
+        '<p id="rail-sync-note" class="rail-note" hidden></p>',
+        '<p id="rail-viewed-error" class="rail-note is-error" role="alert" hidden></p>',
         '<div id="analysis-actions" class="rail-actions"></div>',
         "</header>",
         '<div id="analysis-body" class="rail-body"></div>',
@@ -177,13 +189,13 @@ export function renderConnectedPage(csrf) {
         "</div>",
         '<iframe id="flow-frame" class="flow-frame" title="Call flow"></iframe>',
         "</aside>",
-        `<script nonce="${nonce}">${script(csrf)}</script>`,
+        `<script nonce="${nonce}">${script(csrf, base)}</script>`,
         "</body>",
         "</html>",
         "",
     ].join("\n");
 }
-function script(csrf) {
+function script(csrf, base) {
     // The nonce doubles as a JS string literal; `\u003c` keeps a hostile value
     // from closing the surrounding script element.
     return `
@@ -191,6 +203,8 @@ function script(csrf) {
   'use strict';
   var CSRF = ${JSON.stringify(csrf).replaceAll("<", "\\u003c")};
+  // Every request goes under the session's secret prefix; without it the server answers 404.
+  var BASE = ${JSON.stringify(base).replaceAll("<", "\\u003c")};
   var DRAFT_PREFIX = 'diffninja.connected.draft.v1';
   var state = null;
@@ -227,21 +241,40 @@ function script(csrf) {
   var stopsNow = [];
   var currentRank = 0;
   var followedRank = 0;
-  var seenRanks = Object.create(null);
-  var seenFor = '';
+  var DRAFT_VIEWED_PREFIX = 'diffninja.connected.viewed.v1';
+  var viewedHunks = Object.create(null);
+  var viewedFor = '';
+  var viewedDirty = true;
+  var viewedError = '';
+  var fileSync = Object.create(null);
   var el = {};
   function byId(id) { return document.getElementById(id); }
+  // Bidirectional and other invisible control characters would let untrusted text reorder or hide
+  // what the reviewer reads; every string from the pull request is shown with visible markers instead.
+  var HIDDEN;
+  try {
+    HIDDEN = new RegExp(${JSON.stringify(HIDDEN_CHARACTER_SOURCE).replaceAll("<", "\\u003c")}, 'gu');
+  } catch (unsupported) {
+    // A browser that cannot compile the lookbehind marks every such character rather than lose the page.
+    HIDDEN = new RegExp(${JSON.stringify(HIDDEN_CHARACTER_FALLBACK_SOURCE)}, 'gu');
+  }
+  function visible(value) {
+    return String(value).replace(HIDDEN, function (character) {
+      return '\u27E6U+' + character.codePointAt(0).toString(16).toUpperCase().padStart(4, '0') + '\u27E7';
+    });
+  }
   function make(tag, className, textValue) {
     var node = document.createElement(tag);
     if (className) node.className = className;
-    if (textValue !== undefined && textValue !== null) node.textContent = String(textValue);
+    if (textValue !== undefined && textValue !== null) node.textContent = visible(textValue);
     return node;
   }
   function setText(node, value) {
-    node.textContent = value === undefined || value === null ? '' : String(value);
+    node.textContent = value === undefined || value === null ? '' : visible(value);
   }
   function show(node, visible) { node.hidden = !visible; }
@@ -321,6 +354,7 @@ function script(csrf) {
       return;
     }
     state = next;
+    viewedDirty = true;
     var snap = snapshot();
     if (snap) restoreDraft(snap);
   }
@@ -490,7 +524,7 @@ function script(csrf) {
       init.headers['X-Diffninja-CSRF'] = CSRF;
       init.body = JSON.stringify(payload === undefined ? {} : payload);
     }
-    return fetch(path, init).then(function (response) {
+    return fetch(BASE + (path.charAt(0) === '/' ? path.slice(1) : path), init).then(function (response) {
       return response.text().then(function (raw) {
         var data = null;
         if (raw) {
@@ -942,7 +976,7 @@ function script(csrf) {
       if (!node || typeof node !== 'object') continue;
       var type = typeof node.t === 'string' ? node.t : '';
       if (type === 'text') {
-        if (typeof node.v === 'string') host.appendChild(document.createTextNode(node.v));
+        if (typeof node.v === 'string') host.appendChild(document.createTextNode(visible(node.v)));
         continue;
       }
       if (type === 'code') {
@@ -973,7 +1007,7 @@ function script(csrf) {
         continue;
       }
       // Anything this page does not know is shown as its own text.
-      if (typeof node.v === 'string') host.appendChild(document.createTextNode(node.v));
+      if (typeof node.v === 'string') host.appendChild(document.createTextNode(visible(node.v)));
     }
   }
@@ -1104,6 +1138,19 @@ function script(csrf) {
    * nothing rather than a stale goal — and when none was recorded the block
    * says so instead of describing the pull request itself.
    */
+  /** A newer diffninja exists: one line with the command, from the analysis the page already polls. */
+  function renderUpdate() {
+    var current = currentAnalysis();
+    var u = current && current.update && typeof current.update === 'object' ? current.update : null;
+    var valid = u && typeof u.latest === 'string' && typeof u.current === 'string' && typeof u.command === 'string';
+    el.updateNotice.textContent = '';
+    show(el.updateNotice, Boolean(valid));
+    if (!valid) return;
+    el.updateNotice.appendChild(document.createTextNode('diffninja ' + u.latest + ' is available (you have ' + u.current + '). Update by running '));
+    el.updateNotice.appendChild(make('code', '', u.command));
+    el.updateNotice.appendChild(document.createTextNode(' in a terminal, then restart your agent.'));
+  }
   function renderGoal() {
     var snap = snapshot();
     // A revision that cannot be reviewed gets no goal block: there is nothing to aim the reading at.
@@ -1146,7 +1193,7 @@ function script(csrf) {
     var by = typeof explanation.explainedBy === 'string' && explanation.explainedBy.trim() !== '' ? explanation.explainedBy.trim() : 'your review agent';
     var processes = Array.isArray(explanation.processes) ? explanation.processes.length : 0;
     setText(el.prHowBy, 'Explained by ' + by + ' from the code: ' + processes + (processes === 1 ? ' process' : ' processes') + ' and ' + (explanation.rules || 0) + ((explanation.rules || 0) === 1 ? ' business rule' : ' business rules') + '. Its reading, not a verdict; the diff below is the ground truth.');
-    var src = '/flow?snapshot=' + encodeURIComponent(current.snapshotId) + '&view=business';
+    var src = BASE + 'flow?snapshot=' + encodeURIComponent(current.snapshotId) + '&view=business';
     if (el.prHowFrame.getAttribute('src') !== src) el.prHowFrame.setAttribute('src', src);
   }
@@ -1268,6 +1315,7 @@ function script(csrf) {
     var entry = make('li', 'order-item');
     entry.dataset.action = 'goto-stop';
     entry.dataset.rank = String(rank);
+    entry.dataset.hunk = String(hunk.id);
     entry.dataset.path = String(hunk.file);
     entry.dataset.line = String(hunk.line);
     entry.dataset.side = hunk.side === 'LEFT' ? 'LEFT' : 'RIGHT';
@@ -1287,6 +1335,7 @@ function script(csrf) {
     jump.dataset.rank = entry.dataset.rank;
     main.appendChild(jump);
     entry.appendChild(main);
+    entry.appendChild(viewedBox(hunk, rank));
     return entry;
   }
@@ -1382,11 +1431,13 @@ function script(csrf) {
     var snap = snapshot();
     // The goal rides on the analysis, so it re-renders wherever the analysis does — every poll included.
     renderGoal();
+    renderUpdate();
     renderHow();
     show(el.analysisSection, Boolean(snap) && !(typeof snap.unavailableReason === 'string' && snap.unavailableReason !== ''));
     el.analysisBody.textContent = '';
     el.analysisActions.textContent = '';
     setText(el.analysisSub, '');
+    clearViewedNotes();
     renderAnalysisDetails(currentAnalysis());
     if (!snap) return;
     if (!analysis || analysisFor !== snap.id) {
@@ -1416,10 +1467,12 @@ function script(csrf) {
       el.analysisBody.appendChild(make('p', 'inline-note', 'No call-flow diagrams: ' + analysis.scope.note.replace(/^Patch-only: /, '')));
     }
     if (!el.flowDrawer.hidden && flowSnapshot !== analysis.snapshotId) closeFlow();
+    if (viewedDirty || viewedFor !== snap.id) adoptViewed();
     var list = make('ol', 'order-list');
     var hunks = Array.isArray(analysis.hunks) ? analysis.hunks : [];
     for (var h = 0; h < hunks.length; h += 1) list.appendChild(renderHunkEntry(hunks[h], h + 1));
     el.analysisBody.appendChild(list);
+    paintViewed();
   }
   function gotoLine(node) {
@@ -1445,6 +1498,211 @@ function script(csrf) {
     if (action) action.focus({ preventScroll: true });
   }
+  /* ------------------------------------------------------------- viewed -- */
+  function viewedStoreKey(snap) { return DRAFT_VIEWED_PREFIX + '|' + snap.id; }
+  /** The tab's own viewed flags for one snapshot, hunk id to true; none when storage is unusable. */
+  function readViewedStore(snap) {
+    var flags = Object.create(null);
+    var store = storage();
+    if (!store) return flags;
+    try {
+      var stored = JSON.parse(store.getItem(viewedStoreKey(snap)) || '[]');
+      if (Array.isArray(stored)) {
+        for (var i = 0; i < stored.length; i += 1) {
+          if (typeof stored[i] === 'string') flags[stored[i]] = true;
+        }
+      }
+    } catch (error) {
+      /* Unreadable or blocked: this tab starts with none marked. */
+    }
+    return flags;
+  }
+  function saveViewedStore() {
+    var snap = snapshot();
+    var store = storage();
+    if (!snap || !store || viewedFor !== snap.id) return;
+    try {
+      store.setItem(viewedStoreKey(snap), JSON.stringify(Object.keys(viewedHunks)));
+    } catch (error) {
+      /* Storage disabled or full: the marks stay in memory. */
+    }
+  }
+  function analysisHunks() {
+    var current = currentAnalysis();
+    return current && Array.isArray(current.hunks) ? current.hunks : [];
+  }
+  function hunksOfFile(path) {
+    return analysisHunks().filter(function (hunk) { return hunk.file === path; });
+  }
+  /** GitHub's Viewed is per file: a file counts as viewed exactly when it has hunks and every one of them is viewed. */
+  function fileViewed(path) {
+    var mine = hunksOfFile(path);
+    return mine.length > 0 && mine.every(function (hunk) { return viewedHunks[hunk.id] === true; });
+  }
+  /** Whether the server could read GitHub's marks, so a click may be mirrored there. */
+  function viewedSynced() {
+    return Boolean(state && state.viewed && state.viewed.available === true);
+  }
+  /**
+   * Bring the flags in line with what the server last knew of GitHub. GitHub wins
+   * per file: a file it calls viewed shows every hunk viewed, and a file it does
+   * not call viewed cannot show all of them. Progress inside a file is the tab's
+   * own and is kept. A file with a request out is left to that request.
+   */
+  function adoptViewed() {
+    var snap = snapshot();
+    if (!snap) return;
+    if (viewedFor !== snap.id) {
+      viewedFor = snap.id;
+      viewedHunks = readViewedStore(snap);
+      fileSync = Object.create(null);
+    }
+    var hunks = analysisHunks();
+    var known = Object.create(null);
+    for (var h = 0; h < hunks.length; h += 1) known[hunks[h].id] = true;
+    for (var id in viewedHunks) {
+      if (known[id] !== true) delete viewedHunks[id];
+    }
+    var files = viewedSynced() && Array.isArray(state.viewed.files) ? state.viewed.files : [];
+    var synced = Object.create(null);
+    for (var f = 0; f < files.length; f += 1) {
+      var entry = files[f];
+      if (!entry || typeof entry.path !== 'string') continue;
+      synced[entry.path] = true;
+      var record = fileSync[entry.path] || (fileSync[entry.path] = { confirmed: false, sending: false, last: '' });
+      if (record.sending) continue;
+      record.confirmed = entry.viewed === true;
+      var mine = hunksOfFile(entry.path);
+      if (record.confirmed) {
+        for (var a = 0; a < mine.length; a += 1) viewedHunks[mine[a].id] = true;
+      } else if (fileViewed(entry.path)) {
+        for (var b = 0; b < mine.length; b += 1) delete viewedHunks[mine[b].id];
+      }
+    }
+    for (var path in fileSync) {
+      if (synced[path] !== true) delete fileSync[path];
+    }
+    viewedDirty = false;
+    saveViewedStore();
+  }
+  /** The rail's checkbox for one change: a real button, so it takes focus, Space and Enter. */
+  function viewedBox(hunk, rank) {
+    var box = make('button', 'viewed-box');
+    box.type = 'button';
+    box.dataset.action = 'toggle-viewed';
+    box.dataset.hunk = String(hunk.id);
+    box.setAttribute('role', 'checkbox');
+    box.setAttribute('aria-checked', viewedHunks[hunk.id] === true ? 'true' : 'false');
+    box.setAttribute('aria-label', visible('Mark change ' + rank + ' of ' + hunk.file + ' as viewed'));
+    var mirrored = viewedSynced() && fileSync[hunk.file] !== undefined;
+    box.title = visible(mirrored ? 'Marks the file viewed on GitHub once every change in it is viewed' : 'Kept in this tab only');
+    return box;
+  }
+  /** Repaint the flags in place, so a focused checkbox keeps focus. */
+  function paintViewed() {
+    var stations = el.analysisBody.querySelectorAll('.order-item');
+    var count = 0;
+    for (var i = 0; i < stations.length; i += 1) {
+      var station = stations[i];
+      var on = viewedHunks[station.dataset.hunk] === true;
+      if (on) count += 1;
+      station.classList.toggle('is-viewed', on);
+      var box = station.querySelector('.viewed-box');
+      if (!box) continue;
+      box.setAttribute('aria-checked', on ? 'true' : 'false');
+      var record = fileSync[station.dataset.path];
+      box.classList.toggle('is-pending', Boolean(record && record.sending));
+    }
+    setText(el.railViewedCount, stations.length > 0 ? count + ' of ' + stations.length + ' viewed' : '');
+    var note = '';
+    if (stations.length > 0 && !viewedSynced()) {
+      var reason = state && state.viewed && typeof state.viewed.reason === 'string' && state.viewed.reason !== '' ? state.viewed.reason : 'GitHub did not offer viewed marks';
+      note = 'not synced with GitHub: ' + reason;
+    }
+    setText(el.railSyncNote, note);
+    show(el.railSyncNote, note !== '');
+    setText(el.railViewedError, viewedError);
+    show(el.railViewedError, viewedError !== '');
+  }
+  function clearViewedNotes() {
+    setText(el.railViewedCount, '');
+    setText(el.railSyncNote, '');
+    show(el.railSyncNote, false);
+    setText(el.railViewedError, '');
+    show(el.railViewedError, false);
+  }
+  /** A click on a change's checkbox: flip it here, then mirror the file's new state to GitHub when the file's state changed. */
+  function toggleViewed(hunkId) {
+    var snap = snapshot();
+    var hunk = null;
+    var hunks = analysisHunks();
+    for (var i = 0; i < hunks.length; i += 1) {
+      if (hunks[i].id === hunkId) { hunk = hunks[i]; break; }
+    }
+    if (!snap || !hunk || viewedFor !== snap.id) return;
+    if (viewedHunks[hunkId] === true) delete viewedHunks[hunkId];
+    else viewedHunks[hunkId] = true;
+    viewedError = '';
+    saveViewedStore();
+    var record = fileSync[hunk.file];
+    if (record) record.last = hunkId;
+    syncFile(hunk.file);
+    paintViewed();
+  }
+  /**
+   * Make GitHub's mark of one file match the page. One request per file is out at
+   * a time; a click that lands meanwhile is sent when the answer comes back, so
+   * the file ends in the state of the last click. A request goes out only when
+   * the file's state differs from what GitHub last confirmed.
+   */
+  function syncFile(path) {
+    var snap = snapshot();
+    var record = fileSync[path];
+    if (!snap || !record || record.sending) return;
+    var want = fileViewed(path);
+    if (want === record.confirmed) return;
+    var trigger = record.last;
+    record.sending = true;
+    api('POST', '/api/viewed', { snapshotId: snap.id, path: path, viewed: want }).then(function () {
+      record.sending = false;
+      if (viewedFor !== snap.id) return;
+      record.confirmed = want;
+      // The state the page holds must say what GitHub now says, or the next adoption would undo the click.
+      var files = state && state.viewed && Array.isArray(state.viewed.files) ? state.viewed.files : [];
+      for (var i = 0; i < files.length; i += 1) {
+        if (files[i] && files[i].path === path) files[i].viewed = want;
+      }
+    }, function (error) {
+      record.sending = false;
+      if (viewedFor !== snap.id) return;
+      // Put the click back: GitHub did not take it, so neither does the page.
+      if (want) delete viewedHunks[trigger];
+      else viewedHunks[trigger] = true;
+      viewedError = error && error.message ? error.message : 'The Viewed mark could not be saved.';
+      if (error && error.uncertain) state.viewed = { available: false, reason: 'diffninja did not answer the last Viewed mark' };
+      else if (error && error.state && error.state.viewed && error.state.viewed.available === false) state.viewed = error.state.viewed;
+      viewedDirty = true;
+    }).then(function () {
+      if (viewedDirty) adoptViewed();
+      saveViewedStore();
+      paintViewed();
+      syncFile(path);
+    });
+  }
   /* -------------------------------------------------------- you are here -- */
   var spyQueued = false;
@@ -1498,33 +1756,30 @@ function script(csrf) {
   }
   /**
-   * Mark where the reader is on the rail and what they have read. In the
-   * reading order the stops run 1, 2, 3 down the page, so the rail's list
-   * follows each new one; by file the stations of one file sit far apart in the
-   * reading order, so the list stays where the reader put it.
+   * Mark where the reader is on the rail. In the reading order the stops run 1,
+   * 2, 3 down the page, so the rail's list follows each new one; by file the
+   * stations of one file sit far apart in the reading order, so the list stays
+   * where the reader put it. Position only: nothing here says a change was
+   * viewed, because only the reader's click does.
    */
   function markCurrentStation() {
     spyQueued = false;
     fitRail();
-    var snap = snapshot();
-    if (snap && seenFor !== snap.id) { seenFor = snap.id; seenRanks = Object.create(null); }
     var stations = el.analysisBody.querySelectorAll('.order-item');
     var guided = el.diffBody.querySelector('.stop') !== null;
     currentRank = guided ? currentStopRank() : currentFileRank(stations);
-    // Every change read in the current stop is current, and read.
+    // Every change in the current stop is current.
     var here = Object.create(null);
     var stop = guided ? stopOf(currentRank) : null;
     if (stop) {
       for (var h = 0; h < stop.hunks.length; h += 1) here[stop.hunks[h].rank] = true;
     } else if (currentRank > 0) here[currentRank] = true;
-    for (var seen in here) seenRanks[seen] = true;
     var current = null;
     for (var j = 0; j < stations.length; j += 1) {
       var rank = Number(stations[j].dataset.rank);
       var on = here[rank] === true;
       if (rank === currentRank) current = stations[j];
       stations[j].classList.toggle('is-current', on);
-      stations[j].classList.toggle('is-seen', seenRanks[rank] === true);
       if (on) stations[j].setAttribute('aria-current', 'step');
       else stations[j].removeAttribute('aria-current');
     }
@@ -1738,6 +1993,9 @@ function script(csrf) {
   function codeNode(text, language, state) {
     var code = make('code', 'diff-code');
+    var shown = visible(text);
+    if (shown !== text) code.classList.add('diff-code-hidden');
+    text = shown;
     if (!language || text.length > 2000) { code.textContent = text; return code; }
     var tokens = tokenize(text, language, state);
     for (var t = 0; t < tokens.length; t += 1) {
@@ -1769,7 +2027,7 @@ function script(csrf) {
   function openFlow(path, opener) {
     var current = currentAnalysis();
     if (!current) return;
-    var src = '/flow?snapshot=' + encodeURIComponent(current.snapshotId) + (path === '' ? '' : '&file=' + encodeURIComponent(path));
+    var src = BASE + 'flow?snapshot=' + encodeURIComponent(current.snapshotId) + (path === '' ? '' : '&file=' + encodeURIComponent(path));
     if (el.flowFrame.getAttribute('src') !== src) el.flowFrame.setAttribute('src', src);
     flowSnapshot = current.snapshotId;
     var explained = Boolean(current.explanation);
@@ -1843,7 +2101,10 @@ function script(csrf) {
     for (var i = 0; i < list.length; i += 1) {
       var s = list[i];
       var shaped = s && typeof s === 'object' && typeof s.path === 'string' && typeof s.line === 'number'
-        && (s.side === 'LEFT' || s.side === 'RIGHT') && typeof s.body === 'string' && s.body !== '';
+        && (s.side === 'LEFT' || s.side === 'RIGHT') && typeof s.body === 'string' && s.body !== ''
+        && typeof s.scenario === 'string' && s.scenario !== ''
+        && (s.evidence === 'ran' || s.evidence === 'traced')
+        && typeof s.unlessTrue === 'string' && s.unlessTrue !== '';
       if (!shaped || !currentLine(s) || settled[suggestionKey(current.snapshotId, s)]) continue;
       out.push(s);
     }
@@ -1910,14 +2171,24 @@ function script(csrf) {
     render();
   }
+  /** A suggestion is a claim that the pull request should not merge until it is fixed, so it shows its proof under the comment. */
   function suggestionRow(suggestion, disabled) {
     var wrap = make('div', 'suggestion');
     var head = make('p', 'suggestion-by');
     head.appendChild(make('span', 'agent-dot', ''));
     head.appendChild(make('strong', '', suggestedBy()));
     head.appendChild(document.createTextNode(' suggests'));
+    var badge = make('span', 'blocks-badge', 'Blocks merge');
+    badge.title = 'The agent says this must be fixed before the pull request merges';
+    head.appendChild(badge);
     wrap.appendChild(head);
     wrap.appendChild(make('p', 'suggestion-body', suggestion.body));
+    var proof = make('div', 'suggestion-proof');
+    proof.appendChild(make('p', 'proof-title', 'Why it blocks'));
+    proof.appendChild(make('p', 'proof-scenario', suggestion.scenario));
+    proof.appendChild(make('p', 'proof-evidence', 'Checked: ' + (suggestion.evidence === 'ran' ? 'ran it' : 'traced the code')));
+    proof.appendChild(make('p', 'proof-unless', 'Not a problem if: ' + suggestion.unlessTrue));
+    wrap.appendChild(proof);
     var actions = make('div', 'suggestion-actions');
     var add = make('button', 'btn btn-primary btn-sm', 'Add to review');
     add.type = 'button';
@@ -1952,8 +2223,8 @@ function script(csrf) {
       var said = make('p', '');
       said.appendChild(make('span', 'agent-dot', ''));
       said.appendChild(make('strong', '', suggestedBy()));
-      said.appendChild(document.createTextNode(' suggested ' + open.length + (open.length === 1 ? ' comment' : ' comments')
-        + ' on the lines below. Nothing is posted until you submit.'));
+      said.appendChild(document.createTextNode(' suggested ' + open.length + (open.length === 1 ? ' comment that blocks' : ' comments that block')
+        + ' the merge on the lines below. Nothing is posted until you submit.'));
       bar.appendChild(said);
       var all = make('button', 'btn btn-primary btn-sm', open.length === 1 ? 'Add it to review' : 'Add all ' + open.length);
       all.type = 'button';
@@ -2569,6 +2840,7 @@ function script(csrf) {
     if (action === 'submit') { event_.preventDefault(); submitReview(); return; }
     if (action === 'refresh') { event_.preventDefault(); refreshState(); return; }
     if (action === 'goto') { event_.preventDefault(); gotoLine(node); return; }
+    if (action === 'toggle-viewed') { event_.preventDefault(); toggleViewed(node.getAttribute('data-hunk') || ''); return; }
     if (action === 'goto-stop') { event_.preventDefault(); gotoStop(Number(node.getAttribute('data-rank'))); return; }
     if (action === 'view') { event_.preventDefault(); setView(node.getAttribute('data-view') || ''); return; }
     if (action === 'show-load') { event_.preventDefault(); showLoad = true; render(); el.prUrl.focus(); return; }
@@ -2610,6 +2882,7 @@ function script(csrf) {
     el.refreshButton = byId('refresh-button');
     el.pageTitle = byId('page-title');
     el.pageMeta = byId('page-meta');
+    el.updateNotice = byId('update-notice');
     el.prGoal = byId('pr-goal');
     el.prGoalText = byId('pr-goal-text');
     el.prGoalBy = byId('pr-goal-by');
@@ -2634,6 +2907,9 @@ function script(csrf) {
     el.railFinish = byId('rail-finish');
     el.railProgress = byId('rail-progress');
     el.railAt = byId('rail-at');
+    el.railViewedCount = byId('rail-viewed-count');
+    el.railSyncNote = byId('rail-sync-note');
+    el.railViewedError = byId('rail-viewed-error');
     el.viewSwitch = byId('view-switch');
     view = readView();
     el.analysisActions = byId('analysis-actions');
@@ -2736,6 +3012,7 @@ ${BRAND_MARK_STYLES}
 .page-meta { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 12px; font-size: 13px; color: var(--ink-soft); }
 .page-meta a { font-weight: 600; }
 /* The agent's stated goal, first thing under the masthead: one sentence, with its attribution. */
+.update-notice { padding: 8px 12px; border-left: 3px solid var(--warn); background: var(--warn-soft); border-radius: 4px; font-size: 14px; }
 .pr-goal { margin-top: 6px; padding: 14px 16px; border: 1px solid var(--line); border-left: 3px solid var(--accent); border-radius: var(--radius); background: var(--panel); }
 .pr-goal.is-empty { border-left-color: var(--line-strong); background: var(--sunken); }
 .pr-goal-heading { font-size: 11.5px; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; color: var(--ink-soft); }
@@ -2918,7 +3195,7 @@ button.fact:hover { border-color: var(--accent); background: var(--accent-soft);
 .order-list { list-style: none; margin: 0; padding: 0; }
 /* Stations sit on one continuous line: the route through the pull request. */
 .order-item {
-  position: relative; display: grid; grid-template-columns: 26px minmax(0, 1fr); column-gap: 10px;
+  position: relative; display: grid; grid-template-columns: 26px minmax(0, 1fr) auto; column-gap: 10px;
   padding: 6px 14px 6px 12px; cursor: pointer;
 }
 .order-item::before {
@@ -2926,8 +3203,8 @@ button.fact:hover { border-color: var(--accent); background: var(--accent-soft);
 }
 .order-item:first-child::before { top: 16px; }
 .order-item:last-child::before { bottom: calc(100% - 16px); }
-/* The route fills in behind the reader: a read station and the line after it turn accent. */
-.order-item.is-seen::before { background: var(--accent); opacity: 0.55; }
+/* The route fills in behind what the reader marked viewed: a viewed station and the line after it turn accent. */
+.order-item.is-viewed::before { background: var(--accent); opacity: 0.55; }
 .order-item:hover { background: var(--hover); }
 .order-item:focus-within { outline: 2px solid var(--accent); outline-offset: -2px; }
 .order-rank {
@@ -2936,18 +3213,38 @@ button.fact:hover { border-color: var(--accent); background: var(--accent-soft);
   color: var(--ink-soft); background: var(--panel); border: 2px solid var(--route);
   transition: background 0.15s, border-color 0.15s, color 0.15s;
 }
-.order-item.is-seen .order-rank { color: var(--accent); border-color: var(--accent); }
+.order-item.is-viewed .order-rank { color: var(--accent); border-color: var(--accent); }
 .order-item.is-current { background: var(--accent-soft); }
 .order-item.is-current .order-rank { color: var(--primary-ink); background: var(--accent); border-color: var(--accent); }
+/* A 24px target around a 16px box, drawn in CSS so it needs no glyph and follows the theme. */
+.viewed-box {
+  position: relative; z-index: 1; align-self: center; width: 24px; height: 24px; margin: 0; padding: 0;
+  display: grid; place-items: center; background: transparent; border: 0; border-radius: 6px; cursor: pointer;
+}
+.viewed-box::before {
+  content: ""; width: 16px; height: 16px; box-sizing: border-box; border-radius: 4px;
+  border: 2px solid var(--ink-faint); background: var(--panel); transition: background 0.15s, border-color 0.15s;
+}
+.viewed-box:hover::before { border-color: var(--accent); }
+.viewed-box[aria-checked="true"]::before { background: var(--accent); border-color: var(--accent); }
+.viewed-box[aria-checked="true"]::after {
+  content: ""; position: absolute; width: 4px; height: 8px; margin-top: -2px;
+  border: solid var(--primary-ink); border-width: 0 2px 2px 0; transform: rotate(45deg);
+}
+.viewed-box.is-pending { opacity: 0.55; }
 .order-main { min-width: 0; padding-top: 1px; display: flex; flex-direction: column; gap: 3px; }
 .order-path { display: flex; min-width: 0; font-size: 12.5px; white-space: nowrap; }
 .order-path .path-base { min-width: 0; overflow: hidden; text-overflow: ellipsis; }
 .order-path .path-line { flex: 0 0 auto; }
 .order-path .path-dir { display: none; }
 .order-meta { display: flex; align-items: center; gap: 8px; font-size: 12px; }
-.rail-progress { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-top: 6px; font-size: 12px; color: var(--ink); font-variant-numeric: tabular-nums; }
+.rail-progress { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 2px 8px; margin-top: 6px; font-size: 12px; color: var(--ink); font-variant-numeric: tabular-nums; }
 .rail-progress[hidden] { display: none; }
 .rail-keys { color: var(--ink-faint); white-space: nowrap; }
+.rail-viewed-count { order: 3; flex: 1 0 100%; color: var(--ink-soft); }
+.rail-viewed-count:empty { display: none; }
+.rail-note { margin-top: 4px; font-size: 12px; color: var(--ink-soft); overflow-wrap: anywhere; }
+.rail-note[hidden] { display: none; }
 kbd {
   display: inline-block; min-width: 18px; padding: 0 4px; font: 11px/16px var(--mono); text-align: center;
   color: var(--ink-soft); background: var(--bg); border: 1px solid var(--line); border-bottom-width: 2px; border-radius: 4px;
@@ -3041,6 +3338,7 @@ kbd {
 .diff-action.has-comment { opacity: 1; transform: scale(1); background: var(--warn); }
 .diff-action.is-armed { opacity: 1; transform: scale(1); width: auto; padding: 0 6px; font-size: 11px; color: #fff; }
 .diff-mark { flex: 0 0 auto; width: 20px; text-align: center; color: var(--ink-faint); user-select: none; }
+.diff-code-hidden { outline: 1px solid var(--warn); outline-offset: -1px; background: var(--warn-soft); }
 .diff-code { display: block; flex: 1 1 auto; min-width: 0; padding: 0 12px 0 0; white-space: pre-wrap; overflow-wrap: anywhere; color: var(--ink); }
 .kind-add { background: var(--add-bg); }
 .kind-delete { background: var(--del-bg); }
@@ -3071,9 +3369,18 @@ kbd {
 .editor { border-color: var(--accent); box-shadow: 0 0 0 1px var(--accent-soft); }
 .editor-row { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
 .editor-input { flex: 1 1 240px; min-width: 0; }
-.suggestion-by { font-size: 12px; color: var(--ink-soft); }
+.suggestion-by { display: flex; flex-wrap: wrap; align-items: center; gap: 4px; font-size: 12px; color: var(--ink-soft); }
 .suggestion-by strong { color: var(--ink); font-weight: 600; }
+.blocks-badge {
+  margin-left: 6px; padding: 1px 7px; border-radius: 4px; font-size: 11.5px; font-weight: 600; letter-spacing: 0.02em;
+  color: var(--alarm); background: var(--alarm-bg);
+}
 .suggestion-body { font-size: 14px; line-height: 1.5; overflow-wrap: anywhere; }
+.suggestion-proof {
+  display: flex; flex-direction: column; gap: 2px; padding: 2px 0 2px 10px; border-left: 2px solid var(--line);
+  font-size: 13px; line-height: 1.45; color: var(--ink-soft); overflow-wrap: anywhere;
+}
+.proof-title { font-weight: 600; color: var(--ink); }
 .suggestion-actions { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
 /* ---------------------------------------------------------------- forms */