@tiens.nguyen/gu-cli 1.0.686

package/terminal-hover.mjs

@@ -0,0 +1,153 @@
+/**
+ * Interacting with a printed thought block: what the pointer is over, and what a click does.
+ *
+ * WHY THIS IS ITS OWN MODULE
+ * --------------------------
+ * This logic lived inside gu-repl.mjs, reading half a dozen module-level things directly —
+ * `transcript`, `hoveredThought`, `barPinned()`, `transcriptRows()`. That file has no main
+ * guard, so importing it starts a REPL, which meant the hover rules could not be executed by a
+ * test at all: the only coverage possible was to REIMPLEMENT them beside the real ones and
+ * assert on the copy, plus source-reading to check the two had not drifted.
+ *
+ * That is backwards for the part of the terminal a pointer touches hundreds of times a minute,
+ * and it is the same seam the rest of this codebase already uses where a rule matters:
+ * `pickUsableVersion` takes `usable` injected "so the rule is testable without a filesystem",
+ * and `refreshJobsForClientView` takes its store calls the same way. This is that, for hover.
+ *
+ * BEHAVIOUR IS UNCHANGED. Every rule below was moved, not rewritten, and the byte-level tests
+ * in tests/hover-repaint.test.mjs still stand behind it as the backstop that says the SEQUENCES
+ * are right; these say the DECISIONS are.
+ *
+ * Hover and click are the same feature from two angles — the pointer marks a block, the click
+ * opens it — and they share state: a toggle MOVES rows under a motionless pointer, so it has to
+ * invalidate what hover cached. Keeping them apart would mean keeping that dependency implicit.
+ */
+
+/**
+ * A block was toggled and its rows replaced: fix up every position. → the delta, in lines.
+ *
+ * THE PART WORTH TESTING IS THE ARITHMETIC. Expanding a thought makes it taller, and every
+ * block BELOW it in the transcript moves down by exactly that much. Get the shift wrong and the
+ * blocks below stay clickable at the rows they used to occupy — so a click lands on the wrong
+ * thought, or on nothing, with no error and nothing on screen to explain it.
+ *
+ * `newEnd` comes from the transcript's replaceRange, which is the only thing that knows how many
+ * lines actually landed. Blocks ABOVE are untouched by construction: nothing moved above the
+ * block that changed.
+ *
+ * Mutates in place, because the caller's `thoughtBlocks` array and these objects are the same
+ * ones the hit-test reads — returning copies would leave the live state stale.
+ */
+export function applyToggleShift(blocks, block, newEnd) {
+  const delta = newEnd - block.to;
+  block.collapsed = !block.collapsed;
+  block.to = newEnd;
+  for (const b of blocks ?? []) {
+    if (b !== block && b.from > block.from) {
+      b.from += delta;
+      b.to += delta;
+    }
+  }
+  return delta;
+}
+
+/**
+ * Make a hover controller. All effects are injected — nothing here knows about a terminal.
+ *
+ *   pinned()            → is the bar pinned? Hover is meaningless without a rendered view.
+ *   transcriptRows()    → rows the transcript owns (the scrolling area LESS the live block).
+ *   blockAtRow(row)     → the recorded block under that screen row, or null.
+ *   paintRows(b, on)    → that block's rows, in the hovered or resting colour.
+ *   replaceRange(f,t,r) → swap those recorded lines; null when the range is gone.
+ *   repaintSeq(block)   → bytes that redraw the block where it already sits ("" if off screen).
+ *   write(seq)          → put bytes on screen.
+ *   afterPaint()        → put the caret back where the user is typing.
+ */
+export function createHoverController({
+  pinned = () => true,
+  transcriptRows = () => 1,
+  blockAtRow = () => null,
+  paintRows = () => [],
+  replaceRange = () => null,
+  repaintSeq = () => "",
+  write = () => {},
+  afterPaint = () => {},
+} = {}) {
+  // The block the pointer is currently over, or null. Only ever ONE — highlighting two would
+  // say two things are about to happen.
+  let hovered = null;
+  let lastKey = "";
+
+  /**
+   * The pointer moved to `row`. → true when something was repainted.
+   *
+   * HIGHLIGHT ONLY. Hovering does not expand: expanding reflows everything below it, and a
+   * transcript that rearranges itself as the mouse crosses the screen is unusable. It is also
+   * the one thing an in-place repaint cannot express — the block's rows are rewritten where
+   * they are, so a block that changed HEIGHT would corrupt every row beneath it.
+   */
+  function hover(row) {
+    if (!pinned()) return false;
+
+    // A pointer crossing the window sends a report per CELL, and resolving a row to a block
+    // wraps the entire transcript — so doing that per report would burn real CPU on a mouse
+    // only passing through. The row is the cheap key: nothing can change until it does.
+    //
+    // …EXCEPT THE LIVE BLOCK'S HEIGHT, which is why that is in the key too. It grows and
+    // shrinks as a step's detail lines come and go, and every transcript row above it moves
+    // when it does — so a STILL pointer is over a different line than it was, and a row-only
+    // key would hold the highlight on the block it used to be over.
+    const key = `${row}:${transcriptRows()}`;
+    if (key === lastKey) return false;
+    lastKey = key;
+
+    const block = blockAtRow(row);
+    if (block === hovered) return false;
+    const previous = hovered;
+    hovered = block;
+
+    // Recolour both: the one being left and the one being entered. Same row count either way
+    // (only the colour changed), so neither range can move — which is what makes repainting
+    // them in place safe.
+    let touched = false;
+    for (const [b, on] of [[previous, false], [block, true]]) {
+      if (!b) continue;
+      if (replaceRange(b.from, b.to, paintRows(b, on)) !== null) touched = true;
+    }
+    if (!touched) return false;
+
+    // COLOUR ONLY, IN PLACE. The two blocks whose colour just changed are redrawn where they
+    // already are; every other row is left untouched. Repainting the whole view here is the
+    // #211 bug: it bottom-aligns the transcript and re-saves the output position, so the next
+    // printed line lands on rows that already have content.
+    let seq = "";
+    for (const b of [previous, block]) if (b) seq += repaintSeq(b);
+    if (!seq) return false;
+    write(seq);
+    afterPaint();
+    return true;
+  }
+
+  return {
+    hover,
+    /** The block under the pointer, or null. */
+    get hovered() {
+      return hovered;
+    },
+    /**
+     * Forget the cached row.
+     *
+     * Called by anything that MOVES rows under a motionless pointer — a block growing as its
+     * prose is appended, or one expanding on a click. Without it the next report at the same
+     * row is treated as "nothing changed" and the highlight is stranded on the old block.
+     */
+    reset() {
+      lastKey = "";
+    },
+    /** Drop the highlight entirely (the view was rebuilt; nothing is under the pointer). */
+    clear() {
+      hovered = null;
+      lastKey = "";
+    },
+  };
+}