jaitus 0.3.0 → 0.3.1

package/src/tui/mouse.js

@@ -1,125 +1,150 @@
-// ─── Mouse ──────────────────────────────────────────────────────────────────────
-//
-// Ink has no mouse support, so this is the whole of it: turn the terminal's reporting
-// on, recognise the sequences when they arrive through the ordinary key handler, and
-// turn it off again on the way out.
-//
-// Two things make that safe to do:
-//
-//   • **SGR extended mode (1006) or nothing.** The original X10 encoding packs the
-//     coordinates into single bytes offset by 32, so it cannot report a click past
-//     column 223 — on a wide terminal the right-hand half of the screen silently stops
-//     responding. Every terminal worth enabling this for has supported 1006 for a
-//     decade; the ones that do not simply get no mouse, which is the honest outcome.
-//   • **The sequences arrive as ordinary input.** Ink's key parser does not recognise
-//     them, so it hands them through as a plain string with the leading escape stripped.
-//     That is lucky rather than designed, and it is why the guard below runs before
-//     anything can insert them into the composer — without it, scrolling the wheel types
-//     `[<64;10;5M` into your prompt.
-//
-// Enabling mouse reporting takes over the terminal's own text selection. That is a real
-// cost, not a detail: people select and copy out of a terminal constantly. Hold Shift to
-// get the native behaviour back in every terminal that supports this, and `/mouse off`
-// turns it off for good.
-
-// Button-event tracking (1002) rather than any-event (1003): 1003 reports every pixel of
-// pointer motion, which on a busy screen is thousands of writes a second for information
-// nothing here uses.
-const ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
-const OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
-
-// Ink strips the leading escape, so both spellings have to match.
-const SGR = /^\x1b?\[<(\d+);(\d+);(\d+)([Mm])$/;
-
-// The X10 encoding: `CSI M` followed by three raw bytes. A terminal that does not
-// understand the 1006 request still honours 1000 and reports in this form — and those
-// bytes are unprintable garbage that would otherwise be typed into the composer. It is
-// recognised only to be swallowed: its coordinates top out at column 223, which makes
-// it useless for anything but ignoring.
-const X10 = /^\x1b?\[M[\s\S]{3}$/;
-
-/** True once, per process: never write the disable sequence for something never enabled. */
-let enabled = false;
-
-export function enableMouse(stream = process.stdout) {
-  if (enabled || !stream?.isTTY) return false;
-  try { stream.write(ON); enabled = true; } catch { /* not a real terminal */ }
-  return enabled;
-}
-
-export function disableMouse(stream = process.stdout) {
-  if (!enabled) return;
-  try { stream.write(OFF); } catch { /* going away anyway */ }
-  enabled = false;
-}
-
-export const mouseEnabled = () => enabled;
-
-/**
- * One input string → a mouse event, or null.
- *
- * The button field is a bitfield: the low two bits are which button, bit 5 (32) means
- * the pointer was moving with a button held, and bit 6 (64) means the wheel. Shift, Alt
- * and Ctrl ride in bits 2–4 and are reported so a Shift-click can mean something
- * different from a click.
- */
-export function parseMouse(input) {
-  const m = SGR.exec(String(input ?? ''));
-  if (!m) return null;
-  const code = Number(m[1]);
-  const x = Number(m[2]);
-  const y = Number(m[3]);
-  const pressed = m[4] === 'M';
-
-  const wheel = (code & 64) !== 0;
-  const motion = (code & 32) !== 0;
-  const button = code & 3;
-
-  return {
-    x,
-    y,
-    shift: (code & 4) !== 0,
-    meta: (code & 8) !== 0,
-    ctrl: (code & 16) !== 0,
-    // A wheel "button" of 0 is up and 1 is down; 2 and 3 are horizontal tilt, which is
-    // reported so a future horizontal scroll has somewhere to go rather than being
-    // silently read as a vertical one.
-    kind: wheel
-      ? (button === 0 ? 'wheelUp' : button === 1 ? 'wheelDown' : button === 2 ? 'wheelLeft' : 'wheelRight')
-      : motion ? 'drag'
-        : pressed ? 'down' : 'up',
-    button: wheel ? null : button === 0 ? 'left' : button === 1 ? 'middle' : button === 2 ? 'right' : null,
-  };
-}
-
-/** Does this input look like a mouse report we should swallow rather than type? */
-export const isMouse = (input) => {
-  const s = String(input ?? '');
-  return SGR.test(s) || X10.test(s);
-};
-
-/**
- * A hit map for one frame.
- *
- * The layout is computed in one place, so the regions can be computed there too rather
- * than measured afterwards. Rows and columns are 1-based to match what the terminal
- * reports, and later registrations win — which is what makes an overlay's buttons
- * reachable while the header underneath it is not.
- */
-export function createHitMap() {
-  let regions = [];
-  return {
-    reset() { regions = []; },
-    add(region) { if (region && region.action) regions.push(region); },
-    /** The topmost region containing this cell, or null. */
-    at(x, y) {
-      for (let i = regions.length - 1; i >= 0; i--) {
-        const r = regions[i];
-        if (x >= r.x1 && x <= r.x2 && y >= r.y1 && y <= r.y2) return r;
-      }
-      return null;
-    },
-    get size() { return regions.length; },
-    all() { return regions.slice(); },
-  };
-}
+// ─── Mouse ──────────────────────────────────────────────────────────────────────
+//
+// Ink has no mouse support, so this is the whole of it: turn the terminal's reporting
+// on, recognise the sequences when they arrive through the ordinary key handler, and
+// turn it off again on the way out.
+//
+// Two things make that safe to do:
+//
+//   • **SGR extended mode (1006) or nothing.** The original X10 encoding packs the
+//     coordinates into single bytes offset by 32, so it cannot report a click past
+//     column 223 — on a wide terminal the right-hand half of the screen silently stops
+//     responding. Every terminal worth enabling this for has supported 1006 for a
+//     decade; the ones that do not simply get no mouse, which is the honest outcome.
+//   • **The sequences arrive as ordinary input.** Ink's key parser does not recognise
+//     them, so it hands them through as a plain string with the leading escape stripped.
+//     That is lucky rather than designed, and it is why the guard below runs before
+//     anything can insert them into the composer — without it, scrolling the wheel types
+//     `[<64;10;5M` into your prompt.
+//
+// Enabling mouse reporting takes over the terminal's own text selection. That is a real
+// cost, not a detail: people select and copy out of a terminal constantly. Hold Shift to
+// get the native behaviour back in every terminal that supports this, and `/mouse off`
+// turns it off for good.
+
+// Button-event tracking (1002) rather than any-event (1003): 1003 reports every pixel of
+// pointer motion, which on a busy screen is thousands of writes a second for information
+// nothing here uses.
+const ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
+const OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
+
+// Ink strips the leading escape, so both spellings have to match.
+const SGR = /^\x1b?\[<(\d+);(\d+);(\d+)([Mm])$/;
+
+// The X10 encoding: `CSI M` followed by three raw bytes, each offset by 32. A terminal
+// that does not understand the 1006 request still honours 1000 and reports in this
+// form. It is decoded rather than swallowed: its coordinates stop at column 223, but
+// below that it is a perfectly good report, and swallowing it meant a terminal without
+// 1006 had no selection at all AND no native one, because reporting was still on.
+const X10 = /^\x1b?\[M([\s\S])([\s\S])([\s\S])$/;
+
+// A report the input layer delivered in pieces. Ink holds an unfinished escape sequence
+// for only 20ms before passing it through as typed text, so a report split across two
+// reads — a busy machine, SSH, a fast trackpad drag — arrived as two halves: the drag
+// was lost and the second half was typed into the prompt as `[<32;15;13M`.
+const SGR_FRAGMENT = /^\x1b?\[<[\d;]*$/;
+const X10_FRAGMENT = /^\x1b?\[M[\s\S]{0,2}$/;
+
+/** True once, per process: never write the disable sequence for something never enabled. */
+let enabled = false;
+
+export function enableMouse(stream = process.stdout) {
+  if (enabled || !stream?.isTTY) return false;
+  try { stream.write(ON); enabled = true; } catch { /* not a real terminal */ }
+  return enabled;
+}
+
+export function disableMouse(stream = process.stdout) {
+  if (!enabled) return;
+  try { stream.write(OFF); } catch { /* going away anyway */ }
+  enabled = false;
+}
+
+export const mouseEnabled = () => enabled;
+
+/**
+ * One input string → a mouse event, or null.
+ *
+ * The button field is a bitfield: the low two bits are which button, bit 5 (32) means
+ * the pointer was moving with a button held, and bit 6 (64) means the wheel. Shift, Alt
+ * and Ctrl ride in bits 2–4 and are reported so a Shift-click can mean something
+ * different from a click.
+ */
+export function parseMouse(input) {
+  const s = String(input ?? '');
+  let code, x, y, pressed;
+  const m = SGR.exec(s);
+  if (m) {
+    code = Number(m[1]);
+    x = Number(m[2]);
+    y = Number(m[3]);
+    pressed = m[4] === 'M';
+  } else {
+    const o = X10.exec(s);
+    if (!o) return null;
+    code = o[1].charCodeAt(0) - 32;
+    x = o[2].charCodeAt(0) - 32;
+    y = o[3].charCodeAt(0) - 32;
+    // X10 has no release suffix: a release is button 3, and it does not say which.
+    pressed = (code & 3) !== 3 || (code & 64) !== 0;
+    if (x < 1 || y < 1) return null;
+  }
+
+  const wheel = (code & 64) !== 0;
+  const motion = (code & 32) !== 0;
+  const button = code & 3;
+
+  return {
+    x,
+    y,
+    shift: (code & 4) !== 0,
+    meta: (code & 8) !== 0,
+    ctrl: (code & 16) !== 0,
+    // A wheel "button" of 0 is up and 1 is down; 2 and 3 are horizontal tilt, which is
+    // reported so a future horizontal scroll has somewhere to go rather than being
+    // silently read as a vertical one.
+    kind: wheel
+      ? (button === 0 ? 'wheelUp' : button === 1 ? 'wheelDown' : button === 2 ? 'wheelLeft' : 'wheelRight')
+      : motion ? 'drag'
+        : pressed ? 'down' : 'up',
+    button: wheel ? null : button === 0 ? 'left' : button === 1 ? 'middle' : button === 2 ? 'right' : null,
+  };
+}
+
+/** The start of a mouse report whose remainder has not arrived yet. */
+export const isMouseFragment = (input) => {
+  const s = String(input ?? '');
+  return (SGR_FRAGMENT.test(s) || X10_FRAGMENT.test(s)) && !SGR.test(s) && !X10.test(s);
+};
+
+/** Does this input look like a mouse report we should swallow rather than type? */
+export const isMouse = (input) => {
+  const s = String(input ?? '');
+  return SGR.test(s) || X10.test(s);
+};
+
+/**
+ * A hit map for one frame.
+ *
+ * The layout is computed in one place, so the regions can be computed there too rather
+ * than measured afterwards. Rows and columns are 1-based to match what the terminal
+ * reports, and later registrations win — which is what makes an overlay's buttons
+ * reachable while the header underneath it is not.
+ */
+export function createHitMap() {
+  let regions = [];
+  return {
+    reset() { regions = []; },
+    add(region) { if (region && region.action) regions.push(region); },
+    /** The topmost region containing this cell, or null. */
+    at(x, y) {
+      for (let i = regions.length - 1; i >= 0; i--) {
+        const r = regions[i];
+        if (x >= r.x1 && x <= r.x2 && y >= r.y1 && y <= r.y2) return r;
+      }
+      return null;
+    },
+    get size() { return regions.length; },
+    all() { return regions.slice(); },
+  };
+}