@fresh-editor/fresh-editor 0.3.5 → 0.3.7

package/plugins/git_log.ts

@@ -2,12 +2,10 @@
 
 import {
   type GitCommit,
-  buildCommitDetailEntries,
   buildCommitLogEntries,
-  buildDetailPlaceholderEntries,
-  fetchCommitShow,
   fetchGitLog,
 } from "./lib/git_history.ts";
+import { button, flexSpacer, key, list, row, WidgetPanel } from "./lib/index.ts";
 
 const editor = getEditor();
 
@@ -35,90 +33,68 @@ interface GitLogState {
   isOpen: boolean;
   groupId: number | null;
   logBufferId: number | null;
+  /**
+   * The buffer-group's initial detail panel buffer (a virtual buffer
+   * created by `createBufferGroup`). After the first commit is shown,
+   * the panel is retargeted at a file-backed streaming buffer via
+   * `setBufferGroupPanelBuffer`; this id is kept so we can close the
+   * orphaned virtual buffer on group teardown.
+   */
+  initialDetailBufferId: number | null;
+  /**
+   * The buffer id currently displayed in the detail panel (one
+   * file-backed buffer per visited commit). Tracked for focus checks
+   * and cursor placement.
+   */
   detailBufferId: number | null;
   toolbarBufferId: number | null;
-  /** Click-regions for the toolbar's buttons, populated by `renderToolbar`. */
-  toolbarButtons: ToolbarButton[];
+  /** Widget panel rendering the toolbar (Row of Buttons). */
+  toolbarPanel: WidgetPanel | null;
+  /** Widget panel rendering the log (List of commit rows). */
+  logPanel: WidgetPanel | null;
   commits: GitCommit[];
   selectedIndex: number;
-  /** Cached `git show` output for the currently-displayed detail commit. */
-  detailCache: { hash: string; output: string } | null;
-  /**
-   * In-flight detail request id. Used to ignore stale responses when the
-   * user scrolls through the log faster than `git show` can return.
-   */
-  pendingDetailId: number;
   /**
-   * Debounce token for `cursor_moved`. Rapid cursor motion (PageDown, held
-   * j/k) would otherwise trigger a full log re-render + `git show` per
-   * intermediate row; we bump this id on every event and only do the work
-   * after a short delay if no newer event has arrived.
+   * Per-commit cache: sha → file-backed buffer id. Each visited
+   * commit gets its own buffer pointing at `<dataDir>/git-show/<sha>.diff`,
+   * which a background `git show --patch` writes into. Returning to a
+   * cached commit is just a `setBufferGroupPanelBuffer` call — no
+   * git invocation, scroll position preserved.
    */
-  pendingCursorMoveId: number;
+  commitBuffers: Map<string, number>;
+  /** sha → in-flight spawnProcess handle, for kill-on-supersession. */
+  inFlightSpawns: Map<string, ProcessHandle<SpawnResult>>;
   /**
-   * Byte offset at the start of each row in the rendered log panel, plus
-   * the total buffer length at the end. Populated by `renderLog` so the
-   * cursor_moved handler can map byte positions to commit indices without
-   * relying on `getCursorLine` (which is not implemented for virtual
-   * buffers).
+   * Debounce token for List `select` events. Rapid selection moves
+   * (PageDown, held j/k) shouldn't churn through buffer swaps + spawns;
+   * we bump this id on every event and only do the work after a short
+   * delay if no newer event has arrived.
    */
-  logRowByteOffsets: number[];
+  pendingSelectId: number;
 }
 
 const state: GitLogState = {
   isOpen: false,
   groupId: null,
   logBufferId: null,
+  initialDetailBufferId: null,
   detailBufferId: null,
   toolbarBufferId: null,
-  toolbarButtons: [],
+  toolbarPanel: null,
+  logPanel: null,
   commits: [],
   selectedIndex: 0,
-  detailCache: null,
-  pendingDetailId: 0,
-  pendingCursorMoveId: 0,
-  logRowByteOffsets: [],
+  commitBuffers: new Map(),
+  inFlightSpawns: new Map(),
+  pendingSelectId: 0,
 };
 
 /**
- * Delay before reacting to `cursor_moved`. Long enough to collapse a burst
- * of events from held j/k or PageDown into a single render, short enough
- * that the detail panel still feels live.
- */
-const CURSOR_DEBOUNCE_MS = 60;
-
-// UTF-8 byte length — the overlay API expects byte offsets; JS strings are
-// UTF-16. Matches the helper used by `lib/git_history.ts`.
-function utf8Len(s: string): number {
-  let b = 0;
-  for (let i = 0; i < s.length; i++) {
-    const c = s.charCodeAt(i);
-    if (c <= 0x7f) b += 1;
-    else if (c <= 0x7ff) b += 2;
-    else if (c >= 0xd800 && c <= 0xdfff) {
-      b += 4;
-      i++;
-    } else b += 3;
-  }
-  return b;
-}
-
-/**
- * Binary search `logRowByteOffsets` for the 0-indexed row whose byte
- * offset is the largest one ≤ `bytePos`. Returns 0 on an empty table.
+ * Delay before spawning `git show` after a List `select` event. Long
+ * enough to collapse a burst (held j/k or PageDown) into one fetch,
+ * short enough that the detail panel still feels live.
  */
-function rowFromByte(bytePos: number): number {
-  const offs = state.logRowByteOffsets;
-  if (offs.length === 0) return 0;
-  let lo = 0;
-  let hi = offs.length - 1;
-  while (lo < hi) {
-    const mid = (lo + hi + 1) >> 1;
-    if (offs[mid] <= bytePos) lo = mid;
-    else hi = mid - 1;
-  }
-  return lo;
-}
+const SELECT_DEBOUNCE_MS = 60;
 
 // =============================================================================
 // Modes
