git-reviewer 2.4.1 → 2.5.0

package/README.md

@@ -162,8 +162,10 @@ shown in full, read back out of `HEAD`:
 | `Escape` | Cancel input |
 | `↑` / `↓` | Move between files |
 
-None of that is guessable, so the review pane says it too, in a **How to
-comment** strip above the diff. Collapse it once and it stays collapsed.
+None of that is guessable — a column of line numbers does not look clickable —
+so the app shows you rather than telling you. **Reviewing, in four moves** opens
+by itself the first time you review anything, and lives behind the `?` in the
+header after that. Each move is a small animation of the gesture itself.
 
 ## What it writes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-reviewer",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Review your coding agent's changes like a pull request — locally, with inline comments and threaded follow-ups, then hand the marked-up review back to the agent",
   "author": "Dheeraj Jha",
   "license": "MIT",

package/public/app.js

@@ -210,6 +210,7 @@ async function loadRepo() {
       const opening = previous === -1 ? 0 : previous;
 
       loadFile(currentFiles[opening].path, opening);
+      offerHelpOnce();
     }
 
   } catch (error) {
@@ -1624,8 +1625,6 @@ document.addEventListener('DOMContentLoaded', () => {
     }
   });
 
-  restoreHowTo();
-
   for (const id of ['recentList', 'browseList']) {
     const list = document.getElementById(id);
     list.addEventListener('click', onPickerActivate);
@@ -1635,7 +1634,14 @@ document.addEventListener('DOMContentLoaded', () => {
   // Escape, and a click on the dimmed area around it, both mean "never mind"
   // -- but only when there is a review behind the picker to go back to.
   document.addEventListener('keydown', event => {
-    if (event.key === 'Escape') closePicker();
+    if (event.key !== 'Escape') return;
+
+    // Topmost first: the help sits over the picker, which sits over a review.
+    if (!document.getElementById('helpModal').classList.contains('hidden')) {
+      closeHelp();
+      return;
+    }
+    closePicker();
   });
 
   document.getElementById('picker').addEventListener('click', event => {
@@ -1883,53 +1889,48 @@ function onPickerActivate(event) {
   if (into) loadBrowse(into.dataset.into);
 }
 
-
-/* How to comment
+/* How to review
  * ---------------------------------------------------------------------------
- * Open until it is dismissed, then remembered as dismissed. A hint that cannot
- * be turned off becomes furniture, and a hint that has to be found is not one.
+ * Shown once, on the first review this browser ever opens, and after that only
+ * when asked for. The gestures here are not guessable -- a column of line
+ * numbers does not look clickable -- but they are learned in one go, and a
+ * panel that keeps explaining them afterwards is furniture.
  */
 
-/** Where the dismissal is remembered. Per browser; it is a convenience, not state. */
-const HOW_TO_KEY = 'reviewer.howTo.collapsed';
+/** Set the first time the help has been seen. Per browser; a convenience, not state. */
+const HELP_SEEN_KEY = 'reviewer.help.seen';
 
-/**
- * @returns {boolean} whether it has been collapsed before
- */
-function howToWasCollapsed() {
+/** @returns {boolean} */
+function helpWasSeen() {
   try {
-    return window.localStorage.getItem(HOW_TO_KEY) === 'true';
+    return window.localStorage.getItem(HELP_SEEN_KEY) === 'true';
   } catch {
-    // A private window, or site data blocked. Showing the hint again is a far
-    // better failure than not rendering the panel at all.
+    // Private window, or site data blocked. Showing it again is the harmless
+    // direction to fail in.
     return false;
   }
 }
 
-/**
- * @param {boolean} collapsed
- */
-function rememberHowTo(collapsed) {
+function openHelp() {
+  document.getElementById('helpModal').classList.remove('hidden');
   try {
-    window.localStorage.setItem(HOW_TO_KEY, String(collapsed));
+    window.localStorage.setItem(HELP_SEEN_KEY, 'true');
   } catch {
-    // Nothing to do. It reopens next time, which is the harmless direction.
+    // Nothing to do; it opens again next time.
   }
 }
 
-function toggleHowTo() {
-  const panel = document.getElementById('howTo');
-  const collapsed = panel.classList.toggle('collapsed');
-
-  document.getElementById('howToToggle').setAttribute('aria-expanded', String(!collapsed));
-  rememberHowTo(collapsed);
+function closeHelp() {
+  document.getElementById('helpModal').classList.add('hidden');
 }
 
-function restoreHowTo() {
-  const panel = document.getElementById('howTo');
-  if (!panel) return;
-
-  const collapsed = howToWasCollapsed();
-  panel.classList.toggle('collapsed', collapsed);
-  document.getElementById('howToToggle').setAttribute('aria-expanded', String(!collapsed));
+/**
+ * Offer it unprompted the first time, once a repository is actually on screen.
+ *
+ * Not at page load: with nothing open there is nothing to apply it to, and it
+ * would be the first thing between somebody and the tool they just started.
+ */
+function offerHelpOnce() {
+  if (helpWasSeen()) return;
+  openHelp();
 }

package/public/index.html

@@ -19,6 +19,13 @@
           <span id="repoButtonLabel">Open a repository</span>
         </button>
 
+        <button id="helpButton" class="icon-button" onclick="openHelp()"
+                title="How to review" aria-label="How to review">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+            <path d="M8 0a8 8 0 100 16A8 8 0 008 0zM6.05 6.04a.75.75 0 01-1.45-.38 3.5 3.5 0 016.86.86c0 1.23-.67 1.93-1.28 2.4l-.13.1c-.61.47-.8.68-.8 1.13a.75.75 0 01-1.5 0c0-1.23.67-1.93 1.28-2.4l.13-.1c.61-.47.8-.68.8-1.13a2 2 0 00-3.91-.48zM9 12.5a1 1 0 11-2 0 1 1 0 012 0z"></path>
+          </svg>
+        </button>
+
         <button
           id="pathToggle"
           class="icon-button"
@@ -81,6 +88,74 @@
       </div>
     </section>
 
+    <div id="helpModal" class="help-modal hidden" onclick="if (event.target.id === 'helpModal') closeHelp()">
+      <div class="help-card" role="dialog" aria-modal="true" aria-labelledby="helpTitle">
+        <div class="help-head">
+          <h2 id="helpTitle">Reviewing, in four moves</h2>
+          <button class="icon-button" onclick="closeHelp()" aria-label="Close">
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+              <path d="M3.72 3.72a.75.75 0 011.06 0L8 6.94l3.22-3.22a.75.75 0 111.06 1.06L9.06 8l3.22 3.22a.75.75 0 11-1.06 1.06L8 9.06l-3.22 3.22a.75.75 0 01-1.06-1.06L6.94 8 3.72 4.78a.75.75 0 010-1.06z"></path>
+            </svg>
+          </button>
+        </div>
+
+        <div class="help-steps">
+          <section class="help-step">
+            <div class="help-demo demo-click" aria-hidden="true">
+              <div class="m-row"><span class="m-num">7</span><span class="m-code"></span></div>
+              <div class="m-row m-target"><span class="m-num">8</span><span class="m-code"></span></div>
+              <div class="m-row"><span class="m-num">9</span><span class="m-code"></span></div>
+              <div class="m-box"></div>
+              <div class="m-cursor"></div>
+            </div>
+            <h3>Click a line number</h3>
+            <p>That is the whole gesture. Deleted lines take comments too — often the
+              most useful note is about code that was removed.</p>
+          </section>
+
+          <section class="help-step">
+            <div class="help-demo demo-select" aria-hidden="true">
+              <div class="m-row"><span class="m-num">8</span><span class="m-code m-long"><span class="m-sel"></span></span></div>
+              <div class="m-quote"></div>
+              <div class="m-cursor"></div>
+            </div>
+            <h3>Hold <kbd>⌘</kbd> and drag to quote</h3>
+            <p>Select part of a line first, then click its number. The exact fragment
+              is quoted in the comment, so there is no ambiguity about what you meant.</p>
+          </section>
+
+          <section class="help-step">
+            <div class="help-demo demo-thread" aria-hidden="true">
+              <div class="m-comment"></div>
+              <div class="m-reply"></div>
+            </div>
+            <h3>Replies thread</h3>
+            <p>Follow up on your own comment as the code changes underneath it.
+              Everything saves as you type — there is no save button.</p>
+          </section>
+
+          <section class="help-step">
+            <div class="help-demo demo-handoff" aria-hidden="true">
+              <div class="m-term"><span class="m-prompt">$</span><span class="m-cmd"></span></div>
+              <div class="m-flow"></div>
+              <div class="m-done">✓</div>
+            </div>
+            <h3>Submit, and it goes back</h3>
+            <p>Run it as <code>reviewer | claude -p "Apply this review."</code> and
+              submitting hands the review straight to the agent, which makes the changes.</p>
+          </section>
+        </div>
+
+        <div class="help-foot">
+          <span class="help-keys">
+            <kbd>⌘</kbd><kbd>Enter</kbd> save · <kbd>Esc</kbd> cancel ·
+            <kbd>↑</kbd><kbd>↓</kbd> move between files
+          </span>
+          <button class="help-done" onclick="closeHelp()">Got it</button>
+        </div>
+      </div>
+    </div>
+
     <aside id="sidebar" class="sidebar hidden">
       <div class="sidebar-header">
         <h2>Changed Files</h2>
@@ -101,28 +176,6 @@
           Full Context
         </button>
       </div>
-      <section id="howTo" class="how-to">
-        <button
-          id="howToToggle"
-          class="how-to-toggle"
-          onclick="toggleHowTo()"
-          aria-expanded="true"
-          aria-controls="howToBody">
-          <span class="how-to-chevron" aria-hidden="true">▾</span>
-          How to comment
-        </button>
-        <div id="howToBody" class="how-to-body">
-          <p><strong>Click a line number</strong> in the left column to comment on that line.
-            Removed lines work too — the most useful note is often about deleted code.</p>
-          <p><strong>Hold <kbd>⌘</kbd>/<kbd>Ctrl</kbd> and drag</strong> to select part of a line,
-            then click the line number. The selection is quoted in the comment.</p>
-          <p><kbd>⌘</kbd>/<kbd>Ctrl</kbd> + <kbd>Enter</kbd> saves ·
-            <kbd>Esc</kbd> cancels ·
-            <kbd>↑</kbd> <kbd>↓</kbd> move between files</p>
-          <p>Everything saves as you type. <strong>Submit Review</strong> when you are done.</p>
-        </div>
-      </section>
-
       <div id="codeViewer" class="code-viewer"></div>
     </main>
 

package/public/style.css

@@ -1367,6 +1367,53 @@ button:disabled {
   align-items: flex-start;
 }
 
+/* Where the review went
+ *
+ * The modal used to offer a download and nothing else, which is an odd thing
+ * to put in front of somebody who started this from a terminal. The review is
+ * already a file; knowing where is more useful than a second copy of it.
+ */
+.review-destination {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  margin-bottom: 14px;
+  padding: 10px 12px;
+  border: 1px solid #e1e4e8;
+  border-radius: 6px;
+  background: #f6f8fa;
+  font-size: 13px;
+  color: #24292e;
+}
+
+.review-destination.handed-off {
+  border-color: #b7e0c2;
+  background: #eefcf1;
+}
+
+.review-destination strong {
+  flex: none;
+  font-weight: 600;
+}
+
+.review-destination span {
+  min-width: 0;
+  color: #57606a;
+}
+
+.review-destination .review-path {
+  /* Wrapped rather than truncated. There is room in a modal, and every way of
+   * shortening a path hides the half somebody wanted: cut the front and the
+   * directory goes, cut the back and the filename goes. */
+  word-break: break-all;
+  font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+  font-size: 12px;
+}
+
+.review-destination {
+  align-items: flex-start;
+}
+
 /* How to comment
  *
  * Nothing on screen said that the column of line numbers was clickable, or
@@ -1448,3 +1495,344 @@ button:disabled {
   color: #24292e;
   text-align: center;
 }
+
+/* How to review
+ *
+ * This was four paragraphs pinned above the diff. It said the right things and
+ * nobody read them, because a wall of prose is what a person skips when they
+ * are trying to get to the code. Showing the gesture takes less attention than
+ * describing it.
+ *
+ * The demos are CSS, not video. Four short clips would be a megabyte in a
+ * package that is currently 55KB, and would be soft on a retina screen; these
+ * are a couple of kilobytes, sharp at any density, and inherit the palette so
+ * they keep matching the app when it changes.
+ */
+.help-modal {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 1100;
+  background: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 32px 24px;
+}
+
+.help-card {
+  width: 100%;
+  max-width: 720px;
+  max-height: calc(100vh - 64px);
+  display: flex;
+  flex-direction: column;
+  background: white;
+  border-radius: 10px;
+  box-shadow: 0 14px 48px rgba(0, 0, 0, 0.28);
+  overflow: hidden;
+}
+
+.help-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 18px 22px;
+  border-bottom: 1px solid #e1e4e8;
+}
+
+.help-head h2 {
+  font-size: 17px;
+  font-weight: 600;
+  color: #24292e;
+}
+
+.help-steps {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 20px;
+  padding: 22px;
+  overflow-y: auto;
+}
+
+.help-step h3 {
+  margin: 12px 0 4px;
+  font-size: 13.5px;
+  font-weight: 600;
+  color: #24292e;
+}
+
+.help-step h3 kbd,
+.help-keys kbd {
+  display: inline-block;
+  min-width: 17px;
+  padding: 0 5px;
+  border: 1px solid #d1d5da;
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  background: #fafbfc;
+  font-family: inherit;
+  font-size: 11px;
+  color: #24292e;
+  text-align: center;
+}
+
+.help-step p {
+  font-size: 12.5px;
+  line-height: 1.55;
+  color: #57606a;
+}
+
+.help-step code {
+  padding: 1px 5px;
+  border-radius: 4px;
+  background: #f0f2f4;
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 11.5px;
+  color: #24292e;
+  white-space: nowrap;
+}
+
+/* The demo stage. Every mock below is built from these few pieces. */
+.help-demo {
+  position: relative;
+  height: 104px;
+  padding: 10px;
+  border: 1px solid #e1e4e8;
+  border-radius: 8px;
+  background: #fbfcfd;
+  overflow: hidden;
+}
+
+.m-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 16px;
+}
+
+.m-num {
+  width: 16px;
+  border-radius: 3px;
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 9px;
+  color: #a0a6ad;
+  text-align: right;
+}
+
+.m-code {
+  height: 5px;
+  width: 62%;
+  border-radius: 3px;
+  background: #dfe3e8;
+}
+
+.m-row:nth-child(2) .m-code { width: 78%; }
+.m-row:nth-child(3) .m-code { width: 48%; }
+
+/* A pointer. One element, moved by each demo's own keyframes. */
+.m-cursor {
+  position: absolute;
+  width: 9px;
+  height: 13px;
+  background: #24292e;
+  clip-path: polygon(0 0, 0 100%, 27% 74%, 46% 96%, 62% 84%, 44% 62%, 100% 58%);
+}
+
+/* 1. Click a line number */
+.demo-click .m-target .m-num { background: transparent; color: #0366d6; }
+.demo-click .m-box {
+  position: absolute;
+  left: 34px;
+  top: 46px;
+  width: 60%;
+  height: 26px;
+  border: 1px solid #0366d6;
+  border-radius: 4px;
+  background: white;
+  opacity: 0;
+  transform: translateY(-3px);
+  animation: m-box-in 4s ease-in-out infinite;
+}
+.demo-click .m-target .m-num { animation: m-num-hit 4s ease-in-out infinite; }
+.demo-click .m-cursor { animation: m-click-path 4s ease-in-out infinite; }
+
+@keyframes m-click-path {
+  0%, 8%    { left: 64px; top: 74px; opacity: 0; }
+  18%       { left: 64px; top: 74px; opacity: 1; }
+  38%, 100% { left: 14px; top: 26px; opacity: 1; }
+}
+@keyframes m-num-hit {
+  0%, 38%   { background: transparent; color: #0366d6; }
+  44%, 100% { background: #0366d6; color: white; }
+}
+@keyframes m-box-in {
+  0%, 46%   { opacity: 0; transform: translateY(-3px); }
+  56%, 100% { opacity: 1; transform: translateY(0); }
+}
+
+/* 2. Hold Cmd and drag to quote */
+.demo-select .m-long { position: relative; width: 78%; background: #dfe3e8; }
+.demo-select .m-sel {
+  position: absolute;
+  left: 18%;
+  top: -3px;
+  height: 11px;
+  width: 0;
+  border-radius: 2px;
+  background: rgba(3, 102, 214, 0.28);
+  animation: m-sweep 4s ease-in-out infinite;
+}
+.demo-select .m-quote {
+  position: absolute;
+  left: 34px;
+  top: 44px;
+  width: 52%;
+  height: 22px;
+  border-left: 3px solid #0366d6;
+  border-radius: 3px;
+  background: #eef4fb;
+  opacity: 0;
+  animation: m-quote-in 4s ease-in-out infinite;
+}
+.demo-select .m-cursor { animation: m-drag-path 4s ease-in-out infinite; }
+
+@keyframes m-sweep {
+  0%, 14%   { width: 0; }
+  46%, 100% { width: 46%; }
+}
+@keyframes m-drag-path {
+  0%, 14%   { left: 42px; top: 12px; opacity: 1; }
+  46%       { left: 106px; top: 12px; opacity: 1; }
+  62%       { left: 22px; top: 22px; opacity: 1; }
+  100%      { left: 22px; top: 22px; opacity: 1; }
+}
+@keyframes m-quote-in {
+  0%, 64%   { opacity: 0; }
+  74%, 100% { opacity: 1; }
+}
+
+/* 3. Replies thread */
+.demo-thread .m-comment,
+.demo-thread .m-reply {
+  position: absolute;
+  border-radius: 5px;
+  background: #fff8dc;
+  border: 1px solid #f0e0a0;
+}
+.demo-thread .m-comment { left: 12px; top: 16px; width: 72%; height: 28px; }
+.demo-thread .m-reply {
+  left: 34px;
+  top: 52px;
+  width: 58%;
+  height: 24px;
+  background: white;
+  border-color: #e1e4e8;
+  opacity: 0;
+  transform: translateX(-6px);
+  animation: m-reply-in 3.6s ease-in-out infinite;
+}
+
+@keyframes m-reply-in {
+  0%, 30%   { opacity: 0; transform: translateX(-6px); }
+  45%, 100% { opacity: 1; transform: translateX(0); }
+}
+
+/* 4. Submit, and it goes back */
+.demo-handoff { background: #24292e; border-color: #24292e; }
+.demo-handoff .m-term {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 9px;
+}
+.demo-handoff .m-prompt { color: #56d364; }
+.demo-handoff .m-cmd {
+  height: 5px;
+  width: 0;
+  border-radius: 3px;
+  background: #6e7781;
+  animation: m-type 4s steps(14) infinite;
+}
+.demo-handoff .m-flow {
+  position: absolute;
+  left: 14px;
+  top: 44px;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: #0366d6;
+  animation: m-flow 4s ease-in-out infinite;
+}
+.demo-handoff .m-done {
+  position: absolute;
+  right: 14px;
+  top: 38px;
+  color: #56d364;
+  font-size: 15px;
+  opacity: 0;
+  animation: m-done-in 4s ease-in-out infinite;
+}
+
+@keyframes m-type {
+  0%        { width: 0; }
+  30%, 100% { width: 74%; }
+}
+@keyframes m-flow {
+  0%, 36%  { left: 14px; opacity: 0; }
+  44%      { left: 14px; opacity: 1; }
+  76%      { left: 78%;  opacity: 1; }
+  84%, 100%{ left: 78%;  opacity: 0; }
+}
+@keyframes m-done-in {
+  0%, 78%   { opacity: 0; }
+  88%, 100% { opacity: 1; }
+}
+
+/* Someone who has asked not to see motion should not be shown four looping
+ * animations. The mocks still read as diagrams standing still. */
+@media (prefers-reduced-motion: reduce) {
+  .help-demo * { animation: none !important; }
+  .demo-click .m-box,
+  .demo-select .m-quote,
+  .demo-thread .m-reply,
+  .demo-handoff .m-done { opacity: 1; transform: none; }
+  .demo-select .m-sel { width: 46%; }
+  .demo-handoff .m-cmd { width: 74%; }
+}
+
+.help-foot {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 14px 22px;
+  border-top: 1px solid #e1e4e8;
+  background: #f6f8fa;
+}
+
+.help-keys {
+  font-size: 12px;
+  color: #57606a;
+}
+
+.help-done {
+  flex: none;
+  padding: 7px 18px;
+  border: none;
+  border-radius: 6px;
+  background: #0366d6;
+  color: white;
+  font: inherit;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.help-done:hover { background: #0256b9; }
+
+@media (max-width: 640px) {
+  .help-steps { grid-template-columns: 1fr; }
+}