feat: click a page to read it, and a link in one to open it

The terminal has a pointer and Ink does not know it, so the reader asks for SGR
mouse reporting itself: the terminal then sends a CSI sequence per click and per
wheel notch, and Ink hands each one to `useInput` whole. Reading the pointer is
parsing a string, and the panes' geometry is what turns a row back into the page
that was clicked. The wheel answers to the pointer rather than to the focus:
whatever sits under it is what moves.

Links carry their target now, resolved against the page they were written on, so
a click on one opens it. They are also OSC 8 hyperlinks, which costs a sequence
Ink passes through untouched and no width at all: a terminal that speaks it
underlines the label and opens the URL on its own, and one that does not prints
the label alone, as before.

In exchange the terminal stops selecting text on its own -- that needs the usual
modifier held down while the reader is up.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F9YQGrxNQLRHRLarpzJXLm

Author: abernier

.changeset/cli-browse.md

@@ -6,7 +6,7 @@ Read the published pmndrs documentation from the terminal: `npx @pmndrs/docs`.
 
 Two new commands, both reading each library's published `llms-full.txt` — one GET per library, cached for an hour under `~/.cache/pmndrs-docs`, `--refresh` to fetch again:
 
-- `browse [target]`, the default command, is a reader: pages on the left, the page on the right, `b` folds the sidebar away, `/` searches every library at once, `o` opens the page in a browser. A target lands straight where it points — `drei`, `drei/performances/instances`, or a query.
+- `browse [target]`, the default command, is a reader: pages on the left, the page on the right, `b` folds the sidebar away, `/` searches every library at once, `o` opens the page in a browser. A target lands straight where it points — `drei`, `drei/performances/instances`, or a query. The mouse works too: click a page to read it, click a link in one to open it, and the wheel turns whichever pane it sits over — and links are terminal hyperlinks, so a terminal that speaks OSC 8 opens them on its own.
 - `search <query>` is the same search with no screen: one result per line on stdout, in the `{lib} {path} - {title}` shape the MCP server publishes its index in, so a pipe or an agent can read it. `--in` narrows to a library, or to the matching lines of a single page.
 
 Outside a terminal `browse` writes the page it was pointed at to stdout, rather than opening anything.

README.md

@@ -21,6 +21,11 @@ hands the focus over, `esc` or `⇥` hands it back, and the lit border says wher
 changes library, `b` folds the sidebar away, `/` searches every library at once, `o` opens the
 page in a browser, `q` quits.
 