@@ -129,15 +105,20 @@ function rowFromByte(bytePos: number): number {
 // the log, and opens the file at the cursor when pressed in the detail).
 // =============================================================================
 
-// j/k as vi-style aliases for Up/Down, plus the plugin-specific action
-// keys. Everything else (arrows, Page{Up,Down}, Home/End, Shift+motion for
-// selection, Ctrl+C copy, …) is inherited from the Normal keymap because
-// the mode is registered with `inheritNormalBindings: true`.
+// j/k/Up/Down/PageUp/PageDown route to the log List widget so the host
+// owns selection + scroll + auto-scroll. The List's `select` event then
+// fires back into the plugin's `widget_event` handler for detail-pane
+// refresh. Other plugin actions (q/r/y/Tab/Return) stay as direct
+// bindings — they don't depend on which row is highlighted.
 editor.defineMode(
   "git-log",
   [
-    ["k", "move_up"],
-    ["j", "move_down"],
+    ["k", "git_log_select_up"],
+    ["j", "git_log_select_down"],
+    ["Up", "git_log_select_up"],
+    ["Down", "git_log_select_down"],
+    ["PageUp", "git_log_select_page_up"],
+    ["PageDown", "git_log_select_page_down"],
     ["Return", "git_log_enter"],
     ["Tab", "git_log_tab"],
     ["q", "git_log_q"],
@@ -149,6 +130,52 @@ editor.defineMode(
   true, // inherit Normal-context bindings for unbound keys
 );
 
+function git_log_select_up(): void {
+  if (isLogPanelActive()) {
+    state.logPanel?.command(key("Up"));
+  } else {
+    editor.executeAction("move_up");
+  }
+}
+function git_log_select_down(): void {
+  if (isLogPanelActive()) {
+    state.logPanel?.command(key("Down"));
+  } else {
+    editor.executeAction("move_down");
+  }
+}
+function git_log_select_page_up(): void {
+  if (isLogPanelActive()) {
+    state.logPanel?.command(key("PageUp"));
+  } else {
+    editor.executeAction("move_page_up");
+  }
+}
+function git_log_select_page_down(): void {
+  if (isLogPanelActive()) {
+    state.logPanel?.command(key("PageDown"));
+  } else {
+    editor.executeAction("move_page_down");
+  }
+}
+
+/** True iff the log panel is the focused buffer in the group. The
+ * group's bindings (j/k/Up/Down/PageUp/PageDown) apply to all panels
+ * uniformly; we only want navigation to drive the List widget when
+ * the user is *on* the log panel. From the detail panel, the same
+ * keys must move the buffer cursor (so users can scroll the diff
+ * before pressing Enter on a diff line to open the file view). */
+function isLogPanelActive(): boolean {
+  return (
+    state.logBufferId !== null &&
+    editor.getActiveBufferId() === state.logBufferId
+  );
+}
+registerHandler("git_log_select_up", git_log_select_up);
+registerHandler("git_log_select_down", git_log_select_down);
+registerHandler("git_log_select_page_up", git_log_select_page_up);
+registerHandler("git_log_select_page_down", git_log_select_page_down);
+
 // =============================================================================
 // Panel layout
 // =============================================================================
@@ -177,116 +204,87 @@ const GROUP_LAYOUT = JSON.stringify({
 // =============================================================================
 // Toolbar
 // =============================================================================
+//
+// The toolbar is a one-row panel mounted above the log/detail split. It's
+// rendered through the widget runtime — a `Row` of `Button` widgets — so
+// the host owns hit-testing, focus styling, and keystroke dispatch, and the
+// plugin only handles the resulting `widget_event` actions.
+//
+// Each button's `key` is a stable identifier (`toolbar.tab`, `toolbar.q`,
+// etc.) that `widget_event` carries back so the plugin can look up the
+// right handler without per-row column arithmetic. The previous custom
+// hit-region tracking (`state.toolbarButtons`, `on_git_log_toolbar_click`)
+// is gone.
 
-interface ToolbarHint {
+interface ToolbarItem {
   key: string;
   label: string;
-  /** Click action — `null` for hints that are keyboard-only (j/k, PgUp). */
-  onClick: (() => void | Promise<void>) | null;
+  onClick: () => void | Promise<void>;
 }
 
-interface ToolbarButton {
-  row: number;
-  startCol: number;
-  endCol: number;
-  onClick: (() => void | Promise<void>) | null;
-}
+const TOOLBAR_KEY_PREFIX = "toolbar.";
 
-function toolbarHints(): ToolbarHint[] {
+function toolbarItems(): ToolbarItem[] {
   return [
-    { key: "Tab", label: "switch pane", onClick: git_log_tab },
-    { key: "RET", label: "open file", onClick: git_log_enter },
-    { key: "y", label: "copy hash", onClick: git_log_copy_hash },
-    { key: "r", label: "refresh", onClick: git_log_refresh },
-    { key: "q", label: "quit", onClick: git_log_q },
+    { key: "tab", label: "Tab switch pane", onClick: git_log_tab },
+    { key: "ret", label: "RET open file", onClick: git_log_enter },
+    { key: "y", label: "y copy hash", onClick: git_log_copy_hash },
+    { key: "r", label: "r refresh", onClick: git_log_refresh },
+    { key: "q", label: "q quit", onClick: git_log_q },
   ];
 }
 
-/**
- * Build the single-row toolbar. Each hint renders as a discrete button with
- * its own background so it reads as clickable; the column range of each
- * button is captured in `state.toolbarButtons` so `on_git_log_toolbar_click`
- * can map a mouse click back to the right handler.
- */
-function buildToolbarEntries(width: number): TextPropertyEntry[] {
-  const W = Math.max(20, width);
-  const buttons: ToolbarButton[] = [];
-  let text = "";
-  const overlays: InlineOverlay[] = [];
-
-  for (const hint of toolbarHints()) {
-    const body = ` [${hint.key}] ${hint.label} `;
-    const bodyLen = body.length;
-    const gap = text.length > 0 ? 1 : 0;
-    if (text.length + gap + bodyLen > W) break;
-
-    if (gap) text += " ";
-
-    const startCol = text.length;
-    const startByte = utf8Len(text);
-    text += body;
-    const endByte = utf8Len(text);
-    const endCol = text.length;
-
-    overlays.push({
-      start: startByte,
-      end: endByte,
-      style: { bg: "ui.status_bar_bg" },
-    });
-    const keyDisplay = `[${hint.key}]`;
-    const keyStartByte = startByte + utf8Len(" ");
-    const keyEndByte = keyStartByte + utf8Len(keyDisplay);
-    overlays.push({
-      start: keyStartByte,
-      end: keyEndByte,
-      style: { fg: "editor.fg", bold: true },
-    });
-    overlays.push({
-      start: keyEndByte,
-      end: endByte,
-      style: { fg: "editor.line_number_fg" },
-    });
-
-    buttons.push({ row: 0, startCol, endCol, onClick: hint.onClick });
-  }
-
-  state.toolbarButtons = buttons;
-
-  return [
-    {
-      text: text + "\n",
-      properties: { type: "git-log-toolbar" },
-      style: { bg: "editor.bg", extendToLineEnd: true },
-      inlineOverlays: overlays,
-    },
-  ];
+function toolbarSpec(): WidgetSpec {
+  const items = toolbarItems();
+  // `flexSpacer` at the end pushes the buttons to the left and lets the
+  // toolbar background extend across the row.
+  return row(
+    ...items.map((item) =>
+      button(item.label, { key: TOOLBAR_KEY_PREFIX + item.key }),
+    ),
+    flexSpacer(),
+  );
 }
 
 function renderToolbar(): void {
-  if (state.groupId === null) return;
-  const vp = editor.getViewport();
-  const width = vp ? vp.width : 80;
-  editor.setPanelContent(state.groupId, "toolbar", buildToolbarEntries(width));
+  if (state.toolbarPanel === null) return;
+  state.toolbarPanel.set(toolbarSpec());
 }
 
-function on_git_log_toolbar_click(data: {
-  buffer_id: number | null;
-  buffer_row: number | null;
-  buffer_col: number | null;
-}): void {
-  if (!state.isOpen) return;
-  if (data.buffer_id === null || data.buffer_id !== state.toolbarBufferId) return;
-  if (data.buffer_row === null || data.buffer_col === null) return;
-  const row = data.buffer_row;
-  const col = data.buffer_col;
-  const hit = state.toolbarButtons.find(
-    (b) => b.row === row && col >= b.startCol && col < b.endCol
-  );
-  if (hit && hit.onClick) {
-    void hit.onClick();
+editor.on("widget_event", (data) => {
+  // Toolbar (Row of Buttons) — `activate` from keypress or click on a
+  // button.
+  if (
+    state.toolbarPanel !== null &&
+    data.panel_id === state.toolbarPanel.id()
+  ) {
+    if (data.event_type !== "activate") return;
+    const items = toolbarItems();
+    for (const item of items) {
+      if (data.widget_key === TOOLBAR_KEY_PREFIX + item.key) {
+        void item.onClick();
+        return;
+      }
+    }
+    return;
   }
-}
-registerHandler("on_git_log_toolbar_click", on_git_log_toolbar_click);
+  // Log pane (List of commit rows) — `select` fires on j/k/Up/Down/
+  // PageUp/PageDown navigation and on row clicks; `activate` fires on
+  // Enter or double-click.
+  if (state.logPanel !== null && data.panel_id === state.logPanel.id()) {
+    if (data.event_type === "select") {
+      const idx =
+        typeof data.payload?.index === "number" ? data.payload.index : -1;
+      if (idx >= 0) void on_log_select(idx);
+      return;
+    }
+    if (data.event_type === "activate") {
+      void git_log_enter();
+      return;
+    }
+    return;
+  }
+});
 
 function on_git_log_resize(_data: { width: number; height: number }): void {
   if (!state.isOpen) return;
@@ -303,105 +301,284 @@ function detailFooter(hash: string): string {
 }
 
 function renderLog(): void {
-  if (state.groupId === null) return;
-  // No header row and no footer: the sticky toolbar above the group
-  // carries the shortcut hints, and the commit count goes to the status
-  // line when the group opens.
-  const entries = buildCommitLogEntries(state.commits, {
-    selectedIndex: state.selectedIndex,
+  if (state.logPanel === null) return;
+  // List takes the per-row entries directly. selectedIndex: -1 on the
+  // entry builder suppresses the plugin's selection styling — the host
+  // renders the focused-row highlight from the List widget's instance
+  // state instead.
+  const items = buildCommitLogEntries(state.commits, {
+    selectedIndex: -1,
     header: null,
   });
-  // Rebuild the byte-offset table used by cursor_moved to map positions
-  // to commit indices. `offsets[i]` is the byte offset of commit i; the
-  // final entry is the total buffer length, so row lookups clamp
-  // correctly on the last row.
-  const offsets: number[] = [];
-  let running = 0;
-  for (const e of entries) {
-    offsets.push(running);
-    running += utf8Len(e.text);
-  }
-  offsets.push(running);
-  state.logRowByteOffsets = offsets;
-  editor.setPanelContent(state.groupId, "log", entries);
-}
-
-function renderDetailPlaceholder(message: string): void {
-  if (state.groupId === null) return;
-  editor.setPanelContent(
-    state.groupId,
-    "detail",
-    buildDetailPlaceholderEntries(message)
+  const itemKeys = state.commits.map((c) => c.hash);
+  state.logPanel.set(
+    list({
+      items,
+      itemKeys,
+      selectedIndex: state.selectedIndex,
+      // Visible-rows only matters for virtualization; setting it to
+      // commits.length renders all rows and lets the buffer's natural
+      // scroll handle viewport. Revisit if commit lists grow into the
+      // tens of thousands.
+      visibleRows: Math.max(1, state.commits.length),
+      key: "git-log-list",
+    }),
   );
 }
 
-function renderDetailForCommit(commit: GitCommit, showOutput: string): void {
-  if (state.groupId === null) return;
-  const entries = buildCommitDetailEntries(commit, showOutput);
-  editor.setPanelContent(state.groupId, "detail", entries);
-  // Always scroll the detail panel back to the top when the selection changes.
-  if (state.detailBufferId !== null) {
-    editor.setBufferCursor(state.detailBufferId, 0);
-  }
+// =============================================================================
+// Streaming detail panel
+//
+// Per-commit cached file-backed buffers. On commit switch we either reuse
+// the existing cached buffer (instant) or spawn `git show --patch` into a
+// per-SHA file and open it via `openFileStreaming`, polling for growth
+// while git runs in the background. The buffer-group panel is re-pointed
+// at the chosen buffer via `setBufferGroupPanelBuffer` — the same single
+// tab keeps the side-by-side log/detail UX.
+// =============================================================================
+
+/**
+ * Path of the per-SHA cache file. Commits are immutable; once we've
+ * written one, repeat visits are zero-git.
+ */
+function cachePathForHash(hash: string): string {
+  // `<dataDir>/git-show/<sha>.diff` — the .diff extension lets the
+  // syntax-highlight grammar kick in for free.
+  return `${editor.getDataDir()}/git-show/${hash}.diff`;
 }
 
+/** Polling interval while git is still writing. ~5 fps is plenty. */
+const STREAM_POLL_MS = 200;
+
 /**
- * Synchronous detail refresh: render from cache if we have it, otherwise
- * a "loading…" placeholder. Never spawns git. Called immediately on every
- * selection change so the user sees instant feedback even while the real
- * `git show` is debounced.
+ * Start a `git show --patch` for `hash`, piping stdout straight into the
+ * cache file. Returns the handle so a later commit switch can `.kill()`
+ * the still-running spawn.
  *
- * Returns the commit that needs fetching (cache miss) or null (cache hit
- * or no commit selected) so the caller can decide whether to spawn.
+ * Caller has already verified the cache file doesn't yet exist (or wants
+ * to overwrite it).
  */
-function refreshDetailImmediate(): GitCommit | null {
-  if (state.groupId === null) return null;
-  if (state.commits.length === 0) {
-    renderDetailPlaceholder(editor.t("status.no_commits"));
-    return null;
-  }
-  const idx = Math.max(0, Math.min(state.selectedIndex, state.commits.length - 1));
-  const commit = state.commits[idx];
-  if (!commit) return null;
+function spawnGitShow(hash: string, cwd: string): ProcessHandle<SpawnResult> {
+  // `--stat --patch` matches what the previous plugin used. The stat
+  // header gives users a per-file changed-lines summary at the top
+  // of the diff and is also what `git show` produces by default, so
+  // its presence is what most readers (and tests) expect.
+  //
+  // The generated d.ts shows `spawnProcess(cmd, args, cwd?, stdoutTo?)`
+  // as flat positional args. The runtime JS wrapper also accepts an
+  // `{stdoutTo}` options object in the 4th slot, but using the flat
+  // form keeps the call type-checked without a cast.
+  return editor.spawnProcess(
+    "git",
+    ["show", "--stat", "--patch", hash],
+    cwd,
+    cachePathForHash(hash),
+  );
+}
+
+/**
+ * Poll `editor.refreshBufferFromDisk` until the spawn handle resolves,
+ * then do one final catch-up refresh. Returns immediately if the
+ * commit is no longer in flight (e.g. user moved on, kill() fired).
+ */
+async function pollUntilSpawnDone(
+  hash: string,
+  bufferId: number,
+  handle: ProcessHandle<SpawnResult>,
+): Promise<void> {
+  // Wrap the handle's settlement in a non-rejecting marker promise so
+  // a fast subscription loop can `await` it (or race it against a
+  // delay) without worrying about whether the spawn errored. The
+  // ProcessHandle is a thenable, not a real Promise, so adapt via
+  // Promise.resolve().
+  let done = false;
+  void Promise.resolve(handle).then(
+    () => {
+      done = true;
+    },
+    () => {
+      done = true;
+    },
+  );
 
-  if (state.detailCache && state.detailCache.hash === commit.hash) {
-    renderDetailForCommit(commit, state.detailCache.output);
-    return null;
+  while (!done) {
+    await editor.delay(STREAM_POLL_MS);
+    if (!state.isOpen) return; // group closed mid-stream
+    if (state.inFlightSpawns.get(hash) !== handle) return; // superseded
+    await editor.refreshBufferFromDisk(bufferId);
+  }
+  // Final catch-up so any bytes written between the last poll and
+  // process exit are visible immediately.
+  await editor.refreshBufferFromDisk(bufferId);
+  // Done — clear the in-flight handle if it's still ours.
+  if (state.inFlightSpawns.get(hash) === handle) {
+    state.inFlightSpawns.delete(hash);
   }
+  // Apply diff coloring once the buffer is complete. Doing this
+  // pre-completion would either churn (re-walk on every refresh) or
+  // double-overlay newly-extended lines; on completion we walk once.
+  await applyDiffHighlights(bufferId);
+}
 
-  renderDetailPlaceholder(
-    editor.t("status.loading_commit", { hash: commit.shortHash })
-  );
-  return commit;
+// =============================================================================
+// Diff syntax highlighting via per-line bg overlays
+//
+// Sublime-syntax's bundled `Diff` definition only scopes the `diff`
+// keyword, so themes only colour that. Plugins are responsible for the
+// rest — same approach `live_diff` uses for inline diff coloring in
+// regular buffers.
+//
+// One overlay per line of added/removed content is fine for the
+// "normal commit" workload but explodes on giant commits (the
+// rewrite-bun commit is 1M lines = 1M overlays = back to the old
+// 500k-overlay problem this rewire eliminated). Gate on buffer size;
+// gracefully degrade to no highlighting for outliers.
+// =============================================================================
+
+const HIGHLIGHT_BG_ADDED = "editor.diff_add_bg";
+const HIGHLIGHT_BG_REMOVED = "editor.diff_remove_bg";
+const HIGHLIGHT_BG_HUNK = "editor.diff_modify_bg";
+const HIGHLIGHT_NAMESPACE = "git-log-diff";
+/** Skip overlay highlighting above this size. ~256 KB covers
+ *  basically every hand-written commit comfortably; very large
+ *  generated-file diffs (lockfiles, minified code) just stay
+ *  uncoloured — the cost would be a few thousand-to-a-million
+ *  overlays for content the user mostly skims. */
+const HIGHLIGHT_MAX_BYTES = 256 * 1024;
+
+async function applyDiffHighlights(bufferId: number): Promise<void> {
+  const total = editor.getBufferLength(bufferId);
+  if (total === 0 || total > HIGHLIGHT_MAX_BYTES) return;
+  const text = await editor.getBufferText(bufferId, 0, total);
+  if (!text) return;
+
+  // Walk lines tracking byte offsets; coalesce consecutive same-kind
+  // rows into single ranges so a 30-line added block costs one
+  // overlay, not 30.
+  let byte = 0;
+  let runKind: "+" | "-" | "@" | null = null;
+  let runStart = 0;
+  let runEnd = 0;
+
+  const flushRun = () => {
+    if (runKind === null) return;
+    const bg =
+      runKind === "+"
+        ? HIGHLIGHT_BG_ADDED
+        : runKind === "-"
+        ? HIGHLIGHT_BG_REMOVED
+        : HIGHLIGHT_BG_HUNK;
+    editor.addOverlay(bufferId, HIGHLIGHT_NAMESPACE, runStart, runEnd, {
+      bg,
+      extendToLineEnd: true,
+    });
+    runKind = null;
+  };
+
+  for (const line of text.split("\n")) {
+    const lineLen = line.length;
+    const ch = line.charAt(0);
+    let kind: "+" | "-" | "@" | null = null;
+    if (ch === "+" && !line.startsWith("+++")) kind = "+";
+    else if (ch === "-" && !line.startsWith("---")) kind = "-";
+    else if (line.startsWith("@@")) kind = "@";
+
+    if (kind !== runKind) {
+      flushRun();
+      if (kind !== null) {
+        runStart = byte;
+        runKind = kind;
+      }
+    }
+    if (kind !== null) {
+      // Include the trailing newline in the range so the bg colour
+      // fills the row even on empty lines that wrap-extend.
+      runEnd = byte + lineLen + 1;
+    }
+    byte += lineLen + 1;
+  }
+  flushRun();
 }
 
 /**
- * Spawn `git show` for `commit` and render the result. Tagged with
- * `pendingDetailId` so a newer selection supersedes in-flight fetches.
+ * Get (or create) the file-backed buffer that displays `commit`.
+ * On first call for a hash: ensure cache file exists, kick off
+ * `git show` if it doesn't, openFileStreaming, start the poll loop.
+ * Returns the buffer id on success or null on failure.
  */
-async function fetchAndRenderDetail(commit: GitCommit): Promise<void> {
-  const myId = ++state.pendingDetailId;
-  const output = await fetchCommitShow(editor, commit.hash);
-  if (myId !== state.pendingDetailId) return;
-  if (state.groupId === null) return;
-  state.detailCache = { hash: commit.hash, output };
-  // Only render if the current selection is still this commit — a rapid
-  // Up/Down burst might have moved on before we got here.
-  const currentIdx = Math.max(
-    0,
-    Math.min(state.selectedIndex, state.commits.length - 1)
-  );
-  if (state.commits[currentIdx]?.hash !== commit.hash) return;
-  renderDetailForCommit(commit, output);
+async function ensureCommitBuffer(commit: GitCommit, cwd: string): Promise<number | null> {
+  const hash = commit.hash;
+  const existing = state.commitBuffers.get(hash);
+  if (existing !== undefined) return existing;
+
+  const path = cachePathForHash(hash);
+  const cacheHit = editor.fileExists(path);
+
+  if (!cacheHit) {
+    // Cache miss: spawn git, polling the file as it grows. The handle
+    // is stashed so a fast-scrolling user can supersede us via kill().
+    const handle = spawnGitShow(hash, cwd);
+    state.inFlightSpawns.set(hash, handle);
+    const bufferId = await editor.openFileStreaming(path);
+    if (bufferId === null) {
+      handle.kill?.();
+      state.inFlightSpawns.delete(hash);
+      return null;
+    }
+    state.commitBuffers.set(hash, bufferId);
+    // Fire-and-forget polling task.
+    void pollUntilSpawnDone(hash, bufferId, handle);
+    return bufferId;
+  }
+
+  // Cache hit: just open the existing file. No git spawned.
+  const bufferId = await editor.openFileStreaming(path);
+  if (bufferId === null) return null;
+  state.commitBuffers.set(hash, bufferId);
+  return bufferId;
 }
 
 /**
- * Combined synchronous + asynchronous refresh used by open/refresh paths
- * where there's no burst of events to collapse.
+ * Show `commit` in the detail panel. Cancels any superseded in-flight
+ * spawn for *other* commits (the user has navigated past them) and
+ * retargets the panel at the chosen commit's buffer.
  */
+async function showCommitInDetail(commit: GitCommit, cwd: string): Promise<void> {
+  // Cancel anything still streaming for a commit that isn't this one —
+  // the user has moved on; no point keeping git running.
+  for (const [hash, handle] of state.inFlightSpawns) {
+    if (hash !== commit.hash) {
+      handle.kill?.();
+      state.inFlightSpawns.delete(hash);
+    }
+  }
+
+  const bufferId = await ensureCommitBuffer(commit, cwd);
+  if (bufferId === null) {
+    editor.setStatus(
+      editor.t("status.failed_open_file", { file: commit.shortHash }),
+    );
+    return;
+  }
+  if (state.groupId === null) return;
+  await editor.setBufferGroupPanelBuffer(state.groupId, "detail", bufferId);
+  state.detailBufferId = bufferId;
+  // Each commit buffer needs the same per-buffer presentation as the
+  // initial virtual one: visible cursor for diff-line navigation,
+  // wrap on (long minified lines unreadable in the 40% panel).
+  editor.setBufferShowCursors(bufferId, true);
+  editor.setLineWrap(bufferId, null, true);
+  // Land at the top of the diff every time we (re-)visit a commit.
+  editor.setBufferCursor(bufferId, 0);
+}
+
 async function refreshDetail(): Promise<void> {
-  const pending = refreshDetailImmediate();
-  if (pending) await fetchAndRenderDetail(pending);
+  if (state.groupId === null) return;
+  if (state.commits.length === 0) return;
+  const idx = Math.max(0, Math.min(state.selectedIndex, state.commits.length - 1));
+  const commit = state.commits[idx];
+  if (!commit) return;
+  await showCommitInDetail(commit, editor.getCwd());
 }
 
 // =============================================================================
@@ -415,14 +592,6 @@ function selectedCommit(): GitCommit | null {
   return state.commits[i] ?? null;
 }
 
-function indexFromCursorByte(bytePos: number): number {
-  // No header row — row 0 is commit 0.
-  const idx = rowFromByte(bytePos);
-  if (idx < 0) return 0;
-  if (idx >= state.commits.length) return state.commits.length - 1;
-  return idx;
-}
-
 // =============================================================================
 // Commands
 // =============================================================================
@@ -454,42 +623,40 @@ async function show_git_log(): Promise<void> {
   );
   state.groupId = group.groupId as number;
   state.logBufferId = (group.panels["log"] as number | undefined) ?? null;
-  state.detailBufferId = (group.panels["detail"] as number | undefined) ?? null;
+  state.initialDetailBufferId =
+    (group.panels["detail"] as number | undefined) ?? null;
+  // detailBufferId starts as the initial virtual buffer; it gets
+  // retargeted to a file-backed buffer on first commit selection.
+  state.detailBufferId = state.initialDetailBufferId;
   state.toolbarBufferId = (group.panels["toolbar"] as number | undefined) ?? null;
+  if (state.toolbarBufferId !== null) {
+    state.toolbarPanel = new WidgetPanel(state.toolbarBufferId);
+  }
+  if (state.logBufferId !== null) {
+    state.logPanel = new WidgetPanel(state.logBufferId);
+  }
   state.selectedIndex = 0;
-  state.detailCache = null;
+  state.commitBuffers = new Map();
+  state.inFlightSpawns = new Map();
   state.isOpen = true;
 
-  // The log panel owns a native cursor so j/k/Up/Down navigate commits,
-  // and the detail panel also gets a cursor so diff lines can be clicked
-  // / traversed before pressing Enter to open a file.
-  if (state.logBufferId !== null) {
-    editor.setBufferShowCursors(state.logBufferId, true);
-  }
-  if (state.detailBufferId !== null) {
-    editor.setBufferShowCursors(state.detailBufferId, true);
-    // Wrap long lines in the detail panel — git diffs often exceed the
-    // 40% split width, and horizontal scrolling a commit is awkward.
-    editor.setLineWrap(state.detailBufferId, null, true);
-    // Per-panel mode: the group was created with "git-log" which applies
-    // to the initially-focused panel (log). The detail panel's mode is
-    // set when we focus into it.
+  // The detail panel owns a native cursor so diff lines can be
+  // clicked / traversed before pressing Enter to open a file. We set
+  // the cursor on each retargeted buffer as it gets swapped in, but
+  // wrap-default needs setting too — long minified lines in lock-file
+  // diffs are unreadable without wrap in the 40% panel.
+  if (state.initialDetailBufferId !== null) {
+    editor.setBufferShowCursors(state.initialDetailBufferId, true);
+    editor.setLineWrap(state.initialDetailBufferId, null, true);
   }
 
   renderToolbar();
   renderLog();
-  // Position the cursor on the first commit (row 0 now that the header
-  // row is gone).
-  if (state.logBufferId !== null && state.commits.length > 0) {
-    editor.setBufferCursor(state.logBufferId, 0);
-  }
+  // List widget's instance state is the source of truth for selection;
+  // no buffer-cursor positioning needed (the renderer auto-scrolls so
+  // the selected row stays visible).
   await refreshDetail();
 
-  if (state.groupId !== null) {
-    editor.focusBufferGroupPanel(state.groupId, "log");
-  }
-  editor.on("cursor_moved", on_git_log_cursor_moved);
-  editor.on("mouse_click", on_git_log_toolbar_click);
   editor.on("resize", on_git_log_resize);
   editor.on("buffer_closed", on_git_log_buffer_closed);
 
@@ -504,19 +671,38 @@ registerHandler("show_git_log", show_git_log);
  * close button, which triggers `buffer_closed`). */
 function git_log_cleanup(): void {
   if (!state.isOpen) return;
-  editor.off("cursor_moved", on_git_log_cursor_moved);
-  editor.off("mouse_click", on_git_log_toolbar_click);
   editor.off("resize", on_git_log_resize);
   editor.off("buffer_closed", on_git_log_buffer_closed);
+  // Kill any still-running `git show` spawns — we no longer care.
+  for (const [, handle] of state.inFlightSpawns) {
+    handle.kill?.();
+  }
+  state.inFlightSpawns.clear();
+  // Close each per-commit buffer we created. The buffer-group's own
+  // `close` (called below in `git_log_close`) tears down the panel
+  // buffers (toolbar/log/initialDetail) — but retargeted file-backed
+  // buffers we allocated via openFileStreaming are *outside* the
+  // group's panel_buffers map by the time we got here, so we must
+  // close them explicitly to avoid leaks.
+  for (const [, bufferId] of state.commitBuffers) {
+    editor.closeBuffer(bufferId);
+  }
+  state.commitBuffers.clear();
+  // The buffer-group's `close` will tear down its own panel buffers
+  // (toolbar/log/initialDetail) too, which implicitly drops the widget
+  // panels rendering into them. We still null out the handles so any
+  // stray `renderToolbar()` / `renderLog()` call post-cleanup is a
+  // no-op.
+  state.toolbarPanel = null;
+  state.logPanel = null;
   state.isOpen = false;
   state.groupId = null;
   state.logBufferId = null;
+  state.initialDetailBufferId = null;
   state.detailBufferId = null;
   state.toolbarBufferId = null;
-  state.toolbarButtons = [];
   state.commits = [];
   state.selectedIndex = 0;
-  state.detailCache = null;
 }
 
 function git_log_close(): void {
@@ -532,12 +718,26 @@ registerHandler("git_log_close", git_log_close);
 
 function on_git_log_buffer_closed(data: { buffer_id: number }): void {
   if (!state.isOpen) return;
+  // Tear down the whole group only when the *group's* buffers close
+  // (toolbar / log / the initial virtual detail). A retargeted
+  // file-backed commit buffer closing is normal — drop it from our
+  // cache but keep the group alive.
   if (
     data.buffer_id === state.logBufferId ||
-    data.buffer_id === state.detailBufferId ||
+    data.buffer_id === state.initialDetailBufferId ||
     data.buffer_id === state.toolbarBufferId
   ) {
     git_log_cleanup();
+    return;
+  }
+  // Removed from cache so a revisit re-spawns / re-opens.
+  for (const [hash, bufId] of state.commitBuffers) {
+    if (bufId === data.buffer_id) {
+      state.commitBuffers.delete(hash);
+      state.inFlightSpawns.get(hash)?.kill?.();
+      state.inFlightSpawns.delete(hash);
+      break;
+    }
   }
 }
 registerHandler("on_git_log_buffer_closed", on_git_log_buffer_closed);
@@ -546,7 +746,13 @@ async function git_log_refresh(): Promise<void> {
   if (!state.isOpen) return;
   editor.setStatus(editor.t("status.refreshing"));
   state.commits = await fetchGitLog(editor);
-  state.detailCache = null;
+  // The on-disk cache files are keyed by SHA and commits are
+  // immutable, so they remain valid — but our in-memory buffer ids
+  // for commits no longer in the visible list are stale; clear them.
+  for (const [, handle] of state.inFlightSpawns) handle.kill?.();
+  state.inFlightSpawns.clear();
+  for (const [, bufferId] of state.commitBuffers) editor.closeBuffer(bufferId);
+  state.commitBuffers.clear();
   if (state.selectedIndex >= state.commits.length) {
     state.selectedIndex = Math.max(0, state.commits.length - 1);
   }
@@ -617,26 +823,222 @@ function git_log_q(): void {
 }
 registerHandler("git_log_q", git_log_q);
 
+// =============================================================================
+// Folding by file and hunk
+//
+// Publishes structural fold ranges into the buffer's `folding_ranges`
+// via `setFoldingRanges` — the same channel an LSP `foldingRange`
+// response uses. Nothing is pre-collapsed; the user toggles a range
+// with the standard fold keybinding (`za` etc.), which finds the
+// matching range under the cursor.
+//
+// The diff structure gives us two natural fold levels:
+//   * per-file:  each `diff --git a/X b/Y` section
+//   * per-hunk:  each `@@ -A,B +C,D @@` block within a file
+// We publish both; the toggle-fold key picks the innermost containing
+// range at the cursor's line.
+//
+// Computed once after `pollUntilSpawnDone` settles — re-running on
+// every refresh would churn the marker list for no benefit (the diff
+// structure is monotonic-append until exit).
+// =============================================================================
+
+interface DiffFoldRange {
+  startLine: number;
+  endLine: number;
+}
+
+/** Walk the buffer text and return (file-level, hunk-level) fold
+ *  ranges. Lines are 0-indexed, both endpoints inclusive — the LSP
+ *  shape. The "fold header" is the line at `startLine`; everything up
+ *  through `endLine` collapses under it. */
+function computeDiffFoldRanges(text: string): {
+  files: DiffFoldRange[];
+  hunks: DiffFoldRange[];
+} {
+  const lines = text.split("\n");
+  const files: DiffFoldRange[] = [];
+  const hunks: DiffFoldRange[] = [];
+
+  let fileStart: number | null = null;
+  let hunkStart: number | null = null;
+
+  const closeHunk = (endLine: number) => {
+    if (hunkStart !== null && endLine > hunkStart) {
+      hunks.push({ startLine: hunkStart, endLine });
+    }
+    hunkStart = null;
+  };
+  const closeFile = (endLine: number) => {
+    closeHunk(endLine);
+    if (fileStart !== null && endLine > fileStart) {
+      files.push({ startLine: fileStart, endLine });
+    }
+    fileStart = null;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (l.startsWith("diff --git ")) {
+      closeFile(i - 1);
+      fileStart = i;
+    } else if (l.startsWith("@@ ")) {
+      closeHunk(i - 1);
+      hunkStart = i;
+    }
+  }
+  closeFile(lines.length - 1);
+  return { files, hunks };
+}
+
+async function publishDiffFoldRanges(bufferId: number): Promise<void> {
+  const total = editor.getBufferLength(bufferId);
+  if (total === 0) return;
+  const text = await editor.getBufferText(bufferId, 0, total);
+  if (!text) return;
+
+  const { files, hunks } = computeDiffFoldRanges(text);
+
+  // Merge — the host accepts a single array. "region" kind tags both
+  // levels generically; the LSP spec also defines comment/imports
+  // kinds which don't apply to diffs.
+  const ranges = [...files, ...hunks].map((r) => ({
+    startLine: r.startLine,
+    endLine: r.endLine,
+    kind: "region",
+  }));
+  editor.setFoldingRanges(bufferId, ranges);
+}
+
 // =============================================================================
 // Detail panel — open file at commit
 // =============================================================================
 
+/**
+ * Walk through the streaming diff buffer to find the file + line
+ * context near the cursor. Diff format:
+ *
+ *     diff --git a/<path> b/<path>
+ *     index ...
+ *     --- a/<path>     (or /dev/null for additions)
+ *     +++ b/<path>     (or /dev/null for deletions)
+ *     @@ -old,n +new,m @@
+ *     <context|+|- lines>
+ *
+ * Strategy:
+ *  - Read up to the END of the cursor's line, not just up to the
+ *    cursor's byte offset. This way a cursor sitting on a header line
+ *    (`diff --git`, `+++ b/...`, `@@ ...`) still gets that line
+ *    matched, matching the old text-property behaviour.
+ *  - Walk backwards for the per-file header. Match either:
+ *      `+++ b/<path>`             (preferred — names the new-side path)
+ *      `diff --git a/<src> b/<dst>` (fallback — covers the case where
+ *        the cursor is on the `diff --git` line itself, before the
+ *        `+++` line has appeared in the search range)
+ *  - Walk backwards for the most recent `@@ -... +<new>,<count> @@`
+ *    between the header and cursor, then count context/'+' rows
+ *    forward to the cursor to derive the new-side line number.
+ */
+async function deriveFileAndLineFromDiffCursor(
+  bufferId: number,
+): Promise<{ file: string; line: number } | null> {
+  const cursor = editor.getCursorPosition();
+  if (cursor < 0) return null;
+
+  const bufLen = editor.getBufferLength(bufferId);
+  const readEnd = Math.min(bufLen, cursor + 4096);
+  if (readEnd === 0) return null;
+  const text = await editor.getBufferText(bufferId, 0, readEnd);
+  if (!text) return null;
+  const lines = text.split("\n");
+
+  // Locate the cursor's line index by walking byte offsets. `lines[i]`
+  // covers bytes [byte, byte+len]; the `\n` separator lives at
+  // byte+len, so the next line starts at byte+len+1.
+  let byte = 0;
+  let cursorLineIdx = lines.length - 1;
+  for (let i = 0; i < lines.length; i++) {
+    const lineLen = lines[i].length;
+    if (cursor <= byte + lineLen) {
+      cursorLineIdx = i;
+      break;
+    }
+    byte += lineLen + 1;
+  }
+
+  // Walk back from the cursor's line for the per-file header. Match
+  // either `+++ b/<path>` or `diff --git a/<src> b/<dst>` so cursor-
+  // on-header cases work.
+  let file: string | null = null;
+  let headerIdx = -1;
+  for (let i = cursorLineIdx; i >= 0; i--) {
+    const l = lines[i];
+    if (l.startsWith("+++ b/")) {
+      file = l.slice(6).trim();
+      headerIdx = i;
+      break;
+    }
+    if (l.startsWith("+++ /dev/null")) {
+      // Deletion — no new-side path. Opening the pre-image is a
+      // separate flow.
+      return null;
+    }
+    const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(l);
+    if (m) {
+      const aSide = m[1];
+      const bSide = m[2];
+      file = bSide === "/dev/null" ? aSide : bSide;
+      headerIdx = i;
+      break;
+    }
+  }
+  if (file === null || headerIdx < 0) return null;
+
+  // Find the most recent `@@ ... +start,count @@` between header and
+  // cursor. Default: line 1 (cursor sits on the header itself, or
+  // between the header and the first hunk).
+  let line = 1;
+  for (let i = cursorLineIdx; i > headerIdx; i--) {
+    const l = lines[i];
+    const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(l);
+    if (!m) continue;
+    const newStart = parseInt(m[1], 10);
+    if (!Number.isFinite(newStart)) return null;
+    // Walk forward from the hunk header to the cursor's line,
+    // advancing the new-file line counter for context (' ') and
+    // addition ('+') rows; skip deletion ('-') rows since they don't
+    // exist in the new file.
+    let cur = newStart;
+    for (let j = i + 1; j <= cursorLineIdx; j++) {
+      if (j === cursorLineIdx) {
+        line = cur;
+        break;
+      }
+      const ch = lines[j].charAt(0);
+      if (ch === "+" || ch === " " || ch === "") cur += 1;
+      // '-' / '\' (no-newline marker): don't advance.
+    }
+    break;
+  }
+  return { file, line };
+}
+
 async function git_log_detail_open_file(): Promise<void> {
   if (state.detailBufferId === null) return;
   const commit = selectedCommit();
   if (!commit) return;
 
-  const props = editor.getTextPropertiesAtCursor(state.detailBufferId);
-  if (props.length === 0) {
-    editor.setStatus(editor.t("status.move_to_diff"));
-    return;
-  }
-  const file = props[0].file as string | undefined;
-  const line = (props[0].line as number | undefined) ?? 1;
-  if (!file) {
+  // The detail buffer is a plain file-backed view of `git show --patch`,
+  // so we don't have plugin-attached `file`/`line` properties anymore.
+  // Parse the diff backwards from the cursor to find the nearest
+  // `+++ b/<path>` header (a per-file diff section opener) and the
+  // most recent hunk header to derive a line number.
+  const ctx = await deriveFileAndLineFromDiffCursor(state.detailBufferId);
+  if (!ctx) {
     editor.setStatus(editor.t("status.move_to_diff_with_context"));
     return;
   }
+  const { file, line } = ctx;
 
   editor.setStatus(
     editor.t("status.file_loading", { file, hash: commit.shortHash })
@@ -712,56 +1114,37 @@ function git_log_file_view_close(): void {
 registerHandler("git_log_file_view_close", git_log_file_view_close);
 
 // =============================================================================
-// Cursor tracking — live-update the detail panel as the user scrolls through
-// the commit list.
+// Selection tracking — live-update the detail panel as the user
+// navigates the List. Driven by `widget_event "select"` from the host.
 // =============================================================================
 
-async function on_git_log_cursor_moved(data: {
-  buffer_id: number;
-  cursor_id: number;
-  old_position: number;
-  new_position: number;
-}): Promise<void> {
+async function on_log_select(idx: number): Promise<void> {
   if (!state.isOpen) return;
-  // Only react to movement inside the log panel.
-  if (data.buffer_id !== state.logBufferId) return;
-
-  // Map the cursor's byte offset to a commit index via the row-offset
-  // table built in `renderLog`. This avoids relying on `getCursorLine`
-  // which is not implemented for virtual buffers.
-  const idx = indexFromCursorByte(data.new_position);
   if (idx === state.selectedIndex) return;
   state.selectedIndex = idx;
 
-  // Immediate feedback: update the log panel's selection highlight and
-  // either show the cached detail or a "loading" placeholder. Only the
-  // actual `git show` spawn is debounced below, so a burst of j/k events
-  // still feels responsive even though we collapse the fetches into one.
-  renderLog();
-  const pending = refreshDetailImmediate();
-
   const commit = state.commits[state.selectedIndex];
   if (commit) {
     editor.setStatus(
       editor.t("status.commit_position", {
         current: String(state.selectedIndex + 1),
         total: String(state.commits.length),
-      })
+      }),
     );
   }
 
-  if (!pending) return;
-
   // Debounce: bump the token, wait a beat, bail if a newer event has
-  // arrived. `git show` is expensive; a burst of cursor events (held
-  // j/k, PageDown) must collapse to one spawn.
-  const myId = ++state.pendingCursorMoveId;
-  await editor.delay(CURSOR_DEBOUNCE_MS);
-  if (myId !== state.pendingCursorMoveId) return;
+  // arrived. Even though re-pointing the panel at a cached buffer is
+  // ~free, kicking off a new `git show --patch` for every intermediate
+  // row in a held-j burst is wasteful. Collapse rapid selection moves.
+  const myId = ++state.pendingSelectId;
+  await editor.delay(SELECT_DEBOUNCE_MS);
+  if (myId !== state.pendingSelectId) return;
   if (!state.isOpen) return;
-  await fetchAndRenderDetail(pending);
+  const current = state.commits[state.selectedIndex];
+  if (!current) return;
+  await showCommitInDetail(current, editor.getCwd());
 }
-registerHandler("on_git_log_cursor_moved", on_git_log_cursor_moved);
 
 // =============================================================================
 // Command registration
@@ -785,5 +1168,4 @@ editor.registerCommand(
   "git_log_refresh",
   null
 );
-
 editor.debug("Git Log plugin initialized (modern buffer-group layout)");