pair-mode 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,16 @@
 # pair mode
 
-A coding agent proposes an edit. Pair mode opens a side-by-side diff in a terminal
-editor. Every line you type becomes a question the model must answer, and the edit
-does not apply until you close the editor.
+#### For when your agent needs a rubber ducky.
+
+`pair-mode` is a tool that allows you to sit somewhere between being an approval monkey for your agent running in manual mode and just totally vibe coding in auto mode.
+
+If you've ever found yourself wanting to pay attention to the code that your agent of choice is generating and (god forbid) suggest changes, I'm sure you've run into: "_oh no, I clicked 'reject' and now the proposed diff is gone - what did I want to suggest again?_"
+
+`pair-mode` attempts to solve this.
+
+When enabled, your agent will push diffs to your editing interface of choice (your choices are currently: in a separate terminal tab/pane, multiplexer sub-pane or web - sorry if your interface of choice is not actually here (yet)). From there you can go line by line over the diff and add comments, suggestions, chidings, deranged ramblings, etc. Your agent will receive your thoughts and proceed accordingly.
+
+![The pair review pane open in a zellij floating pane, with three notes anchored to line numbers](https://raw.githubusercontent.com/oFrusch/pair-mode/main/docs/images/pane-zellij.png)
 
 ## Install
 
@@ -11,55 +19,36 @@ npm install -g pair-mode
 pair-mode setup
 ```
 
-Install pair-mode globally before you run setup. Setup writes the install path into each
-CLI's config as an absolute path. `npx pair-mode setup` runs from a package cache that
-npm later prunes, which would leave every hook pointing at a deleted file. Setup detects
-that case and stops.
+Install pair-mode globally before you run setup. Setup writes the install path into each CLI's config as an absolute path. `npx pair-mode setup` runs from a package cache that npm later prunes, which would leave every hook pointing at a deleted file. Setup detects that case and stops.
 
 The setup command detects the CLIs and multiplexers on your machine, registers the
-required hooks, and writes a config file. Restart Claude Code after setup, because
-Claude Code loads hooks only at startup.
-
-If you install from git instead of npm, run `pnpm build` first. The package does not
-ship a committed `dist/` directory; npm builds it fresh through the `prepublishOnly`
-script, but a git checkout does not run that script.
+required hooks, and writes a config file.
 
 ## Supported CLIs
 
-| CLI         | Hook                                             | Status                                                                                        |
-| ----------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| Claude Code | `PreToolUse`, matcher `Write\|Edit\|MultiEdit`   | Shipped.                                                                                      |
-| Codex       | `PreToolUse`, matcher `apply_patch\|Edit\|Write` | Shipped.                                                                                      |
-| pi          | `tool_call` extension hook                       | Planned for 1.0.0. The adapter exists and passes its unit tests. Setup does not offer it yet. |
-| opencode    | `tool.execute.before` plugin hook                | Planned for 1.0.0. Nobody has run it against a live opencode. Setup does not offer it yet.    |
-
-Codex has no `MultiEdit` matcher alias. Its `apply_patch` parser reads single-file Add,
-Update, and Delete patches only. A multi-file or rename patch passes through untouched.
+| CLI         | Hook                                             | Status                                      |
+| ----------- | ------------------------------------------------ | ------------------------------------------- |
+| Claude Code | `PreToolUse`, matcher `Write\|Edit\|MultiEdit`   | Should work.                                |
+| Codex       | `PreToolUse`, matcher `apply_patch\|Edit\|Write` | Should work.                                |
+| pi          | `tool_call` extension hook                       | Will maybe work. Probably not. Coming soon. |
+| opencode    | `tool.execute.before` plugin hook                | Will maybe work. Probably not. Coming soon. |
 
 ## The /pair command
 
-`pair-mode setup` installs a `/pair` command for every CLI whose hook it registers. The
-command toggles pair mode for the current directory. It also tells the agent how a held
-edit comes back.
+`pair-mode setup` installs a `/pair` (`$pair` for Codex) command for every CLI whose hook it registers. The command toggles pair mode for the current directory. It also tells the agent how a held edit comes back.
 
 | CLI         | Installed at                    | Invoked as              |
 | ----------- | ------------------------------- | ----------------------- |
 | Claude Code | `~/.claude/commands/pair.md`    | `/pair on`, `/pair off` |
 | Codex       | `~/.codex/skills/pair/SKILL.md` | `$pair on`, `$pair off` |
 
-Codex deprecated `~/.codex/prompts/` in favour of skills, so pair mode installs a skill
-there. Codex invokes a skill with `$`, not `/`.
-
 The command runs a bare `pair-mode`, unlike a hook, which each CLI invokes by absolute
 path. So `pair-mode` must resolve on your PATH. A global install puts it there.
 
-`pair-mode doctor` warns when the command is missing, and warns when `pair-mode` does not
-resolve on PATH. Neither warning raises the exit code.
-
-Setup backs up an existing file before it rewrites the file.
-
 ## Editors
 
+This is what will render your diff if you choose to use one of the CLI-based approaches. We ship the `pair` editor, which has good syntax highlight and mouse highlighting support. This makes the annotation process a bit easier. But we also support most popular terminal-based editors.
+
 | Editor         | Diff colour | Syntax colour on changed rows                                                                                                                                                                                                    |
 | -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | pair (default) | Yes         | Yes. pair is the built-in review pane, so it paints syntax colour and change colour on the same row. It also reads mouse clicks and drags for selection, and it anchors a note to the exact span you select, not the whole line. |
@@ -97,28 +86,16 @@ keyboard only.
 | `Ctrl+q` `Ctrl+c`  | —                | Quit. With no notes, the edit applies. With notes pending, asks: `s` sends, `d` discards and quits, `Esc` cancels. |
 | `?`                | —                | Toggle the keymap overlay.                                                                                         |
 
-zellij consumes the mouse scroll wheel, so pair mode never depends on it. `Ctrl+d` and
-`Ctrl+u` page instead.
-
-Holding `shift` during a click or drag passes the mouse event straight through to the
-terminal, which then selects text for copy — the same as any other terminal program.
-
 ## Multiplexers
 
-Claude Code and Codex run their hooks with no controlling terminal. `/dev/tty` returns
-`ENXIO` there. Pane mode needs zellij or tmux to open an editor pane under those two
-CLIs.
-
-Session mode removes the requirement. See the next section.
+If you want to do all your development in one terminal pane while using either Claude Code or Codex, you'll need to use a multiplexer (I use zellij but tmux works great as well). Both harnesses run their hooks with no controlling terminal. A multiplexer allows us to open up the agent's diff in a floating sub-pane.
 
 ## Session modes
 
-Pane mode is the default. The hook opens an editor in a floating pane and blocks. That
-needs a multiplexer under Claude Code and Codex.
-
 Session mode moves the review out of the agent's process. The hook posts to a Unix
-socket and waits. A client you start renders the review and answers. There are two
-clients, and both remove the multiplexer requirement.
+socket and waits. A client you start (another terminal tab or the web view) renders the review and allows you to provide your annotations.
+
+### Session mode config
 
 Set `transport` to `"session"`, then pick a client.
 
@@ -126,39 +103,41 @@ Set `transport` to `"session"`, then pick a client.
 pair-mode config transport session
 ```
 
-`pair-mode config` with no argument prints every setting and its value. `pair-mode
-config <key>` prints one. `pair-mode config <key> <value>` changes one and validates it
-before it writes.
+- `pair-mode config` with no argument prints every setting and its value.
+- `pair-mode config <key>` prints one.
+- `pair-mode config <key> <value>` changes one and validates it before it writes.
 
 **Watch mode** reviews in a terminal you own.
 
 ```
-pair-mode watch          # in any terminal, at the repo root
+pair-mode watch
 ```
 
-The watcher paints an idle screen between reviews and opens the pair TUI for each one.
+![Claude Code on the left, the pair review pane on the right in a second terminal pane](https://raw.githubusercontent.com/oFrusch/pair-mode/main/docs/images/watch-terminal.png)
+
+Run this command in the directory or any subdirectory of where you are working with your agent. The diffs your agent suggests will be pushed to the running Unix socket and rendered wherever this command was run. You can then mark up the diffs as you please and send them back to your agent.
+
 `q` on the idle screen quits and releases the socket.
 
 **Web mode** reviews in a browser and needs no terminal at all.
 
 ```
-pair-mode on --web       # prints a link
+pair-mode on --web
 ```
 
-That spawns a detached watcher, binds an HTTP server on `127.0.0.1`, and prints a link
-carrying a random token. Drag across any text in the diff. A popup opens under the
-selection. Type the note and press Enter. `pair-mode off` stops the watcher.
+![The inline web layout, with two notes in the right margin joined to their lines by a leader](https://raw.githubusercontent.com/oFrusch/pair-mode/main/docs/images/web-inline.png)
 
-The watcher process binds the socket, so there is no separate daemon to manage. If the
-watcher dies, the socket goes away and every hook fails open at once.
+That spawns a detached watcher, binds an HTTP server on `127.0.0.1`, and prints a link carrying a random token. Drag across any text in the diff. A popup opens under the selection. Type the note and press Enter.
 
-A hook that finds no watcher applies the edit rather than hanging. So does a hook whose
-watcher never answers within `session.timeout`.
+The page opens in the layout your `layout` setting names, and `u` swaps it while you read. The inline layout puts every note in the right margin and draws a leader from the marked run to the card. The split layout threads each note under the last line it covers, and it hatches the side of a row that has no line.
+
+![The split web layout, with a note threaded under the line it covers](https://raw.githubusercontent.com/oFrusch/pair-mode/main/docs/images/web-split.png)
 
 ## Configuration
 
-Pair mode reads `$XDG_CONFIG_HOME/pair-mode/config.json`, or `~/.config/pair-mode/config.json`
-when `XDG_CONFIG_HOME` is not set.
+Run `pair-mode setup` when first installing and that should get you most of the way there in terms of pair mode working for your setup. Regardless, all configuration options and their accepted values are listed below.
+
+Pair mode reads `$XDG_CONFIG_HOME/pair-mode/config.json`, or `~/.config/pair-mode/config.json` when `XDG_CONFIG_HOME` is not set.
 
 | Key               | Type                                                                                    | Default     | Meaning                                                          |
 | ----------------- | --------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
@@ -188,21 +167,9 @@ existing config with no `editor` key now opens pair mode's own pane by default.
 
 `notes` and `layout` both describe position, and they are easy to confuse. `layout`
 controls the diff itself — split into two columns, or one inline column. `notes`
-controls only where a note you write renders — in a docked panel, or anchored next to
-the span it annotates. Setting one does not affect the other.
-
-## Limits
-
-- Pair mode opens one pane per tool call. It cannot batch a changeset, because a hook
-  returns one verdict per call and an allow cannot be withdrawn.
-- The pane reviews. It does not edit the proposal.
-- Syntax colour in pair needs `shiki` installed. A missing package disables colour and
-  the pane still works.
-- A client answers one review at a time. It cannot skip ahead in the queue.
-- Web mode does not defend against another user on the same machine. The token sits in
-  the URL, and a local user can read the process list.
-- Watch mode needs the watcher running before the agent edits. A missing watcher fails
-  open, so an unattended agent applies its edits.
+controls only where a note you write renders in the pair pane — in a docked panel, or
+anchored next to the span it annotates. Setting one does not affect the other. The web
+view anchors every note, so it reads `layout` and ignores `notes`.
 
 ## License
 

package/dist/cli.js

@@ -12626,10 +12626,11 @@ var PairClient = (() => {
     draftRange: () => draftRange,
     escapeHtml: () => escapeHtml,
     hiddenRows: () => hiddenRows,
+    inlineHtml: () => inlineHtml,
     labelOf: () => labelOf,
+    marginNotesHtml: () => marginNotesHtml,
     markRange: () => markRange,
     marksFor: () => marksFor,
-    notesHtml: () => notesHtml,
     numberOf: () => numberOf,
     paintCell: () => paintCell,
     quoteOf: () => quoteOf,
@@ -12661,6 +12662,9 @@ var PairClient = (() => {
   function tokensOf(row, pane) {
     return pane === "right" ? row.rightTokens : row.leftTokens;
   }
+  function other(pane) {
+    return pane === "right" ? "left" : "right";
+  }
   function numberOf(row, pane) {
     return pane === "right" ? row.rightNumber : row.leftNumber;
   }
@@ -12719,25 +12723,36 @@ var PairClient = (() => {
     });
     return hidden;
   }
+  function signOf(kind, pane) {
+    if (pane === "left") {
+      return kind === "del" || kind === "replace" ? "-" : " ";
+    }
+    return kind === "add" || kind === "replace" ? "+" : " ";
+  }
   function cellHtml(notes, row, rowIndex, pane) {
     const text = textOf(row, pane);
     const body = paintCell(text, tokensOf(row, pane), marksFor(notes, rowIndex, pane, text.length));
-    return '<td class="num ' + pane + '">' + (numberOf(row, pane) ?? "") + '</td><td class="bar ' + pane + '"></td><td class="code ' + pane + '" data-row="' + rowIndex + '" data-pane="' + pane + '">' + body + "</td>";
+    const number = numberOf(row, pane);
+    const void_ = number === null ? " void" : "";
+    return '<td class="num ' + pane + void_ + '">' + (number ?? "") + '</td><td class="sign ' + pane + void_ + '">' + signOf(row.kind, pane) + '</td><td class="code ' + pane + void_ + '" data-row="' + rowIndex + '" data-pane="' + pane + '">' + body + "</td>";
   }
   function foldsByStart(review) {
     return new Map(review.folds.map((fold, foldIndex) => [fold.start, foldIndex]));
   }
+  var SPLIT_COLUMNS = 6;
+  var INLINE_COLUMNS = 4;
+  function foldHtml(foldIndex, count, columns) {
+    return '<tr class="fold" data-fold="' + foldIndex + '"><td colspan="' + columns + '">' + count + " unchanged lines</td></tr>";
+  }
   function tableHtml(review, notes, expanded) {
     const hidden = hiddenRows(review, expanded);
     const byStart = foldsByStart(review);
-    const parts = ["<table>"];
+    const parts = ['<table class="split">'];
     review.rows.forEach((row, index) => {
       const foldIndex = byStart.get(index);
       const fold = foldIndex === void 0 ? void 0 : review.folds[foldIndex];
       if (foldIndex !== void 0 && fold !== void 0 && !expanded.has(foldIndex)) {
-        parts.push(
-          '<tr class="fold" data-fold="' + foldIndex + '"><td colspan="6">' + fold.count + " unchanged lines</td></tr>"
-        );
+        parts.push(foldHtml(foldIndex, fold.count, SPLIT_COLUMNS));
       }
       if (hidden.has(index)) {
         return;
@@ -12745,6 +12760,77 @@ var PairClient = (() => {
       parts.push(
         '<tr class="' + escapeHtml(row.kind) + '">' + cellHtml(notes, row, index, "left") + cellHtml(notes, row, index, "right") + "</tr>"
       );
+      parts.push(threadsAt(review, notes, index, SPLIT_COLUMNS));
+    });
+    parts.push("</table>");
+    return parts.join("");
+  }
+  function inlineLines(kind) {
+    if (kind === "del") {
+      return [{ pane: "left", sign: "-", kind: "del" }];
+    }
+    if (kind === "add") {
+      return [{ pane: "right", sign: "+", kind: "add" }];
+    }
+    if (kind === "replace") {
+      return [
+        { pane: "left", sign: "-", kind: "del" },
+        { pane: "right", sign: "+", kind: "add" }
+      ];
+    }
+    return [{ pane: "right", sign: " ", kind: "context" }];
+  }
+  function inlineMarks(notes, rowIndex, kind, pane, length) {
+    if (kind !== "context") {
+      return marksFor(notes, rowIndex, pane, length);
+    }
+    return [
+      ...marksFor(notes, rowIndex, "left", length),
+      ...marksFor(notes, rowIndex, "right", length)
+    ];
+  }
+  function anchorsHere(line, panes, notePane) {
+    return line.pane === notePane || !panes.includes(notePane);
+  }
+  function anchorsAt(notes, rowIndex, line, panes) {
+    return notes.map((note, index) => ({ note, index })).filter(
+      (entry) => entry.note.startRow === rowIndex && anchorsHere(line, panes, entry.note.pane)
+    ).map((entry) => entry.index);
+  }
+  function inlineRowHtml(review, notes, rowIndex, line, panes) {
+    const row = review.rows[rowIndex];
+    if (row === void 0) {
+      return "";
+    }
+    const text = textOf(row, line.pane);
+    const body = paintCell(
+      text,
+      tokensOf(row, line.pane),
+      inlineMarks(notes, rowIndex, row.kind, line.pane, text.length)
+    );
+    const anchors = anchorsAt(notes, rowIndex, line, panes);
+    const leftNumber = line.pane === "left" ? row.leftNumber ?? "" : "";
+    const rightNumber = line.pane === "right" ? row.rightNumber ?? "" : "";
+    return '<tr class="' + line.kind + '"' + (anchors.length === 0 ? "" : ' data-anchor="' + anchors.join(" ") + '"') + '><td class="num old">' + leftNumber + '</td><td class="num new">' + rightNumber + '</td><td class="sign ' + line.pane + '">' + line.sign + '</td><td class="code ' + line.pane + '" data-row="' + rowIndex + '" data-pane="' + line.pane + '">' + body + "</td></tr>";
+  }
+  function inlineHtml(review, notes, expanded) {
+    const hidden = hiddenRows(review, expanded);
+    const byStart = foldsByStart(review);
+    const parts = ['<table class="inline">'];
+    review.rows.forEach((row, index) => {
+      const foldIndex = byStart.get(index);
+      const fold = foldIndex === void 0 ? void 0 : review.folds[foldIndex];
+      if (foldIndex !== void 0 && fold !== void 0 && !expanded.has(foldIndex)) {
+        parts.push(foldHtml(foldIndex, fold.count, INLINE_COLUMNS));
+      }
+      if (hidden.has(index)) {
+        return;
+      }
+      const lines = inlineLines(row.kind);
+      const panes = lines.map((line) => line.pane);
+      lines.forEach((line) => {
+        parts.push(inlineRowHtml(review, notes, index, line, panes));
+      });
     });
     parts.push("</table>");
     return parts.join("");
@@ -12764,13 +12850,21 @@ var PairClient = (() => {
     if (startRow === void 0 || endRow === void 0) {
       return "";
     }
-    const start = numberOf(startRow, note.pane);
+    const start = numberOf(startRow, note.pane) ?? numberOf(startRow, other(note.pane));
     const end = numberOf(endRow, note.pane);
+    if (start === null) {
+      return "";
+    }
     return start === end || end === null ? "L" + start : "L" + start + "-" + end;
   }
-  function notesHtml(review, notes) {
+  function threadsAt(review, notes, rowIndex, columns) {
+    return notes.map((note, index) => ({ note, index })).filter((entry) => entry.note.endRow === rowIndex).map(
+      (entry) => '<tr class="thread"><td colspan="' + columns + '"><button class="drop" data-drop="' + entry.index + '" aria-label="Remove note">&times;</button><div class="at">' + escapeHtml(labelOf(review, entry.note)) + "</div><p>" + escapeHtml(entry.note.text) + "</p></td></tr>"
+    ).join("");
+  }
+  function marginNotesHtml(review, notes) {
     return notes.map(
-      (note, index) => '<div class="note"><button class="drop" data-drop="' + index + '">&times;</button><div class="where">' + escapeHtml(labelOf(review, note)) + '</div><div class="quote">' + escapeHtml(quoteOf(review, note)) + '</div><div class="body">' + escapeHtml(note.text) + "</div></div>"
+      (note, index) => '<div class="note" data-card="' + index + '"><button class="drop" data-drop="' + index + '" aria-label="Remove note">&times;</button><div class="at">' + escapeHtml(labelOf(review, note)) + "</div><p>" + escapeHtml(note.text) + "</p></div>"
     ).join("");
   }
   function sortedNotes(notes) {
@@ -12810,157 +12904,237 @@ var PairClient = (() => {
 var STYLE = `
 :root {
   --bg: #0d1117;
-  --panel: #12171f;
-  --line: #21262d;
+  --chrome: #10141a;
+  --rule: #1e242c;
   --text: #c9d1d9;
   --muted: ${theme.fold};
-  --chrome: ${theme.chrome};
+  --dim: #39424d;
   --add-bar: ${theme.addBar};
   --del-bar: ${theme.delBar};
-  --add-tint: rgba(63, 185, 80, 0.09);
-  --del-tint: rgba(248, 81, 73, 0.09);
+  --add-tint: rgba(63, 185, 80, 0.08);
+  --del-tint: rgba(248, 81, 73, 0.08);
   --note: ${theme.note};
-  --note-tint: rgba(210, 168, 255, 0.22);
+  --note-tint: rgba(210, 168, 255, 0.16);
+  --amber: ${theme.chrome};
+  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
 }
 
 * { box-sizing: border-box; }
 
 body {
   margin: 0;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
   background: var(--bg);
   color: var(--text);
-  font: 13px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font: 13px/1.6 var(--mono);
+  -webkit-font-smoothing: antialiased;
 }
 
+/* ---- chrome ---- */
+
 header {
   position: sticky;
   top: 0;
-  z-index: 3;
+  z-index: 6;
   display: flex;
-  align-items: center;
-  gap: 12px;
-  padding: 9px 14px;
+  align-items: stretch;
   background: var(--chrome);
-  color: #1f1a12;
-  font-weight: 600;
+  border-bottom: 1px solid var(--rule);
+  font-size: 12px;
 }
 
-header .path { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+header .seg { padding: 6px 13px; white-space: nowrap; }
+header .mode { background: var(--amber); color: ${theme.statusText}; font-weight: 700; letter-spacing: 0.1em; }
+header .path { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; color: var(--muted); }
+header .plus { color: var(--add-bar); }
+header .minus { color: var(--del-bar); }
+header .tally { color: var(--note); }
 
-button {
-  font: inherit;
-  padding: 4px 12px;
-  border: 1px solid rgba(0, 0, 0, 0.35);
-  border-radius: 5px;
-  background: #1f1a12;
-  color: #f0e6d2;
+footer {
+  position: sticky;
+  bottom: 0;
+  z-index: 6;
+  display: flex;
+  align-items: stretch;
+  background: var(--chrome);
+  border-top: 1px solid var(--rule);
+  font-size: 11.5px;
+}
+
+footer .seg { padding: 6px 12px; color: var(--muted); white-space: nowrap; }
+footer .seg .key { color: var(--text); font-weight: 700; }
+footer .fill { flex: 1; }
+
+footer .swap { display: flex; }
+
+footer .swap button {
+  font: 400 11.5px/1.6 var(--mono);
+  padding: 6px 11px;
+  border: 0;
+  background: none;
+  color: var(--muted);
+  cursor: pointer;
+}
+
+footer .swap button:hover { color: var(--text); }
+footer .swap button[aria-pressed="true"] { background: var(--note-tint); color: var(--note); font-weight: 700; }
+
+footer .act {
+  font: 700 11.5px/1.6 var(--mono);
+  padding: 6px 14px;
+  border: 0;
   cursor: pointer;
 }
 
-button:disabled { opacity: 0.4; cursor: default; }
+footer .act:disabled { opacity: 0.35; cursor: default; }
+footer .act.ok { background: rgba(63, 185, 80, 0.16); color: var(--add-bar); }
+footer .act.ok:enabled:hover { background: var(--add-bar); color: #06140a; }
+footer .act.send { background: var(--note); color: #170f1e; }
+footer .act.send:enabled:hover { filter: brightness(1.12); }
+
+button:focus-visible, [tabindex]:focus-visible { outline: 2px solid var(--note); outline-offset: -2px; }
+
+/* ---- diff, both layouts ---- */
 
-main { display: flex; align-items: flex-start; }
+main { position: relative; flex: 1; display: flex; align-items: flex-start; }
 
 #diff { flex: 1; min-width: 0; overflow-x: auto; }
 
 table { width: 100%; border-collapse: collapse; }
 
-td { padding: 0 8px; vertical-align: top; white-space: pre; }
+td { padding: 0; vertical-align: top; white-space: pre; }
 
 td.num {
   width: 1%;
-  padding: 0 6px;
+  padding: 0 8px;
   text-align: right;
-  color: var(--muted);
+  color: var(--dim);
+  font-variant-numeric: tabular-nums;
   user-select: none;
 }
 
-td.bar { width: 3px; padding: 0; }
+td.sign { width: 1%; padding: 0 6px 0 0; text-align: center; color: var(--dim); user-select: none; }
+td.code { cursor: text; padding-right: 18px; }
 
-tr.add td.bar.right, tr.replace td.bar.right { background: var(--add-bar); }
-tr.del td.bar.left, tr.replace td.bar.left { background: var(--del-bar); }
+table.split td.code { width: 50%; }
+table.inline td.code { width: auto; }
 
-tr.add td.code.right, tr.replace td.code.right { background: var(--add-tint); }
-tr.del td.code.left, tr.replace td.code.left { background: var(--del-tint); }
+tr.add td.sign.right, tr.replace td.sign.right { color: var(--add-bar); }
+tr.del td.sign.left, tr.replace td.sign.left { color: var(--del-bar); }
+tr.add td.sign, tr.add td.code { background: var(--add-tint); }
+tr.del td.sign, tr.del td.code { background: var(--del-tint); }
+tr.replace td.sign.right, tr.replace td.code.right { background: var(--add-tint); }
+tr.replace td.sign.left, tr.replace td.code.left { background: var(--del-tint); }
 
-td.code { width: 50%; cursor: text; }
+tr.add td.void, tr.del td.void, tr.replace td.void {
+  background: repeating-linear-gradient(-45deg, transparent 0 5px, rgba(255, 255, 255, 0.022) 5px 10px);
+  cursor: default;
+}
 
 ::selection { background: rgba(88, 166, 255, 0.35); }
 
 mark.noted {
   background: var(--note-tint);
-  border-bottom: 2px solid var(--note);
   color: inherit;
-  border-radius: 2px;
+  box-shadow: inset 0 -2px 0 var(--note);
 }
 
 tr.fold td {
-  padding: 2px 8px;
-  color: var(--muted);
-  background: var(--panel);
+  padding: 3px 0 3px 18px;
+  color: var(--dim);
+  background: rgba(255, 255, 255, 0.016);
+  border-top: 1px solid var(--rule);
+  border-bottom: 1px solid var(--rule);
   cursor: pointer;
-  text-align: center;
   user-select: none;
 }
 
 tr.fold td:hover { color: var(--text); }
 
-aside {
-  position: sticky;
-  top: 40px;
-  width: 300px;
-  flex: none;
-  max-height: calc(100vh - 40px);
-  overflow-y: auto;
-  padding: 12px;
-  border-left: 1px solid var(--line);
-  background: var(--panel);
+/* ---- notes threaded under a split row ---- */
+
+tr.thread td {
+  padding: 9px 22px 10px 60px;
+  border-left: 2px solid var(--note);
+  background: rgba(210, 168, 255, 0.05);
+  white-space: normal;
 }
 
-aside h2 {
-  margin: 0 0 10px;
-  font-size: 11px;
-  letter-spacing: 0.08em;
-  color: var(--muted);
+tr.thread .at {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.11em;
   text-transform: uppercase;
+  color: var(--note);
+}
+
+tr.thread p, .note p {
+  margin: 3px 0 0;
+  max-width: 62ch;
+  font-size: 13px;
+  line-height: 1.5;
+  color: #e7e2ea;
 }
 
+/* ---- notes in the inline margin ---- */
+
+#margin {
+  position: relative;
+  width: 320px;
+  flex: none;
+  align-self: stretch;
+  padding: 0 20px 0 4px;
+}
+
+#margin.hidden { display: none; }
+
 .note {
-  margin-bottom: 10px;
-  padding: 8px 10px;
-  border-left: 3px solid var(--note);
-  border-radius: 0 4px 4px 0;
-  background: var(--bg);
+  position: absolute;
+  left: 4px;
+  right: 20px;
+  padding-left: 14px;
+  border-left: 1px solid var(--note);
+}
+
+.note .at {
+  font-size: 10.5px;
+  letter-spacing: 0.11em;
+  text-transform: uppercase;
+  color: var(--note);
 }
 
-.note .where { color: var(--note); font-size: 11px; }
-.note .quote { margin: 3px 0; color: var(--muted); font-size: 11px; }
-.note .body { white-space: pre-wrap; }
+#leaders { position: absolute; inset: 0; pointer-events: none; z-index: 1; }
 
-.note .drop {
+.drop {
   float: right;
-  padding: 0 6px;
+  padding: 0 4px;
   border: 0;
   background: none;
-  color: var(--muted);
+  color: var(--dim);
+  font: 400 14px/1 var(--mono);
+  cursor: pointer;
 }
 
-.note .drop:hover { color: var(--del-bar); }
+.drop:hover { color: var(--del-bar); }
+
+/* ---- popup ---- */
 
 #popup {
   position: absolute;
-  z-index: 5;
+  z-index: 8;
   display: none;
-  width: 300px;
-  padding: 10px;
+  width: 320px;
+  padding: 11px;
   border: 1px solid var(--note);
-  border-radius: 6px;
-  background: var(--panel);
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.5);
+  border-radius: 5px;
+  background: var(--chrome);
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.6);
 }
 
 #popup .quote {
-  margin-bottom: 6px;
+  margin-bottom: 7px;
   overflow: hidden;
   color: var(--muted);
   font-size: 11px;
@@ -12970,27 +13144,48 @@ aside h2 {
 
 #popup .row { display: flex; gap: 8px; margin-top: 8px; }
 
+#popup button {
+  font: 500 12px/1 var(--mono);
+  padding: 6px 12px;
+  border: 1px solid var(--rule);
+  border-radius: 4px;
+  background: none;
+  color: var(--text);
+  cursor: pointer;
+}
+
+#popup button.save { background: var(--note); border-color: var(--note); color: #170f1e; font-weight: 700; }
+
 textarea {
   width: 100%;
-  min-height: 62px;
-  padding: 6px;
-  border: 1px solid var(--line);
+  min-height: 66px;
+  padding: 7px;
+  border: 1px solid var(--rule);
   border-radius: 4px;
   background: var(--bg);
   color: var(--text);
-  font: inherit;
+  font: 13px/1.5 var(--mono);
   resize: vertical;
 }
 
-.hint { color: var(--muted); font-size: 11px; }
+.hint { color: var(--dim); font-size: 11px; }
 
-#idle { padding: 48px; color: var(--muted); text-align: center; }
+#idle { padding: 64px 24px; color: var(--dim); text-align: center; }
+
+@media (max-width: 900px) {
+  main { flex-wrap: wrap; }
+  #leaders { display: none; }
+  #margin { width: 100%; padding: 12px 16px; border-top: 1px solid var(--rule); }
+  .note { position: static; margin-bottom: 12px; }
+}
 `;
 var WIRING = String.raw`
 const C = PairClient;
 const token = location.pathname.split("/")[2];
+const main = document.querySelector("main");
 const diff = document.getElementById("diff");
-const notesPanel = document.getElementById("notes");
+const margin = document.getElementById("margin");
+const leaders = document.getElementById("leaders");
 const popup = document.getElementById("popup");
 const popupQuote = document.getElementById("popup-quote");
 const popupText = document.getElementById("popup-text");
@@ -12999,37 +13194,151 @@ const popupCancel = document.getElementById("popup-cancel");
 const sendButton = document.getElementById("send");
 const approveButton = document.getElementById("approve");
 const pathLabel = document.getElementById("path");
+const tallyLabel = document.getElementById("tally");
+const plusLabel = document.getElementById("plus");
+const minusLabel = document.getElementById("minus");
 
 let review = null;
 let notes = [];
 let expanded = new Set();
 let draft = null;
+let layout = document.body.dataset.layout === "inline" ? "inline" : "split";
+
+function isInline() {
+  return layout === "inline";
+}
+
+function countKinds() {
+  let plus = 0;
+  let minus = 0;
+
+  review.rows.forEach((row) => {
+    if (row.kind === "add" || row.kind === "replace") { plus += 1; }
+    if (row.kind === "del" || row.kind === "replace") { minus += 1; }
+  });
 
-function renderNotes() {
-  if (review === null || notes.length === 0) {
-    notesPanel.innerHTML = '<div class="hint">Select any text in the diff to leave a note.</div>';
+  return { plus, minus };
+}
+
+// A leader line joins a marked run to its card, so it redraws whenever either one moves.
+function drawLeaders() {
+  if (!isInline() || review === null || notes.length === 0) {
+    leaders.innerHTML = "";
     return;
   }
 
-  notesPanel.innerHTML = C.notesHtml(review, notes);
+  const base = main.getBoundingClientRect();
+
+  leaders.setAttribute("viewBox", "0 0 " + base.width + " " + base.height);
+  leaders.setAttribute("width", base.width);
+  leaders.setAttribute("height", base.height);
+
+  leaders.innerHTML = notes.map((_note, index) => {
+    const row = diff.querySelector('[data-anchor~="' + index + '"]');
+    const card = margin.querySelector('[data-card="' + index + '"]');
+
+    if (row === null || card === null) {
+      return "";
+    }
+
+    // The line leaves from under the marked run, so it continues that underline and crosses no glyph.
+    const marks = row.querySelectorAll("mark.noted");
+    const ordinal = (row.dataset.anchor ?? "").split(" ").indexOf(String(index));
+    const source = marks[ordinal] ?? marks[marks.length - 1] ?? row;
+    const a = source.getBoundingClientRect();
+    const b = card.getBoundingClientRect();
+    const x1 = a.right - base.left + 5;
+    const y1 = a.bottom - base.top - 0.5;
+    const x2 = b.left - base.left;
+    const y2 = b.top - base.top;
+    const mid = x1 + (x2 - x1) * 0.55;
+
+    return '<path d="M ' + x1 + ' ' + y1 + ' C ' + mid + ' ' + y1 + ', ' + mid + ' ' + y2 + ', ' + x2 + ' ' + y2 +
+      '" fill="none" stroke="var(--note)" stroke-width="1" stroke-opacity="0.5" />' +
+      '<circle cx="' + x1 + '" cy="' + y1 + '" r="2" fill="var(--note)" fill-opacity="0.9" />';
+  }).join("");
+}
+
+// Two notes on nearby lines would overlap, so each card starts below the one before it.
+function placeCards() {
+  if (!isInline()) {
+    return;
+  }
+
+  const base = margin.getBoundingClientRect();
+  let floor = 0;
+
+  notes.forEach((_note, index) => {
+    const row = diff.querySelector('[data-anchor~="' + index + '"]');
+    const card = margin.querySelector('[data-card="' + index + '"]');
+
+    if (row === null || card === null) {
+      return;
+    }
+
+    const top = Math.max(row.getBoundingClientRect().bottom - base.top, floor);
+    card.style.top = top + "px";
+    floor = top + card.offsetHeight + 18;
+  });
+}
+
+function renderMargin() {
+  const wanted = isInline() && review !== null && notes.length > 0;
+
+  margin.classList.toggle("hidden", !wanted);
+  margin.innerHTML = wanted ? C.marginNotesHtml(review, notes) : "";
 }
 
 function render() {
   if (review === null) {
     diff.innerHTML = '<div id="idle">waiting for an edit</div>';
     pathLabel.textContent = "no review open";
+    plusLabel.textContent = "";
+    minusLabel.textContent = "";
+    tallyLabel.textContent = "";
     sendButton.disabled = true;
     approveButton.disabled = true;
     hidePopup();
-    renderNotes();
+    renderMargin();
+    refreshLeaders();
     return;
   }
 
+  const counts = countKinds();
+
   pathLabel.textContent = review.path;
+  plusLabel.textContent = "+" + counts.plus;
+  minusLabel.textContent = "−" + counts.minus;
+  tallyLabel.textContent = notes.length === 0 ? "" : notes.length + (notes.length === 1 ? " note" : " notes");
   sendButton.disabled = notes.length === 0;
+  sendButton.textContent = "^S send" + (notes.length === 0 ? "" : " " + notes.length);
   approveButton.disabled = false;
-  diff.innerHTML = C.tableHtml(review, notes, expanded);
-  renderNotes();
+
+  diff.innerHTML = isInline()
+    ? C.inlineHtml(review, notes, expanded)
+    : C.tableHtml(review, notes, expanded);
+
+  renderMargin();
+  refreshLeaders();
+}
+
+// A card needs its final height before anything measures it, so the placement waits for the paint.
+function refreshLeaders() {
+  requestAnimationFrame(() => {
+    placeCards();
+    drawLeaders();
+  });
+}
+
+function setLayout(next) {
+  layout = next;
+
+  document.querySelectorAll(".swap button").forEach((button) => {
+    button.setAttribute("aria-pressed", String(button.dataset.layout === next));
+  });
+
+  hidePopup();
+  render();
 }
 
 function cellOf(node) {
@@ -13063,9 +13372,11 @@ function readSelection() {
   return span === null ? null : { span, rect: range.getBoundingClientRect() };
 }
 
+// A hidden textarea still holds focus, and the key handler ignores every key while it does.
 function hidePopup() {
   popup.style.display = "none";
   popupText.value = "";
+  popupText.blur();
   draft = null;
 }
 
@@ -13074,7 +13385,7 @@ function showPopup(selected) {
   popupQuote.textContent = C.quoteOf(review, selected.span) || "(whole line)";
 
   const top = window.scrollY + selected.rect.bottom + 8;
-  const left = Math.max(8, Math.min(window.scrollX + selected.rect.left, window.innerWidth - 320));
+  const left = Math.max(8, Math.min(window.scrollX + selected.rect.left, window.innerWidth - 340));
 
   popup.style.top = top + "px";
   popup.style.left = left + "px";
@@ -13093,7 +13404,7 @@ diff.addEventListener("mouseup", () => {
 });
 
 diff.addEventListener("click", (event) => {
-  const fold = event.target.closest("[data-fold]");
+  const fold = event.target instanceof Element ? event.target.closest("[data-fold]") : null;
 
   if (fold === null) {
     return;
@@ -13131,8 +13442,8 @@ popupText.addEventListener("keydown", (event) => {
   }
 });
 
-notesPanel.addEventListener("click", (event) => {
-  const drop = event.target.closest("[data-drop]");
+document.addEventListener("click", (event) => {
+  const drop = event.target instanceof Element ? event.target.closest("[data-drop]") : null;
 
   if (drop === null) {
     return;
@@ -13143,6 +13454,44 @@ notesPanel.addEventListener("click", (event) => {
   render();
 });
 
+document.querySelectorAll(".swap button").forEach((button) => {
+  button.addEventListener("click", () => setLayout(button.dataset.layout));
+});
+
+// The pane binds u to the same swap, so the browser answers the key a pair mode user already knows.
+document.addEventListener("keydown", (event) => {
+  if (event.target === popupText || event.metaKey || event.ctrlKey || event.altKey) {
+    return;
+  }
+
+  if (event.key === "u") {
+    setLayout(isInline() ? "split" : "inline");
+  }
+});
+
+// The footer names ^S and ^Q, so both keys act rather than reaching the browser.
+document.addEventListener("keydown", (event) => {
+  if (!event.ctrlKey || event.metaKey || event.altKey || review === null) {
+    return;
+  }
+
+  if (event.key === "s" && notes.length > 0) {
+    event.preventDefault();
+    post({ id: review.id, notes });
+    return;
+  }
+
+  if (event.key === "q") {
+    event.preventDefault();
+    post({ id: review.id, notes: [] });
+  }
+});
+
+window.addEventListener("resize", () => {
+  placeCards();
+  drawLeaders();
+});
+
 function warn(message) {
   pathLabel.textContent = message;
 }
@@ -13211,7 +13560,10 @@ function inlineScript(source) {
 }
 var SCRIPT = inlineScript(`${CLIENT_BUNDLE}
 ${WIRING}`);
-function renderPage() {
+function pressed(layout, wanted) {
+  return layout === wanted ? "true" : "false";
+}
+function renderPage(layout = "split") {
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -13220,25 +13572,35 @@ function renderPage() {
 <title>pair mode</title>
 <style>${STYLE}</style>
 </head>
-<body>
+<body data-layout="${layout}">
 <header>
-  <span>pair mode</span>
-  <span class="path" id="path">no review open</span>
-  <button id="approve">Approve</button>
-  <button id="send">Send notes</button>
+  <span class="seg mode">PAIR</span>
+  <span class="seg path" id="path">no review open</span>
+  <span class="seg plus" id="plus"></span>
+  <span class="seg minus" id="minus"></span>
+  <span class="seg tally" id="tally"></span>
 </header>
 <main>
+  <svg id="leaders" aria-hidden="true"></svg>
   <div id="diff"></div>
-  <aside>
-    <h2>Notes</h2>
-    <div id="notes"></div>
-  </aside>
+  <div id="margin"></div>
 </main>
+<footer>
+  <span class="seg">drag to <span class="key">note</span></span>
+  <span class="seg">click a fold to <span class="key">open</span></span>
+  <span class="swap" role="group" aria-label="Layout">
+    <button data-layout="inline" aria-pressed="${pressed(layout, "inline")}">u inline</button>
+    <button data-layout="split" aria-pressed="${pressed(layout, "split")}">u split</button>
+  </span>
+  <span class="fill"></span>
+  <button class="act ok" id="approve">^Q approve</button>
+  <button class="act send" id="send">^S send</button>
+</footer>
 <div id="popup">
   <div class="quote" id="popup-quote"></div>
   <textarea id="popup-text" placeholder="What do you want to ask?"></textarea>
   <div class="row">
-    <button id="popup-save">Add note</button>
+    <button class="save" id="popup-save">Add note</button>
     <button id="popup-cancel">Cancel</button>
   </div>
   <div class="hint">Enter saves. Shift-Enter makes a new line.</div>
@@ -13416,7 +13778,7 @@ data: ${data}
     const url = request.url ?? "";
     if (url === base && request.method === "GET") {
       response.writeHead(OK, { "content-type": "text/html; charset=utf-8" });
-      response.end(renderPage());
+      response.end(renderPage(options.layout));
       return;
     }
     if (url === `${base}/events` && request.method === "GET") {
@@ -13516,6 +13878,7 @@ async function startWebWatch(options, config) {
   const web = await startWebServer({
     port: options.port,
     token: options.token,
+    layout: config.layout,
     onVerdict(id, questions) {
       client.write(encode({ type: "verdict", id, questions }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-mode",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Annotate a coding agent's proposed edits line by line, in your terminal.",
   "keywords": [
     "ai",
@@ -37,6 +37,7 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "capture": "node scripts/capture-fixtures.mjs",
+    "release": "node scripts/release.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",