+The mouse works too: click a page to read it, click a link in one to open it, and the wheel
+turns whichever pane it sits over. Links are terminal hyperlinks as well, so a terminal that
+speaks OSC 8 opens them on its own. Selecting text needs the usual modifier held down (⌥ in
+iTerm2, ⇧ elsewhere) while the reader is asking for the pointer.
+
 `search` is the half a pipe or an agent can use: results read `{lib} {path} - {title}`, the
 shape the [MCP server](https://docs.pmnd.rs) publishes its index in, and nothing found exits 1.
 `--in drei` narrows to one library, `--in drei/performances/instances` to the matching lines of

src/cli/browse.lines.tsx

@@ -1,7 +1,7 @@
 // The styled-line model, as Ink. `toAnsi` is the same lines for a pager.
 
 import { Text } from 'ink'
-import type { Line } from './browse.markdown'
+import { hyperlink, type Line } from './browse.markdown'
 
 export function Lines({ lines }: { lines: Line[] }) {
   return (
@@ -20,7 +20,7 @@ export function Lines({ lines }: { lines: Line[] }) {
                   italic={span.italic}
                   underline={span.underline}
                 >
-                  {span.text}
+                  {span.href ? hyperlink(span.text, span.href) : span.text}
                 </Text>
               ))}
         </Text>

src/cli/browse.list.tsx

@@ -8,6 +8,18 @@ export interface Row {
   hint?: string
 }
 
+/**
+ * The first row a list of `length` shows, given where its cursor is.
+ *
+ * The window is the whole of the list's scrolling: what it shows follows the cursor rather
+ * than a scroll of its own. A pointer needs it too -- it is what turns a screen row back into
+ * the row of the list that was clicked.
+ */
+export function listWindowStart(cursor: number, length: number, height: number) {
+  const window = Math.max(1, height)
+  return Math.max(0, Math.min(cursor - Math.floor(window / 2), length - window))
+}
+
 /** A list of `height` rows that keeps the cursor in view, centred when it can be. */
 export function List({
   rows,
@@ -21,7 +33,7 @@ export function List({
   focused?: boolean
 }) {
   const window = Math.max(1, height)
-  const start = Math.max(0, Math.min(cursor - Math.floor(window / 2), rows.length - window))
+  const start = listWindowStart(cursor, rows.length, height)
 
   return (
     <Box flexDirection="column" height={window} flexShrink={0}>

src/cli/browse.markdown.test.ts

@@ -1,8 +1,13 @@
 import { expect, test } from 'vitest'
-import { plain, renderMarkdown, toAnsi, type Line } from './browse.markdown'
+import { plain, renderMarkdown, spanAt, toAnsi, type Line } from './browse.markdown'
 
 const WIDTH = 80
 
+const ESC = String.fromCharCode(27)
+const BEL = String.fromCharCode(7)
+const HYPERLINK = new RegExp(`${ESC}\\]8;;[^${BEL}]*${BEL}`, 'g')
+const SGR = new RegExp(`${ESC}\\[[\\d;]*m`, 'g')
+
 test('renders a heading in its own colour, over a rule', () => {
   const lines = renderMarkdown('## Getting started', WIDTH)
   const heading = lines.find((line) => line[0]?.text === 'Getting started')
@@ -42,6 +47,56 @@ test('renders a link as its underlined label, without the URL', () => {
   expect(lines.flat().find((span) => span.underline)?.text).toBe('the docs')
 })
 
+test('a link keeps its target, resolved against the page it was written on', () => {
+  const base = 'https://pmndrs.github.io/drei/performances/instances'
+  const lines = renderMarkdown(
+    'see [the docs](/getting-started) and [three](https://threejs.org)',
+    80,
+    base,
+  )
+  const links = lines.flat().filter((span) => span.href)
+
+  expect(links.map((span) => span.href)).toEqual([
+    'https://pmndrs.github.io/getting-started',
+    'https://threejs.org/',
+  ])
+})
+
+test('with no page to resolve against, only an absolute link keeps its target', () => {
+  const lines = renderMarkdown('[near](/getting-started) and [far](https://threejs.org)', WIDTH)
+  const spans = lines.flat()
+
+  expect(plain(lines)).toEqual(['near and far'])
+  expect(spans.find((span) => span.text === 'near')?.href).toBeUndefined()
+  expect(spans.find((span) => span.text === 'far')?.href).toBe('https://threejs.org')
+})
+
+test('two links side by side stay two links', () => {
+  const lines = renderMarkdown('[one](https://a.example) [two](https://b.example)', WIDTH)
+
+  expect(lines.flat().filter((span) => span.href).length).toBe(2)
+})
+
+test('a linked span is a terminal hyperlink, printing the label alone', () => {
+  const lines = renderMarkdown('see [the docs](https://docs.pmnd.rs) for more', WIDTH)
+  const ansi = toAnsi(lines)
+
+  // ESC ] 8 ; ; URL BEL label ESC ] 8 ; ; BEL -- the URL travels inside the sequence, so what
+  // the terminal shows is the label, and the label is what a click follows
+  expect(ansi).toContain(`${ESC}]8;;https://docs.pmnd.rs${BEL}the docs${ESC}]8;;${BEL}`)
+  expect(ansi.replace(HYPERLINK, '').replace(SGR, '')).toBe('see the docs for more')
+})
+
+test('spanAt finds what sits at a column, and nothing past the end of the line', () => {
+  const [line] = renderMarkdown('see [the docs](https://docs.pmnd.rs) here', WIDTH)
+
+  expect(spanAt(line, 0)?.text).toBe('see ')
+  expect(spanAt(line, 5)?.href).toBe('https://docs.pmnd.rs')
+  expect(spanAt(line, 11)?.href).toBe('https://docs.pmnd.rs')
+  expect(spanAt(line, 12)?.href).toBeUndefined()
+  expect(spanAt(line, 999)).toBeUndefined()
+})
+
 test('renders a blockquote behind a gutter', () => {
   const lines = renderMarkdown('> mind the gap', WIDTH)
 

src/cli/browse.markdown.ts

@@ -9,6 +9,8 @@
 
 export interface Span {
   text: string
+  /** Where the span points, absolute. A link, and nothing else, has one. */
+  href?: string
   fg?: string
   bold?: boolean
   dim?: boolean
@@ -35,7 +37,23 @@ const BADGE_ROW = /^\s*(\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)\s*)+$/
 /** Inline `code`, [label](href), **bold** and _emphasis_, in one left-to-right pass. */
 const INLINE_TOKEN = /(`[^`]+`)|(\[([^\]]*)\]\(([^)]+)\))|(\*\*[^*]+\*\*)|(_[^_]+_)/g
 
-function inline(text: string): Span[] {
+/**
+ * A link's target as a browser can follow it.
+ *
+ * Docs link to each other with a path (`/getting-started/introduction`), which only means
+ * something next to the page it was written on -- so a link is worth keeping only when there
+ * is a page to resolve it against.
+ */
+function resolve(href: string, base: string | undefined): string | undefined {
+  if (!base) return /^[a-z][\w+.-]*:/i.test(href) ? href : undefined
+  try {
+    return new URL(href, base).href
+  } catch {
+    return undefined
+  }
+}
+
+function inline(text: string, base?: string): Span[] {
   const spans: Span[] = []
   let last = 0
 
@@ -44,9 +62,15 @@ function inline(text: string): Span[] {
     if (at > last) spans.push({ text: text.slice(last, at) })
 
     if (match[1]) spans.push({ text: match[1].slice(1, -1), fg: theme.code })
-    // A link keeps its label, or its href when it has no label. The URL itself is not
-    // clickable in a pager, and spelling it out costs more width than it is worth.
-    else if (match[2]) spans.push({ text: match[3] || match[4], fg: theme.link, underline: true })
+    // A link keeps its label, or its href when it has no label: spelling the URL out next to
+    // the label costs more width than it is worth, and the href travels with the span anyway
+    else if (match[2])
+      spans.push({
+        text: match[3] || match[4],
+        href: resolve(match[4], base),
+        fg: theme.link,
+        underline: true,
+      })
     else if (match[5]) spans.push({ text: match[5].slice(2, -2), bold: true })
     else if (match[6]) spans.push({ text: match[6].slice(1, -1), italic: true })
 
@@ -58,6 +82,7 @@ function inline(text: string): Span[] {
 }
 
 const sameStyle = (a: Span, b: Span) =>
+  a.href === b.href &&
   a.fg === b.fg &&
   !!a.bold === !!b.bold &&
   !!a.dim === !!b.dim &&
@@ -135,7 +160,7 @@ function demoMarker(folder: string | undefined): Line {
   return line
 }
 
-function renderBlocks(source: string[], width: number): Line[] {
+function renderBlocks(source: string[], width: number, base?: string): Line[] {
   const out: Line[] = []
   let i = 0
 
@@ -197,7 +222,7 @@ function renderBlocks(source: string[], width: number): Line[] {
 
     const bullet = line.match(/^(\s*)[-*]\s+(.*)$/)
     if (bullet) {
-      out.push(...wrap(inline(bullet[2]), width, `${bullet[1]}  • `))
+      out.push(...wrap(inline(bullet[2], base), width, `${bullet[1]}  • `))
       i++
       continue
     }
@@ -216,7 +241,7 @@ function renderBlocks(source: string[], width: number): Line[] {
       continue
     }
 
-    out.push(...wrap(inline(line), width))
+    out.push(...wrap(inline(line, base), width))
     i++
   }
 
@@ -226,10 +251,14 @@ function renderBlocks(source: string[], width: number): Line[] {
 /**
  * Renders one markdown body to styled lines, wrapped to `width` columns.
  *
+ * `base` is the URL the body was published at, and it is what turns the relative links a page
+ * makes to its neighbours into links something can follow. Without it, only the absolute ones
+ * survive as links.
+ *
  * Never throws: any input renders, and anything malformed degrades to the plain text it was
  * written as. A reader is not allowed to die on a page.
  */
-export function renderMarkdown(body: string, width: number): Line[] {
+export function renderMarkdown(body: string, width: number, base?: string): Line[] {
   const source = String(body ?? '')
     .replace(/\r\n?/g, '\n')
     // Pages come out of the corpus behind their own `URL:`/`Description:` header.
@@ -241,15 +270,45 @@ export function renderMarkdown(body: string, width: number): Line[] {
   const columns = Number.isFinite(width) && width >= 1 ? Math.floor(width) : 1
 
   try {
-    return renderBlocks(source, columns)
+    return renderBlocks(source, columns, base)
   } catch {
     return source.map((line) => [{ text: line }])
   }
 }
 
+/**
+ * The span covering `column`, counting from the start of the line, or nothing past its end.
+ *
+ * This is how a pointer lands on a word: the reader knows where a line starts on screen, and
+ * the line knows what sits at each of its columns.
+ */
+export function spanAt(line: Line, column: number): Span | undefined {
+  let at = 0
+  for (const span of line) {
+    at += span.text.length
+    if (column < at) return span
+  }
+  return undefined
+}
+
 const RESET = '\x1b[0m'
 const HEX = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i
 
+const OSC = '\x1b]8;;'
+const BEL = '\x07'
+
+/**
+ * Marks `text` as a link to `href`, the way OSC 8 does.
+ *
+ * The terminal is what makes it clickable, so this costs no width, no key and no code: a
+ * terminal that speaks OSC 8 underlines the label and opens the URL on a click, and one that
+ * does not prints the label alone. Ink passes the sequence through untouched, and measures
+ * the text as if it were not there.
+ */
+export function hyperlink(text: string, href: string): string {
+  return `${OSC}${href}${BEL}${text}${OSC}${BEL}`
+}
+
 function ansi(span: Span): string {
   let codes = ''
 
@@ -263,7 +322,8 @@ function ansi(span: Span): string {
   if (span.italic) codes += '\x1b[3m'
   if (span.underline) codes += '\x1b[4m'
 
-  return codes ? codes + span.text + RESET : span.text
+  const text = span.href ? hyperlink(span.text, span.href) : span.text
+  return codes ? codes + text + RESET : text
 }
 
 /** Serializes lines to one ANSI string, for a pager or a plain `stdout` write. */

src/cli/browse.mouse.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from 'vitest'
+import { parseMouse } from './browse.mouse'
+
+/** What Ink hands over: the sequence the terminal sent, minus its leading escape. */
+const event = (button: number, column: number, row: number, final = 'M') =>
+  `[<${button};${column};${row}${final}`
+
+test('reads a left click, in coordinates counting from zero', () => {
+  expect(parseMouse(event(0, 12, 7))).toEqual({ kind: 'click', column: 11, row: 6 })
+})
+
+test('reads the wheel, both ways', () => {
+  expect(parseMouse(event(64, 1, 1))?.kind).toBe('wheel-up')
+  expect(parseMouse(event(65, 1, 1))?.kind).toBe('wheel-down')
+})
+
+test('a click counts once: the release that ends it is not a second one', () => {
+  expect(parseMouse(event(0, 12, 7, 'm'))).toBeUndefined()
+})
+
+test('a modifier held down changes nothing about the click', () => {
+  // shift (4), meta (8) and ctrl (16) ride in the same number as the button
+  expect(parseMouse(event(0 + 4 + 16, 12, 7))).toEqual({ kind: 'click', column: 11, row: 6 })
+})
+
+test('leaves alone what it has no answer for', () => {
+  expect(parseMouse(event(2, 12, 7))).toBeUndefined() // right button
+  expect(parseMouse(event(66, 12, 7))).toBeUndefined() // sideways wheel
+  expect(parseMouse(event(32, 12, 7))).toBeUndefined() // a drag
+  expect(parseMouse('j')).toBeUndefined()
+  expect(parseMouse('[A')).toBeUndefined()
+})
+
+test('reads a column past the 223 an older encoding could report', () => {
+  expect(parseMouse(event(0, 400, 300))).toEqual({ kind: 'click', column: 399, row: 299 })
+})

src/cli/browse.mouse.ts

@@ -0,0 +1,50 @@
+// The terminal has a pointer; Ink does not know it. Asking for SGR mouse reporting makes the
+// terminal send one CSI sequence per click and per wheel notch, and Ink hands each of them to
+// `useInput` whole, with its ESC already stripped -- so reading the pointer is reading a
+// string, and the reader needs no second listener on stdin.
+
+/** Turns click and wheel reporting on. SGR (1006) is what lifts the 223-column limit. */
+export const MOUSE_ON = '\x1b[?1000h\x1b[?1006h'
+
+/** And off again -- left set, the terminal keeps reporting into whatever runs next. */
+export const MOUSE_OFF = '\x1b[?1006l\x1b[?1000l'
+
+export interface Mouse {
+  kind: 'click' | 'wheel-up' | 'wheel-down'
+  /** Both 0-based, from the top-left corner of the terminal, as Ink lays it out. */
+  column: number
+  row: number
+}
+
+/** `[<button;column;rowM` — a press, or `m`, its release. Columns and rows count from 1. */
+const SGR_MOUSE = /^\[<(\d+);(\d+);(\d+)([Mm])$/
+
+/** Modifiers ride in bits 2-4 of the button, and say nothing about where the pointer is. */
+const BUTTON = 0b1000011
+
+/** Bit 5 marks a move rather than a press -- a drag has nothing here to drag. */
+const MOTION = 0b100000
+
+/**
+ * The pointer event `input` carries, or nothing when it carries none.
+ *
+ * Only what the reader acts on comes back: the press of the left button, and the wheel. A
+ * release repeats the press that it ends, and a drag would move a cursor with nothing to drag.
+ */
+export function parseMouse(input: string): Mouse | undefined {
+  const match = input.match(SGR_MOUSE)
+  if (!match) return undefined
+
+  // A wheel notch reports as a press with no release, so acting on presses alone still counts
+  // every notch -- and counts a click once rather than twice.
+  if (match[4] !== 'M') return undefined
+
+  if (Number(match[1]) & MOTION) return undefined
+
+  const button = Number(match[1]) & BUTTON
+  const kind =
+    button === 64 ? 'wheel-up' : button === 65 ? 'wheel-down' : button === 0 ? 'click' : undefined
+  if (!kind) return undefined
+
+  return { kind, column: Number(match[2]) - 1, row: Number(match[3]) - 1 }
+}